# 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.

```http
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

```sh
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:

```sh
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: <a href="/openapi/v1.json">openapi/v1.json</a>.
Your own environment serves the description of its API at `/v1/openapi.json`: the same, with the
[extensions](/commerce/extensions) your code declares by name and every [event](/integrations/events#the-catalog) 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](/commerce/quotes#verify-a-quote). |
| `GET`  | `/.well-known/ucp`       | Your UCP profile for [AI agents](/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.

<Callout type="warn" title="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.
</Callout>

## Errors

Failures use [Problem Details](https://www.rfc-editor.org/rfc/rfc9457) as
`application/problem+json`:

```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 →](/api-reference/errors)

## 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 →](/api-reference/errors)