BooksAPI.com

Marketplace API

Buy and sell books without mixing catalog and commerce.

Connect works and editions to seller-owned offers, physical copies, transparent condition, prices, reservations, orders, shipping, returns, and moderation.

Read the marketplace article

Resource map

Catalog

Work, edition, contributor, identifier, cover, subject, and source claim.

Seller

Account, store profile, verification state, permissions, payout eligibility, and policy status.

Inventory

Physical item or interchangeable stock, seller SKU, condition, defects, images, location, and quantity.

Commerce

Offer, price, currency, reservation, cart, order, payment state, shipment, return, and dispute.

One edition, many offers

Catalog fields describe the publication. Offer fields describe a seller’s terms. A signed used copy, a new retailer unit, and a damaged ex-library copy can point to the same edition while keeping separate condition, price, images, and fulfillment. Unique copies need item IDs; interchangeable new stock can use quantity.

Condition as structured evidence

Publish a versioned condition rubric and combine grades with defect flags, seller notes, photographs, and reviewer status. Record who assigned the grade. Automated image suggestions should remain suggestions unless a real inspection process verifies them.

Transactional integrity

Before checkout, atomically revalidate offer status, price, quantity, seller eligibility, and shipping terms. Create time-limited reservations for unique copies. Use idempotency keys on checkout, payment webhooks, inventory changes, and refunds. Preserve an immutable listing snapshot on the order.

1. Match edition
2. Create item + evidence
3. Activate offer
4. Reserve + pay
5. Ship + resolve returns

Search and comparison

Offer comparison should normalize edition, condition, currency, shipping, location, and included materials. “Lowest price” can mean item price or estimated delivered price; name the metric. Price guidance should be a range with evidence, not a guaranteed appraisal.

Trust and safety

Keep sensitive seller verification in restricted services. Public APIs expose only buyer-relevant trust signals. Model policy actions separately for offer removal, catalog review, seller restriction, legal hold, and dispute outcome. Never fabricate ratings, reviews, sales counts, or inspection claims.

Suggested endpoints

  • POST /v1/items create a physical copy or stock unit.
  • POST /v1/offers publish price and terms.
  • GET /v1/editions/{id}/offers compare active offers.
  • POST /v1/reservations hold inventory safely.
  • POST /v1/orders create an idempotent transaction.
  • POST /v1/returns start an evidence-backed return.