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
POST /v1/commerce/sessionswithcategory, a natural-languagequery, an optionalcity, andbuyer.phone(required — it keys checkout continuity and order lookup).- Poll
GETevery few seconds untiloptions_ready. Searches run against live supply and typically settle within a minute. Options carry opaqueoption_refidentifiers, titles, and prices; supplier network internals are never exposed. POST …/checkoutand send the buyer to the returnedcheckout_url. The buyer completes selection, consent, and payment on Bino's page.- 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.