Overview

The public API is what a storefront, a checkout and a buyer's library call. It reads a store's public data, starts a checkout, follows an order to fulfilment and records tracking events. It is safe to call from a browser.

Base URLCopy Anchor Link

https://api.sorai.ai

Every route is under /v1/public. Requests and responses are JSON.

AuthenticationCopy Anchor Link

Send your store's publishable key in the X-Sorai-Key header:

curl https://api.sorai.ai/v1/public/products/my-ebook \
  -H "X-Sorai-Key: spk_..."

A publishable key starts with spk_ and belongs to one store. It is safe to ship to a browser: it can read public store data, start a checkout and post tracking events, and it can never change the catalog, list orders or read a buyer's personal details.

Create one in the Sorai console under Organization, API keys. Pick Publishable and the store it is for.

A few routes take something else instead of the key, and each says so on its page:

• An order's status and its post-payment offer take the token the checkout returned.
• The buyer's library uses a session cookie, set when the buyer follows the link Sorai emails them.
• Media links accept the key as ?key=, because an <img src> cannot set a header. Tracking events accept it in the body as public_key, because navigator.sendBeacon cannot either.

ErrorsCopy Anchor Link

A request that fails answers a non-2xx status and a body like this:

{
  "error": {
    "code": "payment_method_required",
    "message": "choose how you want to pay"
  }
}

Branch on code; message is for people and can change. A request whose body or query fails validation answers 422 with the code validation_failed and a fields array naming every field that failed.

MoneyCopy Anchor Link

Every amount is an integer in the currency's minor unit, such as cents, in a field ending _minor. Never a float. Sorai never converts between currencies: a price is charged in the currency it is listed in.

Retrying a checkoutCopy Anchor Link

POST /v1/public/checkout needs an Idempotency-Key header, unique per checkout attempt. Sending the same key again returns the original order instead of creating a second one, so a checkout that timed out can be retried safely.

Try itCopy Anchor Link

Each endpoint page has a playground. Paste your own publishable key into it and send the request: it goes from your browser straight to the API, against your real store. These docs embed no key, and the one you paste stays in this browser tab's session storage until you close it.

A checkout sent from the playground creates a real order, so try it on a store you test with. Never paste a secret key (ssk_): the playground only needs a publishable one, and a secret key must not reach a browser.

WebhooksCopy Anchor Link

To hear about orders as they happen instead of asking for them, see Webhooks.