Integrations
The same ShipperOne API is consumed in different sequences by different kinds of integrators. These guides walk through the flow per role — what endpoints to call, in what order, and with which payloads.
Roles covered
Section titled “Roles covered”-
ERP integration — for finance / ERP systems that drive allocation and invoicing, and register credit memos for returns. Polls
pending_allocation,pending_invoiceandpending_creditmemo; callsallocate,invoiceandcreditmemo. Does not handle physical shipment. -
Fulfillment partner integration — for any party that physically fulfils orders: 3PLs, dropshippers, or in-house warehouses (often running a WMS). Polls
pending_acceptandpending_shipment; callsaccept(withqtyper item;qty=0rejects that item) andship. Also has read-only access to afailedqueue for diagnostics. -
Reading data — for any system that only needs to read: reporting, reconciliation, customer service tools, or an ERP that books sales orders and returns. Covers sales orders, fulfillment orders and returns. Only the read endpoints are needed.
Fulfillment order lifecycle
Section titled “Fulfillment order lifecycle”A fulfillment order is a unit of work produced by ShipperOne when a customer order (a sales order) is routed to a location. One sales order can be split into several fulfillment orders, one per location. It progresses through four stages, each with its own polling endpoint and a matching action endpoint that moves the order forward:
| # | Stage | What happens | Polling endpoint | Action endpoint | Owner |
|---|---|---|---|---|---|
| 1 | Pending accept | Warehouse decides if it can fulfil | GET /V1/fulfillmentOrders/pending_accept | POST /V1/fulfillmentOrder/accept (per-item qty; 0 rejects) | Fulfillment partner |
| 2 | Pending allocation | Stock is reserved against the order | GET /V1/fulfillmentOrders/pending_allocation | POST /V1/fulfillmentOrder/allocate | ERP |
| 3 | Pending shipment | Order is picked, packed and dispatched | GET /V1/fulfillmentOrders/pending_shipment | POST /V1/fulfillmentOrder/ship | Fulfillment partner |
| 4 | Pending invoice | Fiscal invoice is issued for shipped items | GET /V1/fulfillmentOrders/pending_invoice | POST /V1/fulfillmentOrder/invoice | ERP |
Return lifecycle
Section titled “Return lifecycle”A return records goods sent back against a shipped fulfillment order. Every return waits for a credit memo from the ERP; registering it completes the return.
| Stage | What happens | Polling endpoint | Action endpoint | Owner |
|---|---|---|---|---|
| Pending credit memo | Credit memo is issued for the return | GET /V1/returns/pending_creditmemo | POST /V1/return/creditmemo | ERP |
Common conventions
Section titled “Common conventions”These rules apply across both guides:
- Authentication — every request carries a Bearer token. See Authentication for details.
- Base URL — each customer runs its own ShipperOne instance; substitute your tenant hostname for
YOUR_SHIPPER_BASE_URLin all examples. - Path prefix — every REST URL is shaped
https://YOUR_SHIPPER_BASE_URL/rest/{store_code}/V1/…. Yourstore_codeis provided alongside your token — typicallyallon single-store tenants, or a country code (rs,hr,me, …) on multi-country tenants. items[]payload — every action that operates on line items takes an explicititems[]array. A sales order is fulfilled partially by splitting it into fulfillment orders and by the per-itemqtydecision onaccept; after accept,allocate,shipandinvoiceact on the fulfillment order as a whole, and theiritems[]must list every accepted item. See the Fulfillment partner integration guide for details.- Read-only lists — every list endpoint returns a fixed page of at most 100 records — 10,000 for
GET /V1/stockItems— (?page=1,?page=2, …; iterate until you receive an empty array) and acceptsdate=yyyy-mm-dd hh:mm:ssto return only records updated since that time. An invalidpageordatereturns 400.