# Concepts

The mental model of OrbCart. Who owns what, the words of a purchase, and why it is shaped this way.

**You own the catalog. OrbCart owns the purchase.** Products, prices and stock stay
in your systems. OrbCart takes a reference and a quantity, asks your systems for the
current facts and turns them into a signed Quote, a Payment and an Order.

Two front doors lead into one Cart: your storefront, where the buyer shops with a publishable key, and AI agents, which buy for a buyer over UCP with signed requests. The Cart holds the purchase from its Lines to the Quote, the Payment and the Order, in a Worker in your own Cloudflare account. Behind it, your systems answer through small contracts for prices, stock, tax and the hand-off to your ERP, and the payment provider moves the money and reports back by webhook.

Both doors follow the same rules. A storefront or an agent can only say what the
buyer wants. Everything binding, from a price to the total, is decided on the
server. [How it works](/how-it-works) follows one purchase through every part.

## The words of a purchase

### Offer

**What you are willing to sell right now.** Your [offers function](/integrations)
returns it whenever OrbCart needs current facts:

```ts value="OfferedReference"
{
  reference: "BACKPACK-30-GREEN",
  title: "Trail backpack · 30 L · Green",
  price: { amount: 8990, currency: "EUR" },
  taxCategory: "standard",
  shipping: { weightInGrams: 950 },
}
```

An Offer is not a catalog entry: no images, no description, no categories. Those
stay in your storefront. Money is always an integer in minor units with its
currency, so `8990` with `EUR` is €89.90. Use `formatMoney()` to display it.

### Line

**What the buyer chose.** A reference and a quantity. OrbCart gives every Line its
own `id`:

```ts browser
await cart.add("BACKPACK-30-GREEN", { quantity: 2 });
```

Add goods by **reference**. Change or remove them by **Line ID**.

### Cart

**The purchase while it takes shape.** Lines, contact details, addresses, the
shipping choice and discount codes. Every change answers with the whole Cart,
including two fields a checkout shows:

* `estimate` is the current, non-binding price. `estimate.excludes` names what is not in it yet: `"shipping"` until a method is chosen, `"tax"` for net prices until a rate is known.
* `missing` lists what the buyer still has to provide, in the order a checkout asks: `["ship_to", "email"]`.

### Quote

**The exact deal the buyer agrees to.** A Quote freezes the Lines, prices, tax,
shipping and total. It is signed and expires after at most 30 minutes. If anything
changed before the buyer pays, the answer is `quote_changed` with a new Quote and
the list of changes. A buyer is never charged a total they did not see.

### Payment

**The money for one accepted Quote.** A provider such as Stripe, Adyen, Mollie,
PAYONE or PayPal moves it. OrbCart starts the Payment, follows it and never guesses
its outcome: an unclear answer is `unknown` until the provider decides.

### Order

**The record of the agreed purchase.** It keeps the Quote exactly as signed, even
when your prices change later. Payment, shipping and refunds move on beside it; the
purchase itself never changes. Handing the Order to your ERP is a separate step,
retried until your ERP takes it.

### Environment and Channel

* An **Environment** is one isolated deployment, such as `test` or `live`, with its own Worker, keys and data.
* A **Channel** is one way you sell, such as your German shop. It sets currency, tax, shipping, payment methods and the sites allowed to call. A publishable key belongs to exactly one Channel.

```text
Environment "live"
├── Channel "de"   EUR · EU VAT · card, PayPal, Klarna
└── Channel "ch"   CHF · Swiss VAT · card, TWINT
```

## Why it is shaped this way

* **The server decides.** Browsers and agents send references, quantities and choices. Prices, tax, discounts and totals come only from the server, so the SDKs never calculate and a tampered request has nothing to change.
* **The Quote freezes the deal.** Consent, Payment and Order all point to one signed Quote. A price that changes during the click leads to a new Quote, never to a different charge.
* **Retries are safe.** Every change carries an idempotency key, so a repeat returns the first answer instead of acting twice. The SDKs add the keys for you.
* **Every state has one owner.** Each Cart is one Durable Object that holds its Quotes, its Payment and its Order. Lists and dashboards read a copy, and no decision is made from it.
* **Your catalog is asked, not copied.** There is no import and no sync. OrbCart asks `offers` when it needs facts and keeps an answer only while it is valid. To end a price at once, [invalidate it](/integrations#end-a-sale-early).

## Next

* [How it works](/how-it-works): one purchase through the browser, the Worker, your systems and the provider.
* [Security](/security): what each key and token opens, and why the browser cannot set a price.
* [Configuration](/configuration): describe your shop in one file.