Core concepts

Your catalog stays yours. OrbCart only needs to know what the buyer can purchase, for how much, and under which conditions.

Offer

What you are willing to sell right now. An Offer contains a reference, title, price and tax category. Physical goods also carry shipping facts.

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

8990 means €89.90, not €8,990. Amounts are integers in the currency's smallest unit. Never send a floating-point price.

An Offer is not a catalog entry. Your offers function supplies it when OrbCart needs current facts.

Line

What the buyer chose. A Line names an Offer by its reference, with a quantity and optional configuration. OrbCart assigns the Line an id.

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

Use the reference to add goods. Use the returned Line ID to change or remove a Line.

Cart

The purchase while it is still taking shape. A Cart holds Lines, contact and address details, shipping choices and discount codes.

Its estimate is provisional. Read estimate.excludes before presenting it as a complete total. missing tells you which details the buyer still needs to supply.

Quote

The exact purchase the buyer agrees to. A Quote freezes Lines, prices, tax, shipping and the total. It is signed and has an expiry.

If something changes before acceptance, OrbCart returns quote_changed. Show the new Quote and ask again. Never silently accept a different total.

Order

The record of the agreed purchase. An Order keeps its original amounts even when your catalog changes later. Payment, fulfillment and refund state can still change; the purchase snapshot does not.

Creating an Order and delivering it to your ERP are separate steps. If your ERP is unavailable, OrbCart retries the delivery rather than losing the Order.

Two settings worth knowing

• Environment: an isolated runtime, such as test or live. Keys belong to one environment.
• Channel: a way you sell, with its currency, tax treatment, shipping and payment methods. A publishable key selects a Channel.

Put the concepts to work →