HTTP API

Every endpoint below is relative to your commerce environment's URL. The client SDK handles authentication, response parsing and safe transport retries for you.

Authentication

Send credentials as a Bearer token. Never put them in the URL.

Credential	Use
Publishable key (`pk_test_…`)	Create a Cart in its Channel. Safe to expose in a storefront.
Cart token	Read and change one Cart, quote and accept its purchase. Keep secret.
Secret key (`sk_test_…`)	Merchant operations. Server only.

Create a Cart

Replace the example key with the OrbCart key from your environment:

CART_CREATION_KEY=$(openssl rand -hex 16)

curl http://localhost:8787/v1/carts \
  -X POST \
  -H "Authorization: Bearer $ORBCART_PUBLISHABLE_KEY" \
  -H "Idempotency-Key: $CART_CREATION_KEY"

The JSON response includes id and token. Save the token privately; use it for subsequent calls on that Cart. Creating a different Cart needs a different idempotency key. Keep the creation key private like the Cart token: for 24 hours, replaying it can recover that token. Generate it once and reuse it only for retries.

Add a Line

Set CART_ID and CART_TOKEN from that response:

ADD_LINE_KEY=$(openssl rand -hex 16)

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

The response is the full Cart, not just the added Line.

The purchase endpoints

Method	Path	Purpose
`GET`	`/v1/carts/{id}`	Read a Cart.
`PATCH`	`/v1/carts/{id}/lines/{line}`	Set a Line's quantity.
`DELETE`	`/v1/carts/{id}/lines/{line}`	Remove a Line.
`PUT`	`/v1/carts/{id}/contact`	Set contact details.
`PUT`	`/v1/carts/{id}/ship-to`	Set the delivery address.
`PUT`	`/v1/carts/{id}/shipping`	Select a shipping method by `id`.
`POST`	`/v1/carts/{id}/quote`	Get a signed Quote.
`GET`	`/v1/quotes/{id}`	Reopen a Quote and its known acceptance.
`POST`	`/v1/quotes/{id}/accept`	Accept the Quote with a payment method.

This is a starting reference, not the complete schema. A generated OpenAPI reference is still planned. For browser payment fields and provider actions, use the client payment flow rather than collecting card data yourself.

Retries

Send an Idempotency-Key on mutations. Repeat the same request with the same key after an unclear network result. A new operation gets a new key.

The SDK adds keys and retries eligible transport failures automatically. If your own backend retries a refund across restarts, supply its stable key explicitly.

Errors

Failed requests return application/problem+json. The useful fields are:

Field	Meaning
`code`	What happened, such as `cart_incomplete`.
`kind`	The category, such as `invalid` or `conflict`.
`retryable`	Whether the same request may succeed later.
`requestId`	A reference for investigating the request.
`missing`	Details to ask for when the Cart is incomplete.

The SDK throws these as CommerceError, available under error.problem. Don't show the API's developer-facing detail directly to buyers.

A payment decline or quote_changed is instead a normal acceptance outcome. Handle each outcome →