ORBCART DOCUMENTATION
Stock & ERP hand-off
Limit purchases to what you can ship, hold it during checkout, and hand every Order to your ERP.
Both are optional. Without inventory, stock never limits a purchase. Without
deliverOrder, your ERP fetches Orders itself.
Check stock
Start with check. It answers how many units you can supply right now:
export default defineCommerce({
channels,
offers,
inventory: {
check: async (references, { signal }) => {
const stock = await erp.stock(
references.map((r) => r.reference),
{ signal },
);
return stock.map((item) => ({ reference: item.sku, available: item.quantity }));
},
},
});OrbCart calls check for the binding Quote (with a reservation, reserve answers
instead, see below). A reference you do not name is
unlimited, like an e-book. The buyer sees the result in cart.changes:
| Stock | What the buyer sees |
|---|---|
| Enough | Nothing. The Quote takes the full quantity. |
| Some | quantity_changed from 3 to 2. The Quote takes 2. |
| None | unavailable with reason sold_out. The Line is not quoted. |
Reserve stock during checkout
check alone can sell the last unit twice when two buyers pay at the same moment.
Add reserve, release and commit to hold stock from Quote to Order.
The three come together:
inventory: {
check: (references) => erp.stock(references),
reserve: (hold) => erp.reserve(hold),
release: (holdId) => erp.release(holdId),
commit: (holdId, orderId) => erp.commit(holdId, orderId),
},| Function | When OrbCart calls it | Your job |
|---|---|---|
reserve | A Quote is created. | Hold hold.references until hold.expiresAt. |
release | The hold runs out without an Order. | Free the hold. A second call must do no harm. |
commit | The Order is placed. | Turn the hold into a booking for orderId. |
Each hold has its own hold.id. OrbCart may call again with the same ID after a
timeout. Reserving the same ID twice must hold stock once. A later expiresAt
extends the hold.
While stock is held, quote.hold.expiresAt is set. Use it for a countdown if you like.
Hand Orders to your ERP
deliverOrder receives every new Order, after the buyer has paid:
deliverOrder: async (order, { signal }) => {
const salesOrder = await erp.createSalesOrder(order, { signal });
return { reference: salesOrder.number };
},- Called at least once. Until your ERP answers, OrbCart retries, from every second up to every hour. An ERP that is down for an hour gets the Order when it is back.
- Deduplicate by
order.id. It is always the same for one Order. This is your only duty. - Return your own number as
reference. It appears on the Order's hand-off.
The budget is 30 seconds per attempt. The buyer never waits for it: they see their confirmation as soon as the payment is through. The recipe Send paid Orders to your ERP maps an Order to a sales order and reports shipments back.
What's in the Order
Everything your ERP needs, frozen at the moment the buyer agreed:
order.number; // "NG-2026-004711"
order.contact.email; // the buyer's email
order.quote.lines; // reference, quantity, configuration, offer, totals, taxes
order.quote.shipTo; // delivery address
order.quote.shipping; // the chosen method and its price
order.quote.totals; // subtotal, discount, shipping, tax, total
order.quote.extensions; // your cart extensions, such as a gift message
order.payment; // method, provider and its referenceOr let your ERP fetch Orders
Some ERPs poll instead of receiving. Leave out deliverOrder and say so with
fetchOrders:
export default defineCommerce({
channels,
offers,
fetchOrders: true,
});Every new Order then waits as handoff: "pending" until you acknowledge it. Read
the waiting Orders with the Admin SDK and take each once:
let page = await admin.orders.list({ handoff: ["pending"] });
while (true) {
for (const summary of page.data) {
const order = await admin.orders.get(summary.id);
if (order.handoff === "delivered") continue; // taken, the list is just behind
const salesOrder = await erp.createSalesOrder(order); // keyed by order.id
await admin.orders.acknowledge(order.id, { reference: salesOrder.number });
}
if (!page.next) break;
page = await admin.orders.list({ handoff: ["pending"], after: page.next });
}- The list is a fast index, seconds behind. An Order you just acknowledged may still be listed on the next poll, and a brand-new one may not be listed yet.
get()is always current, so checkhandoffthere. Poll again later for what is not listed yet. - Deduplicate by
order.idin your ERP, as withdeliverOrder. If you crash betweencreateSalesOrderandacknowledge, the next poll takes the Order again and must find the sales order it already made. - Acknowledging twice changes nothing. The first
referencestays. - A waiting Order is not a failure. Unlike
deliverOrder, which raiseshandoff_failedafter 30 minutes, a fetching ERP may wait as long as it likes. Filter withhandoff: ["pending"]to see the queue.
Report shipments back
When your ERP ships units, record them with
admin.orders.fulfill().