# 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](/concepts).

```text
Browser SDK ──► Worker ──► Cart object ──► your offers · inventory · tax
                               │
                               ├──► payment provider ◄── its webhook
                               │
                               └──► outbox ──► deliverOrder · D1 · events
```

## The 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 →](/integrations)        |
| 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

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 D1 and send `order.created` to your [event receivers](/integrations/events). 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](/integrations/inventory#or-let-your-erp-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](/security#personal-data).

## Next

* [Security](/security): what each key and token opens, and what to check before going live.
* [Hand Orders to your ERP](/integrations/inventory#hand-orders-to-your-erp): the contract behind step 8.
* [Quotes & payments](/commerce/quotes): every outcome of `pay()` in code.