# 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](/recipes/erp-prices-and-stock). Below, `erp` stands for it. The
backend part needs the secret key from [`orbcart dev`](/sdks/cli).

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

```ts title="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

```ts title="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:

```ts title="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`](/integrations/events#the-catalog).

## Variations

* **Your ERP polls instead?** Leave out `deliverOrder`, set `fetchOrders: true` and acknowledge each
  Order: [Or let your ERP fetch Orders](/integrations/inventory#or-let-your-erp-fetch-orders).
* **Your middleware lives outside Cloudflare?** Attach `deliverOrder: http("https://…")` and check
  each call with `verifyRequest()`: [Contracts in another system](/integrations/remote-contracts).
* **A gift message or an engraving on the packing slip?** They travel in the Order:
  [A gift message, end to end](/recipes/gift-message).

## Next

* [Orders & refunds](/sdks/admin): refunds by Line, partial shipments and the Order list.
* [Order events](/integrations/events): tell other systems, such as accounting, what happened.