ORBCART DOCUMENTATION
How it works
Follow one purchase from cart.add to the Order in your ERP, and see what OrbCart does when something goes wrong.
This page follows one purchase through every part of OrbCart. The words it uses, such as Offer, Quote and Order, are explained in Concepts.
Browser SDK ──► Worker ──► Cart object ──► your offers · inventory · tax
│
├──► payment provider ◄── its webhook
│
└──► outbox ──► deliverOrder · D1 · eventsThe parts
| Part | Where it runs | What it owns |
|---|---|---|
| Client SDK | The browser, an app or an agent | Nothing binding. It sends what the buyer wants and keeps the Cart token. |
| Worker | Your Cloudflare account, one per Environment | Nothing. It checks each request and routes it to the right Cart. |
| Cart object | One Durable Object per Cart | The Cart, its Quotes, its Payment and its Order. The source of truth. |
| Environment object | One Durable Object per Environment | API keys, Order numbers and the key that signs Quotes. |
| Your contracts | Your code, another Worker or an HTTP endpoint | Prices, stock, tax and the Order hand-off. Offers → |
| Payment provider | Stripe, Adyen, Mollie, PAYONE or PayPal | The money. |
| D1 | Your Cloudflare account, optional | A copy of the Order list without personal data, for lists and the Explorer. |
One purchase, step by step
- The buyer adds a Line.
cart.add("BACKPACK-30-GREEN")runs in the browser. The first call creates the Cart with the Channel's publishable key and gets back a Cart token. Every later call carries that token, and every change carries a freshIdempotency-Key. - The Worker checks and routes. It reads the credential from the
Authorizationheader, checks the calling site against the Channel'soriginsand the body against the API schema. The Cart's ID is part of its token, so the request goes straight to that Cart's Durable Object, which checks the token itself. - The Cart asks your systems. The Cart object calls your
offersfunction for the new Line and answers with the whole Cart: titles and prices, a non-bindingestimate, and what is stillmissing. - The buyer asks for a Quote.
cart.quote()sends the address and email. The Cart asksoffersfor binding prices, reserves stock throughinventoryif you implement it, and gets tax from the EU's rates or yourtaxfunction. The core calculates every amount; the runtime signs the result with the Environment's key and stores it. The Quote lasts at most 30 minutes. - The buyer pays.
quote.pay({ payment })runs on the order button. Card details go from the provider's field straight to the provider. The Cart checks that the Quote still holds, records the buyer's consent and a new Payment in one write, and keeps the Cart still while the Payment runs. It starts the Payment with an idempotency key derived from the Payment's ID. - The provider decides. Its answer arrives with the response, by a signed webhook, or when the Cart asks again. Whichever comes first records the decision; the others find it. A 3-D Secure step in between is
requires_action, which the SDK runs. - The Order arises. In the same Cart object: an Order number from the Environment object, then the Order with the signed Quote exactly as it was.
pay()answersordered. - The follow-up steps run. The write that creates the Order also puts its follow-up steps in the Cart's outbox: capture the money, commit the reserved stock, hand the Order to your ERP through
deliverOrder, update the Order list in D1 and sendorder.createdto your event receivers. An alarm of the Durable Object runs each step until it succeeds.
If your ERP would rather poll than receive, leave out deliverOrder and let it fetch Orders.
When something goes wrong
| What happens | What OrbCart does | What the buyer sees |
|---|---|---|
| A price, stock or shipping changes before payment | The acceptance answers quote_changed with a new Quote and the list of changes. Nothing is charged. | The new total, and the order button again. |
| The provider does not answer in time | The Payment becomes unknown, never failed. The Cart asks again after 30 seconds, then 1, 2, 4, 8 and 16 minutes, and listens for the webhook. Still unclear when the payment window ends, 30 minutes after consent by default, it cancels the Payment with the provider. | A calm waiting page that becomes the Order once decided. |
| A double click, a reload or a second tab | A click on a Quote whose Payment runs is answered with that Payment. A repeated request with the same key replays the first answer. | One Payment and one Order. |
Your offers or tax function fails | No Quote. The answer is provider_unavailable, which can be retried. OrbCart never invents a price. | A message to try again. |
| Your ERP is down | deliverOrder gets the same Order again, first after a second, then up to once an hour, so your ERP deduplicates by order.id. After 30 minutes the Order shows handoff_failed; the retries go on. | Nothing. Their Order exists. |
| The Worker restarts mid-purchase | The decision is stored before anything follows from it. The next alarm continues where the last one stopped. | Nothing. |
A payment the provider confirms after the window closed is canceled, or refunded if it was already captured. A Payment the provider reports as still processing, as with some asynchronous methods, is never given up: OrbCart waits for its webhook.
Where the data lives
- The Cart object is the truth. It holds the Cart, its Quotes, the Payment and the Order with the buyer's details.
- D1 is a copy. The Order list behind
admin.orders.list()and the Explorer can lag a few seconds, and nothing is decided from it.admin.orders.get()reads the Cart object itself. - No archive yet. A locked R2 archive of every Order is planned, not built. Today the Order lives in its Cart object only.
Which personal data is kept where, and when it is deleted: Security.
Next
- Security: what each key and token opens, and what to check before going live.
- Hand Orders to your ERP: the contract behind step 8.
- Quotes & payments: every outcome of
pay()in code.