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).
Audience and scope
Section titled “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).
- 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.
Stages handled by the ERP
Section titled “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. |
| 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).
Step-by-step flow
Section titled “Step-by-step flow”1. Poll for orders awaiting allocation
Section titled “1. Poll for orders awaiting allocation”GET /rest/{store_code}/V1/fulfillmentOrders/pending_allocation?page=1Authorization: Bearer <your-token>Accept: application/jsonReturns 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 ownid, asales_order_item_idlinking it to the line on the sales order, and (when the item lives in a different warehouse than the order) a per-itemwarehouse_codeindicating an inter-warehouse transfer is needed.
See the full schema at GET /V1/fulfillmentOrders/pending_allocation.
2. Reserve stock and confirm allocation
Section titled “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/allocateAuthorization: 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.
3. ShipperOne ships the order
Section titled “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/shipitself — 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.
4. Poll for orders awaiting invoice
Section titled “4. Poll for orders awaiting invoice”GET /rest/{store_code}/V1/fulfillmentOrders/pending_invoice?page=1Authorization: Bearer <your-token>Accept: application/jsonReturns fulfillment orders that have been shipped and are ready to invoice. Notes specific to this endpoint:
warehouse_codeis 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 acceptedqty. 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 carryqty_shipped,qty_invoicedandqty_canceled.
See GET /V1/fulfillmentOrders/pending_invoice.
5. Issue the invoice
Section titled “5. Issue the invoice”POST /rest/{store_code}/V1/fulfillmentOrder/invoiceAuthorization: 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 inpending_invoice.shipping_amount_incl_tax— the shipping fee, including tax. Use theshipping_amountreturned for the order inpending_invoice; it is0when 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=1Authorization: Bearer <your-token>Accept: application/jsonReturns 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.
7. Register the credit memo
Section titled “7. Register the credit memo”POST /rest/{store_code}/V1/return/creditmemoAuthorization: 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 inpending_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 returnedqty(item_idis the return itemid).shipping_amount_incl_tax— the shipping refunded with the return, including tax. Use thereturn_shipping_amountreturned for the return; it is0when 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.