Skip to Content

ORBCART DOCUMENTATION

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 follows one purchase through every part.

The words of a purchase

Offer

What you are willing to sell right now. Your offers function returns it whenever OrbCart needs current facts:

{
  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:

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.
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.

Next

  • How it works: one purchase through the browser, the Worker, your systems and the provider.
  • Security: what each key and token opens, and why the browser cannot set a price.
  • Configuration: describe your shop in one file.

On this page