Skip to Content

ORBCART DOCUMENTATION

HTTP API

Call OrbCart from any language. Keys, headers, the endpoints you call and how retries work.

The SDKs wrap this API. Use it directly from PHP, Python, Go or anything else that speaks HTTP. All paths are relative to your environment's URL, such as https://commerce.example.com.

Authentication

Send a credential as a Bearer token. Never in the URL.

Authorization: Bearer pk_test_...
CredentialLooks likeOpens
Publishable keypk_test_…Creating Carts in its Channel. Safe in a browser.
Cart tokencart_…_secret_…One Cart: read, change, quote and pay. Keep it secret.
Secret keysk_test_…The Admin API. Server only.

A signed-in buyer's ID token goes in its own header, next to a publishable key or Cart token: OrbCart-Buyer: <id token>.

A first request

curl -X POST http://localhost:8787/v1/carts \
  -H "Authorization: Bearer $ORBCART_PUBLISHABLE_KEY" \
  -H "Idempotency-Key: $(openssl rand -hex 16)"

The answer is the Cart with its id and token. Use the token for everything that follows:

curl -X POST "http://localhost:8787/v1/carts/$CART_ID/lines" \
  -H "Authorization: Bearer $CART_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(openssl rand -hex 16)" \
  -d '{"reference":"BACKPACK-30-GREEN","quantity":1}'

Every Cart change answers with the whole Cart.

Endpoints

Generated from the same routes that check every request, so they never fall behind. Every field and every answer is in the OpenAPI 3.2 description, ready for a generated client in any language: openapi/v1.json. Your own environment serves the description of its API at /v1/openapi.json: the same, with the extensions your code declares by name and every event under webhooks. A generated client of that one knows the fields of exactly your shop.

Storefront

With a publishable key or a Cart token.

MethodPathWhat it doesWith
POST/v1/cartsCreate a Cart. { lines? }Publishable key
POST/v1/carts/handoffsOpen an agent's checkout in the buyer's browser. { handoff }Publishable key
POST/v1/carts/{cart}/buyerClaim the Cart for the signed-in buyer.Cart token
POST/v1/carts/{cart}/successorStart the next Cart after a purchase.Cart token
GET/v1/carts/{cart}Read a Cart.Cart token
GET/v1/carts/{cart}/payment-methods/{method}/setupA payment method's public setup before there is a Quote.Cart token
POST/v1/carts/{cart}/payment-methods/apple_pay/sessionApple Pay's merchant session for the page that shows its button. { page }Cart token
POST/v1/carts/{cart}/linesAdd a Line. { reference, quantity?, configuration? }Cart token
PATCH/v1/carts/{cart}/lines/{line}Set a Line's quantity. { quantity }Cart token
DELETE/v1/carts/{cart}/lines/{line}Remove a Line.Cart token
PUT/v1/carts/{cart}/ship-toSet the delivery address.Cart token
PUT/v1/carts/{cart}/bill-toSet a separate billing address.Cart token
DELETE/v1/carts/{cart}/bill-toBill to the delivery address again.Cart token
PUT/v1/carts/{cart}/contactSet the buyer's email and phone. { email, phone? }Cart token
PUT/v1/carts/{cart}/shippingChoose a shipping method. { id }Cart token
POST/v1/carts/{cart}/codesEnter a discount code. { code }Cart token
DELETE/v1/carts/{cart}/codes/{code}Remove a discount code.Cart token
POST/v1/carts/{cart}/gift-cardsApply a gift card to the cart. { code }Cart token
DELETE/v1/carts/{cart}/gift-cards/{card}Take a gift card off the cart.Cart token
PUT/v1/carts/{cart}/extensions/{name}Set a Cart extension. { value }Cart token
DELETE/v1/carts/{cart}/extensions/{name}Remove a Cart extension.Cart token
POST/v1/carts/{cart}/quoteGet a signed Quote.Cart token
GET/v1/quotes/{quote}Reopen a Quote with its last payment state.Cart token
GET/v1/quotes/{quote}/payment-methods/{method}/setupA payment method's public setup for the Quote's amount.Cart token
POST/v1/quotes/{quote}/acceptAccept the Quote and pay. { payment, instrument?, preparation?, returnTo? }Cart token
POST/v1/payments/{payment}/resumeResume a Payment after a provider redirect. { returned? }Cart token
POST/v1/carts/{cart}/prepare-paymentPrepare a payment the buyer approves at the provider first, such as PayPal. { payment, returnTo? }Cart token
POST/v1/carts/{cart}/preparations/{preparation}/updatePass on an address or shipping method the buyer chose at the provider. { shipTo } or { shipping }Cart token
POST/v1/carts/{cart}/preparations/{preparation}/reviewQuote what the buyer approved at the provider. { returned? }Cart token
GET/v1/orders/{order}Read an Order by ID or number, or a buyer's own by its token.
POST/v1/withdrawalsWithdraw from an Order.Publishable key
GET/v1/ordersList Orders: a signed-in buyer's own, or all of them with filters.Publishable key
GET/v1/address-formats/{country}Postal code and region rules of a country.Publishable key, Cart token

