ERP integration

This guide is for ERP and finance systems integrating with ShipperOne to drive stock allocation and fiscal invoicing of fulfillment orders. The ERP does not perform physical shipment — that is handled by ShipperOne (local courier integration) or by a separate fulfillment partner (3PL, dropshipper, or in-house warehouse).

Audience and scope

You should follow this guide if your system needs to:

• Reserve stock against incoming fulfillment orders before they are dispatched (allocate).
• Generate fiscal invoices once goods are shipped (invoice).
• Optionally, in a later phase: process returns against previously invoiced orders.

If you also need to handle the warehouse-side accept/reject decision and the dispatch-with-carrier step, see the Fulfillment partner integration guide. A single integrator may combine both roles.

Stages handled by the ERP

The ERP owns two of the four fulfillment order stages — see Fulfillment order lifecycle for the full picture.

Stage	ERP responsibility
Pending allocation	Reserve stock against the order; confirm allocation back to ShipperOne.
Pending invoice	Issue a fiscal invoice for the items that shipped.

Between these two stages, ShipperOne handles physical shipment — either through its built-in courier integration or by routing the order to a connected fulfillment partner. The ERP does not need to know which path was taken; the order simply reappears in pending_invoice once shipped.

In total the ERP polls two queues (pending_allocation, pending_invoice) and calls two action endpoints (allocate, invoice).

Step-by-step flow

1. Poll for orders awaiting allocation

GET /rest/{store_code}/V1/fulfillmentOrders/pending_allocation?page=1
Authorization: Bearer <your-token>
Accept: application/json

Returns up to 100 fulfillment orders that have been accepted by a warehouse and are waiting for stock allocation. Each order carries:

• A top-level warehouse_code — the location stock is being allocated from.
• items[] — each item has its own id and (when the item lives in a different warehouse than the order) a per-item warehouse_code indicating an inter-warehouse transfer is needed.

See the full schema at GET /V1/fulfillmentOrders/pending_allocation.

2. Reserve stock and confirm allocation

For each fulfillment order, reserve the listed items in your ERP, then confirm back to ShipperOne:

POST /rest/{store_code}/V1/fulfillmentOrder/allocate
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "order": {
    "order_id": "FO-000012345",
    "items": [
      { "item_id": 55501 },
      { "item_id": 55502 }
    ]
  }
}

Confirming allocation transitions the order to the shipping stage. ShipperOne (or a downstream fulfillment partner) will then dispatch the goods. See POST /V1/fulfillmentOrder/allocate for the response schema.

3. ShipperOne ships the order

This step is not an ERP responsibility. Depending on tenant configuration, ShipperOne ships via:

• Local courier integration (managed in the ShipperOne admin), or
• A connected fulfillment partner (which calls POST /V1/fulfillmentOrder/ship itself — see Fulfillment partner integration).

After shipment, the fulfillment order moves into pending_invoice. Partial shipment is supported — if only some items shipped, the next step’s pending_invoice payload reflects only the shipped subset.

4. Poll for orders awaiting invoice

GET /rest/{store_code}/V1/fulfillmentOrders/pending_invoice?page=1
Authorization: Bearer <your-token>
Accept: application/json

Returns fulfillment orders that have been shipped and are ready to invoice. Notes specific to this endpoint:

• warehouse_code is present on the order level only (no per-item field, since by this stage every item has been allocated and shipped from a known location).
• After a partial shipment, the order may appear here with fewer items than were originally placed. Only the shipped subset is invoiceable; remaining items will appear in a later pending_invoice response after their own shipment.

See GET /V1/fulfillmentOrders/pending_invoice.

5. Issue the invoice

POST /rest/{store_code}/V1/fulfillmentOrder/invoice
Authorization: Bearer <your-token>
Content-Type: application/json

{
  "order": {
    "order_id": "FO-000012345",
    "items": [
      { "item_id": 55501 }
    ],
    "shipping_amount_incl_tax": 4.99
  }
}

Two validation fields must match the current ShipperOne state of the order:

• items[] — the line items being invoiced. Must match what ShipperOne shows as currently shipped on this order.
• shipping_amount_incl_tax — the shipping fee, including tax.

If either does not match, the call returns 400 with a body explaining the mismatch. This guard prevents your invoice from listing items that were never actually shipped (e.g. after a partial shipment where you used a stale snapshot of the order).

The legacy doc_type field is no longer required and is ignored if sent.

See POST /V1/fulfillmentOrder/invoice.