Recipes

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:

src/erp.ts
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

src/worker.ts
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:

backend/erp-shipments.ts
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; deliverOrder runs 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_failed in 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 as order.fulfilled.

Variations

Next

  • Orders & refunds: refunds by Line, partial shipments and the Order list.
  • Order events: tell other systems, such as accounting, what happened.

On this page