ORBCART DOCUMENTATION
Send paid Orders to your ERP
Hand every paid Order to your ERP exactly once, keep OrbCart's Line IDs there, and report shipments back so the buyer's order page shows the tracking.
You make every paid Order arrive in your ERP as a sales order, exactly once, even when the ERP is down for an hour. When the warehouse ships, the ERP reports it back, and the buyer's order page shows the parcel with its tracking.
You need a commerce Worker, and an ERP client such as ask from
Prices and stock from your ERP. Below, erp stands for it. The
backend part needs the secret key from orbcart dev.
1. Map the Order to a sales order
deliverOrder gets each new Order after the buyer has paid. Hand it over and return the ERP's number:
import type { DeliverOrderContract } from "@orbcart/runtime";
export const deliverOrder: DeliverOrderContract = async (order, { signal }) => {
const { shipTo, shipping, lines, totals } = order.quote;
const salesOrder = await erp.createSalesOrder(
{
externalId: order.id,
number: order.number, // such as NG-2026-004711
email: order.contact.email,
shipTo,
shippingMethod: shipping?.id,
lines: lines.map((line) => ({
line: line.id, // keep it: shipments and refunds name Lines by it
sku: line.reference,
quantity: line.quantity,
total: line.totals.total,
})),
total: totals.total,
},
// OrbCart calls again until the ERP answers, always with the same order.id.
{ idempotencyKey: order.id, signal },
);
return { reference: salesOrder.number };
};Deduplicating by order.id is your one duty. Most ERPs take an external ID or an idempotency key for
this; if yours does not, look the ID up before you create. The Order holds every amount frozen as the
buyer agreed, so never recalculate one.
2. Attach it
import { defineCommerce } from "@orbcart/runtime";
import { deliverOrder, inventory, offers } from "./erp";
export * from "@orbcart/runtime/objects";
export default defineCommerce({ channels, offers, inventory, deliverOrder });3. Report shipments back
When the ERP ships, it calls your backend. Tell OrbCart with the Admin SDK and the secret key:
import { createAdmin } from "@orbcart/admin";
import { z } from "zod";
const admin = createAdmin({ url: env.ORBCART_URL, key: env.ORBCART_SECRET_KEY });
// What the ERP posts when a delivery leaves the warehouse.
const Delivery = z.object({
externalId: z.string(),
deliveryNumber: z.string(),
trackingNumber: z.string(),
items: z.array(z.object({ line: z.string(), quantity: z.int().positive() })),
});
export async function handle(request: Request): Promise<Response> {
const delivery = Delivery.parse(await request.json());
await admin.orders.fulfill(delivery.externalId, {
reference: delivery.deliveryNumber, // the same delivery twice changes nothing
carrier: "DHL",
tracking: delivery.trackingNumber,
lines: delivery.items,
});
return new Response(null, { status: 204 });
}Check the ERP's call the way its docs say before you trust the body. A delivery may hold part of an Order: name only the Lines and quantities that left.
What the buyer sees
- The confirmation at once. The buyer never waits for the ERP;
deliverOrderruns after the payment is secured. - Nothing, when the ERP is down. OrbCart retries from every second up to every hour. After 30
minutes the Order shows
handoff_failedin the Explorer, and the next success clears it. - The parcel on the order page, with carrier and tracking, once you call
fulfill. Your systems hear it asorder.fulfilled.
Variations
- Your ERP polls instead? Leave out
deliverOrder, setfetchOrders: trueand acknowledge each Order: Or let your ERP fetch Orders. - Your middleware lives outside Cloudflare? Attach
deliverOrder: http("https://…")and check each call withverifyRequest(): Contracts in another system. - A gift message or an engraving on the packing slip? They travel in the Order: A gift message, end to end.
Next
- Orders & refunds: refunds by Line, partial shipments and the Order list.
- Order events: tell other systems, such as accounting, what happened.
Prices and stock from your ERP
Answer OrbCart's offers and inventory contracts from an ERP over HTTP, with one request per call, parsed answers and a reservation that never sells the last unit twice.
Free shipping and a welcome code
Free standard shipping from €50 without a code, 10 % off with WELCOME10, a code field in the bag, and a test that proves both.