Skip to Content

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 · lists · events

The parts

PartWhere it runsWhat it owns
Client SDKThe browser, an app or an agentNothing binding. It sends what the buyer wants and keeps the Cart token.
WorkerYour Cloudflare account, one per EnvironmentNothing. It checks each request and routes it to the right Cart.
Cart objectOne Durable Object per CartThe Cart, its Quotes, its Payment and its Order. The source of truth.
Environment objectOne Durable Object per EnvironmentAPI keys, Order numbers and the key that signs Quotes.
Your contractsYour code, another Worker or an HTTP endpointPrices, stock, tax and the Order hand-off. Offers →
Payment providerStripe, Adyen, Mollie, PAYONE or PayPalThe money.
Your PostgresYour database through Hyperdrive, optionalThe lists, a copy without personal data, for the Admin API and the admin.

One purchase, step by step

  1. 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 fresh Idempotency-Key.
  2. The Worker checks and routes. It reads the credential from the Authorization header, checks the calling site against the Channel's origins and 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.
  3. The Cart asks your systems. The Cart object calls your offers function for the new Line and answers with the whole Cart: titles and prices, a non-binding estimate, and what is still missing.
  4. The buyer asks for a Quote. cart.quote() sends the address and email. The Cart asks offers for binding prices, reserves stock through inventory if you implement it, and gets tax from the EU's rates or your tax function. 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.
  5. 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.
  6. 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.
  7. 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() answers ordered.
  8. 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 your Postgres and send order.created to 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 happensWhat OrbCart doesWhat the buyer sees
A price, stock or shipping changes before paymentThe 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 timeThe 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 tabA 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 failsNo Quote. The answer is provider_unavailable, which can be retried. OrbCart never invents a price.A message to try again.
Your ERP is downdeliverOrder 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-purchaseThe 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.
  • The lists are a copy. The Order list in your Postgres, behind admin.orders.list() and the admin's Orders area 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

On this page