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_...| Credential | Looks like | Opens |
|---|---|---|
| Publishable key | pk_test_… | Creating Carts in its Channel. Safe in a browser. |
| Cart token | cart_…_secret_… | One Cart: read, change, quote and pay. Keep it secret. |
| Secret key | sk_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.
| Method | Path | What it does | With |
|---|---|---|---|
POST | /v1/carts | Create a Cart. | Publishable key |
POST | /v1/carts/handoffs | Open an agent's checkout in the buyer's browser. { handoff } | Publishable key |
POST | /v1/carts/{cart}/buyer | Claim the Cart for the signed-in buyer. | Cart token |
POST | /v1/carts/{cart}/successor | Start the next Cart after a purchase. | Cart token |
GET | /v1/carts/{cart} | Read a Cart. | Cart token |
GET | /v1/carts/{cart}/payment-methods/{method}/setup | A payment method's public setup before there is a Quote. | Cart token |
POST | /v1/carts/{cart}/lines | Add 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-to | Set the delivery address. | Cart token |
PUT | /v1/carts/{cart}/bill-to | Set a separate billing address. | Cart token |
DELETE | /v1/carts/{cart}/bill-to | Bill to the delivery address again. | Cart token |
PUT | /v1/carts/{cart}/contact | Set the buyer's email and phone. { email, phone? } | Cart token |
PUT | /v1/carts/{cart}/shipping | Choose a shipping method. { id } | Cart token |
POST | /v1/carts/{cart}/codes | Enter 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}/quote | Get 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}/setup | A payment method's public setup for the Quote's amount. | Cart token |
POST | /v1/quotes/{quote}/accept | Accept the Quote and pay. { payment, instrument?, preparation?, returnTo? } | Cart token |
POST | /v1/payments/{payment}/resume | Resume a Payment after a provider redirect. { returned? } | Cart token |
POST | /v1/carts/{cart}/prepare-payment | Prepare a payment the buyer approves at the provider first, such as PayPal. { payment, returnTo? } | Cart token |
POST | /v1/carts/{cart}/preparations/{preparation}/update | Pass on an address or shipping method the buyer chose at the provider. { shipTo } or { shipping } | Cart token |
POST | /v1/carts/{cart}/preparations/{preparation}/review | Quote 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/orders | List 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.
| Method | Path | What it does |
|---|---|---|
GET | /v1/carts | List 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}/fulfillments | Report shipped units. |
POST | /v1/orders/{order}/acknowledge | Confirm your ERP took the Order. { reference? } |
GET | /v1/orders/{order}/refunds | Refunds and what is still refundable. |
POST | /v1/orders/{order}/refunds | Refund. { lines?, shipping?, expectedAmount?, reason? } |
POST | /v1/orders/{order}/refunds/preview | Calculate a refund without making it. { lines?, shipping?, expectedAmount?, reason? } |
POST | /v1/orders/search | Find Orders by email. { email, limit?, after? } |
GET | /v1/orders | List Orders: a signed-in buyer's own, or all of them with filters. |
GET | /v1/events | List the Events of Orders and of the Carts before them, newest first, with how far each receiver's delivery came. |
POST | /v1/events/{event}/resend | Send an Event again, with the same ID, to one Receiver or to all that want its type. { receiver? } |
POST | /v1/events/replay | Send the Events from an instant on again, oldest first, a batch per call. { since, receiver?, after? } |
GET | /v1/insights/checkout | Count where buyers get stuck: the funnel, the time a checkout takes, the friction and the payment methods of the last days. |
GET | /v1/receivers | List the Receivers of Events that the code defines, with how each stands. |
POST | /v1/receivers/{receiver}/pause | Stop deliveries to a Receiver until it is resumed. |
POST | /v1/receivers/{receiver}/resume | Resume a Receiver and deliver its backlog at once. |
POST | /v1/offers/invalidate | Void Offers by reference or tag. { references?, tags?, reason? } |
GET | /v1/environment | Mode, jurisdiction and Channels. |
GET | /v1/address-formats/{country} | Postal code and region rules of a country. |
Public endpoints
| Method | Path | What it is |
|---|---|---|
GET | /.well-known/jwks.json | Public keys to verify Quotes. |
GET | /.well-known/ucp | Your 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.