Admin

With a secret key, on servers only.

MethodPathWhat it does
GET/v1/cartsList Carts that need a person.
GET/v1/carts/{cart}Read a Cart.
GET/v1/orders/{order}Read an Order by ID or number, or a buyer's own by its token.
POST/v1/orders/{order}/fulfillmentsReport shipped units.
POST/v1/orders/{order}/cancellationsCancel units that have not shipped, or the whole Order. { lines?, reason }
POST/v1/orders/{order}/returnsRecord shipped units that came back. { lines, reason, restock }
POST/v1/orders/{order}/paymentsRecord a payment received for an Order paid offline. { amount, receivedAt?, reference? }
POST/v1/orders/{order}/acknowledgeConfirm your ERP took the Order. { reference? }
GET/v1/orders/{order}/appointments/{appointment}/free-timesRead free starts for the appointment's whole visit at its Location.
POST/v1/orders/{order}/appointments/{appointment}/moveMove every active appointment of the visit together, once per key. { start, notifyBuyer }
POST/v1/orders/{order}/appointment-changesRecord an immutable appointment change from the capacity authority.
GET/v1/orders/{order}/refundsRefunds and what is still refundable.
POST/v1/orders/{order}/refundsRefund. { lines?, shipping?, expectedAmount?, reason? }
POST/v1/orders/{order}/refunds/previewCalculate a refund without making it. { lines?, shipping?, expectedAmount?, reason? }
GET/v1/withdrawalsList the withdrawals that need attention.
GET/v1/withdrawals/{withdrawal}Read a withdrawal as it was received.
POST/v1/withdrawals/{withdrawal}/attachRecord a withdrawal on the Order it meant. { order }
POST/v1/withdrawals/{withdrawal}/handleMark a withdrawal that named no Order as handled.
POST/v1/orders/searchFind a buyer's Orders by email, by identity, or both.
GET/v1/ordersList Orders: a signed-in buyer's own, or all of them with filters.
GET/v1/eventsList the Events of Orders and of the Carts before them, newest first, with how far each receiver's delivery came.
POST/v1/events/{event}/resendSend an Event again, with the same ID, to one Receiver or to all that want its type. { receiver? }
POST/v1/events/replaySend the Events from an instant on again, oldest first, a batch per call. { since, receiver?, after? }
GET/v1/insights/checkoutCount where buyers get stuck: the funnel, the time a checkout takes, the friction and the payment methods of the last days.
GET/v1/receiversList the Receivers of Events that the code defines, with how each stands.
POST/v1/receivers/{receiver}/pauseStop deliveries to a Receiver until it is resumed.
POST/v1/receivers/{receiver}/resumeResume a Receiver and deliver its backlog at once.
POST/v1/offers/invalidateVoid Offers by reference or tag. { references?, tags?, reason? }
GET/v1/environmentMode, jurisdiction and Channels.
PUT/v1/channels/identitiesTake the identities of the channels the catalog keeps. { channels }
GET/v1/discountsList the discounts staff made, with their state and how often each was redeemed.
POST/v1/discountsMake a discount; it applies from the next quote.
GET/v1/discounts/{discount}One discount.
PUT/v1/discounts/{discount}Replace a discount's rules; the next quote applies them.
POST/v1/discounts/{discount}/pauseStop a discount until it is resumed.
POST/v1/discounts/{discount}/resumeResume a paused discount.
POST/v1/discounts/{discount}/endEnd a discount for good.
POST/v1/discounts/{discount}/batchesGenerate a batch of single-use codes; the same prefix and count again answers the same batch. { prefix, count }
GET/v1/discounts/{discount}/batches/{prefix}A batch's codes, each with whether it was redeemed: what the CSV export lists.
GET/v1/discounts/{discount}/redemptionsThe orders that redeemed a discount, the latest first.
GET/v1/gift-cards/accessWhere the caller may redeem gift cards, and whether they work merchant-wide.
POST/v1/gift-cardsMake a gift card with a value, such as a goodwill gesture; the same Idempotency-Key again answers the same card. { amount, currency, reason, channel? }
GET/v1/gift-cardsList the gift cards made in the last 30 days, newest first.
POST/v1/gift-cards/lookupFind a gift card by the code a customer holds out, at the desk of any Location; a few tries a minute per address. { code }
GET/v1/gift-cards/{card}A gift card's standing, without its code.
GET/v1/gift-cards/{card}/historyWhat moved on a gift card, oldest first: its value, each payout with its order or Location, refunds and what was retired.
POST/v1/gift-cards/{card}/redemptionsPay out value of a gift card at the desk of a Location; the same Idempotency-Key again answers the same payout. { code, amount, location, note? }
GET/v1/gift-cards/{card}/deliveryWhat a mail about a gift card needs: its code and the link to print it from.
POST/v1/gift-cards/{card}/printMake a fresh link to the gift card's printable page.
GET/v1/address-formats/{country}Postal code and region rules of a country.

