# 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="/docs/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](/docs/shop/extensions) your code declares by name and every [event](/docs/integrate/order-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.

<Operations tag="Storefront" />

### Admin

With a secret key, on servers only.

<Operations tag="Admin" />

## 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 →](/docs/shop/payments#amazon-pay)

## Public endpoints

| Method | Path                     | What it is                                                   |
| ------ | ------------------------ | ------------------------------------------------------------ |
| `GET`  | `/.well-known/jwks.json` | Public keys to [verify Quotes](/docs/shop/quotes#verify-a-quote). |
| `GET`  | `/.well-known/ucp`       | Your UCP profile for [AI agents](/docs/shop/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 →](/docs/cart/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 →](/docs/cart/errors)