Skip to content

Reading the Commerce catalogue

Commerce is a headless engine: it holds your catalogue, stock and prices, and your site or app is the shop. The delivery API is how that site reads the catalogue. It is read-only. There is no cart or checkout in it.

Prefer a client to hand-built URLs: @ebitex/commerce-sdk for JavaScript, in a browser or on a server, and Ebitex.Commerce.Delivery for .NET. Both build the queries below, page with a cursor for you, and report errors with the codes in this page.

A store is the unit a key reads. An organization can have several, each with its own currency and its own list of products. A delivery key is bound to exactly one store and reads nothing outside it.

Open Commerce, choose Delivery keys, pick the store and create a key. The secret is shown once. Send it as a bearer token:

GET /commerce/delivery/v1/products
Authorization: Bearer <your key>

There are two kinds of key, and what you restrict decides which you have.

Kind How you make it What it reads
Server key No origin and no IP restriction The catalogue, and exact stock counts
Browser-safe key One or more allowed origins, or allowed IP ranges The catalogue and each variant’s stock status; exact counts only if the store allows it

A browser-safe key can sit in the code you send to a browser, because it only works from the origins you listed. A server key must never reach a browser.

A key sees the products its store lists that are active, and for each only its active variants. A draft, an archived or an unlisted product answers exactly as a product that does not exist: 404 product_not_found for a product, and absent from every list and batch. A key cannot learn that one is there.

GET /commerce/delivery/v1/products lists products a page at a time. search matches the start of a name, category takes a category path from GET /categories, sort is name or createdUtc, and limit is 1 to 100. Each page ends with nextCursor, which is null on the last; send it back as cursor with exactly the same other parameters for the next page. A cursor is bound to its query, and no product repeats or is skipped because another was added in between.

GET /commerce/delivery/v1/products?search=trail&sort=name&limit=12

GET /commerce/delivery/v1/products?keys=trail-runner,road-runner reads up to 50 products by key in one round trip, in the order asked, with the keys that are not available listed under missing. GET /commerce/delivery/v1/products/{key} reads one. GET /commerce/delivery/v1/store names the store and its currency, and GET /commerce/delivery/v1/categories lists the categories its products use.

A product carries attributes (the document you authored against its product type), media, axes (the options, such as Size, with their values) and variants. Media are references to Assets items, { provider, key, position }, with position 0 the primary image: Commerce stores no files, so resolve the reference through Assets.

Catalogue responses carry an ETag. Send it back as If-None-Match and an unchanged answer is 304. They are private, no-cache: revalidate rather than store.

A price is whole minor units beside a currency, and the same amount as the store’s own decimal string:

{ "amountMinor": 8950, "currency": "GBP", "amount": "89.50", "taxIncluded": true, "compareAtMinor": 9900, "compareAt": "99.00" }

Show amount, and do arithmetic on amountMinor. A floating-point number is never used for money. taxIncluded says whether the price you set already includes tax, which is the store’s setting. A variant with no price in the store has price: null: it is unpriced, which is not the same as free.

A store has one currency of its own and may sell in others. GET /commerce/delivery/v1/store lists them in currencies, the store’s own first. Add currency=EUR to a product read to price it in one of them; leave it off for the store’s own. If the merchant set a price for that currency by hand it is returned as set. Otherwise the store’s own price is converted at the merchant’s rate and rounded to the smallest unit of the target currency, half up. A variant that cannot be converted is unpriced, never guessed. A currency the store does not sell in is 400 invalid_currency.

Each variant carries availability: inStock, backorder or outOfStock. It is a status and never a count, and a variant that is not counted, such as a digital good, is always inStock. The catalogue routes are cached for up to five minutes, so the status is for display.

Before you take an order, ask for stock itself:

GET /commerce/delivery/v1/stock?keys=TR-40,TR-41
{ "items": [{ "sku": "TR-40", "status": "inStock", "available": 5 }, { "sku": "TR-41", "status": "outOfStock", "available": 0 }], "missing": [] }

This route is never cached, so it is the authority to confirm against. Because it reads the database on every call it has its own, tighter budget: a tenth of the key’s requests per minute.

available is the number of units available now: on hand, less what checkouts are holding, never below zero. A server key always receives it. A browser-safe key receives it only when you switch on Show stock quantities for the store, which is off by default. A browser-safe key is embedded in your page, so anyone who loads the page can read what it is told, a competitor included. While the setting is off, available is absent from every item, not null, and the status is all a browser-safe key learns. No catalogue route ever carries a count for any key.

A key made with Allow carts and checkout can also run a shopper’s cart. A cart belongs to one shopper in one store and holds SKUs and quantities only: it never holds a price, because the server prices everything, so a client cannot name one. The shopper is proven by their visitor token, sent in the X-Visitor-Token header; another shopper’s cart answers 404 cart_not_found.

  • POST /commerce/delivery/v1/carts creates one. Its currency is fixed at creation.
  • PUT /commerce/delivery/v1/carts/{id}/lines sets a SKU’s quantity (1 to 99; 0 removes it). A SKU that is not on sale, or has no price in the cart’s currency, is refused at once.
  • PUT /commerce/delivery/v1/carts/{id}/address sets the delivery and billing addresses. The country decides tax and shipping.
  • GET /commerce/delivery/v1/carts/{id} returns the cart with every price and total worked out now; DELETE removes it.

Tax comes from where the order goes: the delivery address for shipped goods, the billing address otherwise. Until there is an address a rate applies to, taxCalculated is false and the tax is absent, not zero. A destination the store cannot ship to in the cart’s currency is reported as shipping.status: "unavailable" and is refused at checkout, never shipped free. A browser-safe key with checkout is in your page, so anyone who loads it can start a cart: carts are priced on the server and creating them is rate limited.

POST /commerce/delivery/v1/carts/{id}/checkout starts paying for a cart. It becomes an order awaiting payment, the stock is held for 30 minutes, and the answer carries the payment provider’s page to send the shopper to; card details are entered there and never reach your page or ebitex. The server prices the cart afresh, so the shopper pays what the cart shows now, and the order records the rate a converted price used. A cart that cannot be paid for as it stands is a 409 with a code that says why: an empty cart, no address, a line that can no longer be sold, not enough stock, tax that could not be worked out, or a store with no payment connection for its mode.

A store has a test mode and a live mode. In test mode the order is marked as a test, nothing is charged and no stock is held, so you can build and try a storefront against the real store. Return addresses must be absolute https addresses (http only to localhost), and for a browser-safe key on one of its allowed origins. Whether an order is paid is for your server to learn from the store; arriving at the success address proves nothing.

Errors are JSON with an error code. The ones you meet:

Status error Meaning
400 invalid_cursor The cursor belongs to a different query
400 invalid_limit, invalid_sort, invalid_search, invalid_keys, invalid_category The request is malformed
401 invalid_api_key The key is unknown, revoked or expired
402 payment_required The organization’s subscription needs attention
403 origin_denied, ip_denied A browser-safe key was used from outside its restrictions
404 product_not_found No such product, or this key may not see it
429 rate_limited The key spent its budget; Retry-After says how long to wait

Every response carries an X-Request-Id. Quote it if you ask for help.