Skip to content

ERP integration

This guide is for ERP and finance systems integrating with ShipperOne to drive stock allocation and fiscal invoicing of fulfillment orders, and to register credit memos for returns. 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).

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).
  • Issue a credit memo for every return and register it with ShipperOne (creditmemo).

If you also need to handle the warehouse-side accept decision (with per-item qty, where qty=0 rejects the item) and the dispatch-with-carrier step, see the Fulfillment partner integration guide. A single integrator may combine both roles.

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

StageERP responsibility
Pending allocationReserve stock against the order; confirm allocation back to ShipperOne.
Pending invoiceIssue a fiscal invoice for the items that shipped.
Pending credit memo (returns)Issue a credit memo for every return.

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.

For returns, the ERP owns the credit memo: every return waits in pending_creditmemo until the ERP registers its credit memo, which completes the return.

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

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[] — the accepted items only. Each item has its own id, a sales_order_item_id linking it to the line on the sales order, 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.

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
{
"allocation": {
"order_id": "FO-000012345",
"items": [
{ "item_id": 55501 },
{ "item_id": 55502 }
]
}
}

items[] must list every item returned for the order in pending_allocation — allocation applies to the fulfillment order as a whole. A missing or extra item_id returns 400. Re-sending allocate for an order that is already allocated returns the current order state without re-processing.

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.

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. A fulfillment order is always shipped as a whole. Partial fulfillment of a customer order happens earlier: ShipperOne may split one sales order into several fulfillment orders, and the warehouse may accept less than the ordered quantity of an item, or reject it (qty=0). Each fulfillment order then reaches pending_invoice on its own, with only its accepted items and quantities.

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).
  • items[] lists the accepted items only, with their accepted qty. Items rejected at accept are not part of the fulfillment order any more; if ShipperOne reroutes them, they arrive in a separate fulfillment order. To see how a whole customer order is progressing, read the sales order — its items carry qty_shipped, qty_invoiced and qty_canceled.

See GET /V1/fulfillmentOrders/pending_invoice.

POST /rest/{store_code}/V1/fulfillmentOrder/invoice
Authorization: Bearer <your-token>
Content-Type: application/json
{
"invoice": {
"order_id": "FO-000012345",
"invoice_number": "INV-2026-000123",
"invoice_time": "2026-10-30T11:41:43+00:00",
"items": [
{ "item_id": 55501 },
{ "item_id": 55502 }
],
"shipping_amount_incl_tax": 4.99
}
}

Request fields:

  • invoice_number — required. Your fiscal invoice number.
  • invoice_time — optional, ISO 8601 with offset (yyyy-mm-ddThh:mm:ss+hh:mm).
  • additional_data — optional JSON-encoded string with extra data to store on the invoice.
  • doc_binary — optional, the invoice document to attach: the PDF file content, base64-encoded (line breaks in the base64 text are allowed). Anything that does not decode to a PDF returns 400 ("doc_binary": "Invalid content, expected a base64 encoded PDF document").

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

  • items[] — must list every item of the fulfillment order, as returned in pending_invoice.
  • shipping_amount_incl_tax — the shipping fee, including tax. Use the shipping_amount returned for the order in pending_invoice; it is 0 when the fulfillment order does not carry the shipping fee (when a sales order is split, shipping is charged on one fulfillment order only).

If either does not match, the call returns 400 with a body explaining the mismatch. This guard prevents your invoice from listing items or a shipping fee that do not belong to this fulfillment order — e.g. when you used a stale snapshot of the order.

The legacy doc_type field is no longer part of the request — remove it; sending it returns 400 ("DocType" is not supported).

See POST /V1/fulfillmentOrder/invoice.

6. Poll for returns awaiting a credit memo

Section titled “6. Poll for returns awaiting a credit memo”
GET /rest/{store_code}/V1/returns/pending_creditmemo?page=1
Authorization: Bearer <your-token>
Accept: application/json

Returns up to 100 returns that are waiting for a credit memo. Every return passes through this queue. Each return references the fulfillment order it was made against (fulfillment_order_number), the sales order (order_number), its items and amounts, and the replacement order when the customer asked for an exchange.

settlement_type tells which way the money goes: refund (money back to the customer), charge (the customer pays the difference because the replacement is worth more) or none (nothing to settle). Every return gets a credit memo regardless — how each type is booked is up to your accounting. See Returns for the full field list and how the amounts add up.

See GET /V1/returns/pending_creditmemo.

POST /rest/{store_code}/V1/return/creditmemo
Authorization: Bearer <your-token>
Content-Type: application/json
{
"creditmemo": {
"return_id": "R000000123",
"creditmemo_number": "CN-2026-000045",
"creditmemo_time": "2026-10-30T11:41:43+00:00",
"items": [
{ "item_id": 812, "qty": 1 },
{ "item_id": 813, "qty": 2 }
],
"shipping_amount_incl_tax": 4.99
}
}

Request fields:

  • return_id — required. The return number (return_number) as listed in pending_creditmemo.
  • creditmemo_number — required. Your credit memo number; it must be unique across returns.
  • creditmemo_time — optional, ISO 8601 with offset (yyyy-mm-ddThh:mm:ss+hh:mm).
  • additional_data — optional JSON-encoded string with extra data to store on the credit memo.
  • doc_binary — optional, the credit memo document to attach: the PDF file content, base64-encoded. Anything that does not decode to a PDF returns 400.

Two validation fields must match the return:

  • items[] — must list every item of the return, each with its returned qty (item_id is the return item id).
  • shipping_amount_incl_tax — the shipping refunded with the return, including tax. Use the return_shipping_amount returned for the return; it is 0 when the return does not include shipping.

If either does not match, the call returns 400 with a body explaining the mismatch. Like the invoice guard, this keeps your credit memo from being registered against a stale snapshot of the return. The credit memo always covers the return as recorded in ShipperOne.

Registering the credit memo completes the return (status: complete) and removes it from pending_creditmemo. Re-sending the same creditmemo_number for a completed return returns it without re-processing; a different number returns 400.

See POST /V1/return/creditmemo.