Skip to main content

Partner API access (/api/v1/external/*)

This page documents the platform's partner-facing HTTP surface: the dedicated /api/v1/external/* namespace. It is the only namespace intended for external partners (distributors, resellers, procurement systems) and the partner-documentable scope of the live OpenAPI document (GET /api/v1/_openapi.json). Public storefront endpoints (/api/v1/catalog/…) and customer-session endpoints (/api/v1/orders…) are not partner surfaces — they ignore API-key credentials entirely.

Authentication​

Every /api/v1/external/* request must carry an API-key bearer token:

GET /api/v1/external/catalog/products?limit=50 HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_live_REDACTED
  • Anonymous requests receive 401 UNAUTHORIZED.
  • Revoked and expired keys receive 401 UNAUTHORIZED everywhere.
  • A key missing the required scope receives 403 API_KEY_OUT_OF_SCOPE (audited).

Keys are issued in Admin Panel → API keys. The token is shown once at creation; only its SHA-256 hash is stored.

The two key modes​

Unbound keyBound key
IdentityPlatform credential (system context)Acts for one Organization on one pinned Sales Channel via a designated service Customer Account
Typical usePIM sync, feed generationDistributor integration: org-priced catalog, ordering
Catalog readsThe channel's prices for everyone (no organization); channel resolved from the X-Sales-Channel header / host / defaultThe Organization's effective prices, availability, and quantity price tiers; channel always the bound one
Bulk pricing / ordersRefused (403 API_KEY_NOT_BOUND)Allowed with the matching scope
Allowed scopescatalog:read, catalog:writecatalog:read, orders:read, orders:write (catalog:write is forbidden on bound keys)
ExpiryOptional expiresAtOptional expiresAt

The binding (Organization + Sales Channel + service Customer Account) is immutable after creation — to rebind, revoke the key and issue a new one. See api_keys module docs for the creation rules.

Scope catalog​

ScopeUnbound keyBound key
catalog:readExternal catalog reads (the channel's prices for everyone) + PIM attribute-set readsExternal catalog reads (org prices) + bulk pricing
catalog:writePIM by-SKU product upsertNot grantable (creation rule)
orders:readNot grantable without a bindingExternal order list/detail
orders:writeNot grantable without a bindingExternal order placement
platform.api_description.readThe API description (GET /api/v1/_openapi.json)The API description (GET /api/v1/_openapi.json)

Channel pinning (bound keys)​

A bound key always operates on its bound sales channel. Sending an X-Sales-Channel header naming a different channel is refused with 403 API_KEY_CHANNEL_MISMATCH (and audited). If the bound channel is inactive, requests fail closed with the standard inactive-channel error — no fallback.

Caching rule (normative)​

Every /api/v1/external/* response carries:

Cache-Control: private, no-store

Responses are per-credential (org-specific prices, order data) and must never enter a shared or persistent cache. Do not cache them on your side beyond the lifetime of the request that produced them; re-fetch instead.

Catalog reads​

Gate: catalog:read.

  • GET /api/v1/external/catalog/products — paginated list (limit 1–100, cursor), filters categorySlug, q, and changedSince (ISO 8601). Served from PostgreSQL deterministically (x-search-backend: postgres).
  • GET /api/v1/external/catalog/products/:idOrSlug — detail; for bound keys includes priceTiers (the Organization's quantity-tier ladder: the price at each quantity where one of the price books that apply to it starts a tier).
  • GET /api/v1/external/catalog/categories — the resolved channel's category tree.

Bound callers see the bound channel's published assortment exactly as the storefront does; products excluded from that channel are absent and their detail URLs return 404 — indistinguishable from non-existence. Bound-caller items additionally carry:

  • price — the Organization's effective unit price at quantity 1, computed by the same price-book resolution as the cart (null when no price book prices the product for it);
  • priceUnavailable: true — marker when the org price could not be resolved;
  • availability — { band, inStock }.

Incremental sync with changedSince​

For a full export, paginate with cursor until exhaustion. For incremental sync, poll with changedSince=<last successful sync start>. Always overlap the windows: record the timestamp before a sync run starts and pass that value on the next run, so updates that land while a run is in flight are never skipped. Deduplicate on product id.

Bulk pricing​

Gate: catalog:read, bound keys only.

POST /api/v1/external/catalog/prices
{ "lines": [ { "sku": "SKU-1", "quantity": 10 }, … ] } // 1–200 lines

The response preserves line order. Each line resolves to either a priced entry (amount, currency, isSale, bracketStartQuantity, priceListId) or price: null with a reason of sku_not_in_assortment or price_unavailable. priceListId is the price book that priced the line and bracketStartQuantity the starting quantity of its quantity tier — the field names predate price books and are kept for compatibility. A line names a product SKU; a variant SKU is not looked up and answers sku_not_in_assortment. Per-line misses are data, not errors — a basket always gets a total answer. More than 200 lines is a 422 VALIDATION_FAILED.

Guarantee: for any (sku, quantity) the returned amount equals what the cart and order placement would charge the bound Organization on the bound channel at that quantity, to the cent. The price is resolved for the Organization and its customer group; the bound service customer account's own customer group, if it has one, is not applied here.

Idempotent ordering​

Gate: orders:write, bound keys only.

POST /api/v1/external/orders
Idempotency-Key: acme-order-1001
{
"lines": [ { "sku": "SKU-1", "quantity": 10 } ],
"deliveryMethodId": "…", "paymentMethodId": "…",
"deliveryAddressId": "…", "billingAddressId": "…",
"customerReference": "PO-2026-0042"
}
  • The Idempotency-Key header (1–128 chars) is required; missing ⇒ 422 IDEMPOTENCY_KEY_REQUIRED.
  • Replaying the same key with the same payload — including concurrent replays — returns the same order (200); exactly one order is ever created.
  • Reusing a key with a different payload ⇒ 409 IDEMPOTENCY_KEY_REUSED.
  • Addresses: pass existing organization address ids, or inline deliveryAddress / billingAddress objects.
  • Per-line refusals are a whole-order 422 ORDER_INTAKE_LINES_REFUSED whose details is the array of per-line issues ({ path, issue, sku }, issue SKU_NOT_IN_ASSORTMENT or PRICE_UNAVAILABLE); nothing is persisted. Until issue #627 the code was VALIDATION_FAILED; the array is unchanged.
  • Another intake for the same key still in progress ⇒ 409 ORDER_INTAKE_BUSY. Retry with the same Idempotency-Key: the retry lands on the order the other intake placed. Until issue #627 this was 409 VALIDATION_FAILED with details.code intake_busy, which is gone.
  • A line whose SKU is in the channel's assortment but whose product is not available to your Organization there now — switched off in the channel, archived, outside its publication window, or restricted to other customers — refuses the whole order with 404 PRODUCT_NOT_FOUND, without naming the product; nothing is persisted. It is asked after the per-line checks, so a 422 takes precedence. The difference between the two answers is deliberate: the key is bound to one Organization and one channel — your own integration — and SKUs are generally public.
  • The success response (201) is the standard order envelope — the same shape customer sessions receive. Track orders with GET /api/v1/external/orders and GET /api/v1/external/orders/:id (orders:read); ids outside your visibility return 404.

The organization capability envelope​

A bound key can never do more than the Organization's own buyers. The same domain code path places the order, so every entitlement applies identically: suspended organization ⇒ 423; payment or delivery method outside the organization's allow-list ⇒ the same refusal as customer checkout (400 ORDER_PAYMENT_METHOD_UNAVAILABLE or 400 ORDER_DELIVERY_METHOD_UNAVAILABLE, error.details.code payment_method_not_allowed_for_organization or delivery_method_not_allowed_for_organization); credit limit exceeded ⇒ the same credit-guard error; minimum order value, assortment, warehouse strategy, and automatic promotions all behave exactly as in the storefront. There is no override or bypass parameter.

Webhooks (organization-scoped)​

Order events are delivered to webhook subscriptions (see the Integrations overview for transport, HMAC verification, and retry semantics). Two facts matter for partners:

  • A subscription may be scoped to one Organization (set the optional Organization on the webhook form). Org-scoped subscriptions receive only that Organization's order.created.v1 / order.status_changed.v1 events; platform-wide subscriptions (no organization) receive all of them. An event without an organization attribution is never delivered to an org-scoped subscription (fail closed).
  • Delivery is now active. Webhook subscriptions registered before this feature existed were accepted but order events were not dispatched. The delivery pipeline is now live: any pre-existing subscription matching order.created.v1 or order.status_changed.v1 starts receiving deliveries. Verify your receivers are idempotent before upgrading.

Error vocabulary (partner surface)​

CodeHTTPMeaning
UNAUTHORIZED401Missing, invalid, revoked, or expired key
API_KEY_OUT_OF_SCOPE403Key lacks the required scope (audited)
API_KEY_NOT_BOUND403Bound-only endpoint called with an unbound key
API_KEY_CHANNEL_MISMATCH403Bound key named a foreign sales channel
IDEMPOTENCY_KEY_REQUIRED422Missing Idempotency-Key on order placement
IDEMPOTENCY_KEY_REUSED409Same idempotency key, different payload
ORDER_INTAKE_BUSY409Another intake for the same key is in progress; retry with the same Idempotency-Key
ORDER_INTAKE_LINES_REFUSED422One or more lines refused; details lists each line's issue
SKU_NOT_IN_ASSORTMENT422 (per line)SKU absent from the bound channel's assortment
PRICE_UNAVAILABLE422 (per line)No resolvable organization price
PRODUCT_NOT_FOUND404A product in the assortment is not available to the Organization in the channel now
STOCK_UNAVAILABLE409Insufficient stock at placement
FORBIDDEN (organization_cannot_transact)423Organization suspended / cannot transact