Express preparations

With the owning Cart token and an Idempotency-Key:

  • POST /v1/carts/{cart}/prepare-payment with { "payment": "amazon_pay", "returnTo": "https://shop.example/checkout" } returns a preparation. Amazon's launch has sdk: { payloadJSON, signature, algorithm }, not a provider reference yet. PayPal's preparation carries providerReference.
  • Render Amazon's official button with the method's public sdk setup. On click, prepare and pass the signed launch to button.initCheckout(). Never expose the private key or reserialize the signed payload.
  • After Amazon redirects to ?preparation=…&amazonCheckoutSessionId=…, POST /v1/carts/{cart}/preparations/{preparation}/review accepts { "returned": { "amazonCheckoutSessionId": "…" } }. Without provider return fields, send {}. The server verifies and adopts the session for this Cart; the returned ID alone grants no access.
  • The response is the review Quote plus its preparation, whose sdk has the actual paymentDescriptor, sessionId, region and optional checkoutButtonText. Keep the shipping address read-only and offer Amazon's hosted change actions.
  • Only after consent, accept the Quote with { "payment": "amazon_pay", "preparation": "…" }. Follow its redirect, then resume the Payment with { "returned": { "amazonCheckoutSessionId": "…" } } at POST /v1/payments/{payment}/resume.

Amazon is preparationRequired: true: it is accepted only with its reviewed preparation, so never offer an order button that names it without one. As an express button it is express: "review" (with expressOnly: true unless the Channel's offer also lists it among the methods). Among the methods, render Amazon's button in place of the order button, with the method's sdk.productType (PayAndShip, or PayOnly for a pickup or a cart that ships nothing). Reloads reuse the stored session; the server does not replace it with a different returned ID.

No Amazon SNS/IPN webhook is exposed. Durable server polling handles payment outcomes and refunds initiated by OrbCart, not refunds made in Seller Central. Setup and sandbox acceptance →

Public endpoints

MethodPathWhat it is
GET/.well-known/jwks.jsonPublic keys to verify Quotes.
GET/.well-known/ucpYour UCP profile for AI agents.
POST/webhooks/{provider}Webhooks from stripe, adyen, mollie and paypal.

Retries and idempotency

Send an Idempotency-Key header on every change. After a timeout, repeat the same request with the same key. OrbCart answers with the original result instead of doing it twice. A new operation gets a new key.

Accepting a Quote, refunds and payment preparations require a key. Keys live for 24 hours.

The Cart creation key is a secret, too

For 24 hours, replaying the key of POST /v1/carts returns that Cart's token. Keep it as private as the token.

Errors

Failures use Problem Details as application/problem+json:

{
  "status": 422,
  "code": "cart_incomplete",
  "kind": "invalid",
  "retryable": false,
  "requestId": "req_01J...",
  "detail": "The cart still lacks ship_to, email.",
  "missing": ["ship_to", "email"]
}

Decide by code, never by detail. detail is for developers, in English. Every code and what to do →

Versioning

/v1 only grows. New fields and new values can appear at any time; existing ones never change meaning. Ignore fields you don't know and handle unknown values in open lists such as changes, missing and code.

Look up an error code →

On this page