# Commerce API

Create commerce sessions that search Bino's connected supply, return ranked options, and hand the buyer to a Bino-hosted checkout.

Create a commerce session, poll it for ranked options from Bino's connected supply, then hand your buyer a Bino-hosted checkout link. Bino operates the transaction of record: consent, seller disclosure, payment, and support all happen on Bino's checkout surface, and your systems read status mirrors.

## Endpoints

| Method and path | Purpose |
|---|---|
| `POST /v1/commerce/sessions` | Create a buyer session and start the supply search. Returns `201` with `status: "searching"` immediately. |
| `GET /v1/commerce/sessions/{session_id}` | Poll the session. `status` becomes `options_ready` with redacted option cards, or `failed`. |
| `POST /v1/commerce/sessions/{session_id}/checkout` | Get the Bino-hosted `checkout_url` for the buyer (optionally pass an `option_ref`). |
| `GET /v1/commerce/orders/{order_ref}` | Read a redacted order status mirror after the buyer completes checkout. |
| `GET /v1/usage` | Read your metered usage. |

## How a session flows

1. `POST /v1/commerce/sessions` with `category`, a natural-language `query`, an optional `city`, and `buyer.phone` (required — it keys checkout continuity and order lookup).
2. Poll `GET` every few seconds until `options_ready`. Searches run against live supply and typically settle within a minute. Options carry opaque `option_ref` identifiers, titles, and prices; supplier network internals are never exposed.
3. `POST …/checkout` and send the buyer to the returned `checkout_url`. The buyer completes selection, consent, and payment on Bino's page.
4. Track fulfilment with `GET /v1/commerce/orders/{order_ref}`.

## Authentication and environments

Authenticate every call with your service-account headers `x-boni-client-id` and `x-boni-client-secret`. `https://sandbox.api.boni.one/v1` serves deterministic fixtures for integration tests; `https://api.boni.one/v1` serves live supply and is metered per successful session. Every `POST` requires an `Idempotency-Key` header (retries with the same key replay the stored response). Per-second through per-day quotas apply per subscription and are reported in rate-limit response headers.

## Access

Commerce API subscriptions are provisioned per organization by the Boni team, with sandbox access first and production activation tied to your billing account. Errors use the standard envelope with a stable `error.code` and a `request_id` for support.

Canonical: https://docs.boni.one/developers/commerce-api
Version: 2
Updated: 2026-08-19T09:27:48.300Z