HTTP API

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.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}/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
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.Cart token
GET/v1/orders/{order}Read an Order by ID or number, or a buyer's own by its token.
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}/acknowledgeConfirm your ERP took the Order. { reference? }
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? }
POST/v1/orders/searchFind Orders by email. { email, limit?, after? }
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.
GET/v1/address-formats/{country}Postal code and region rules of a country.

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