ShipBob adapter - process maps
How every flow in the LataSys 3PL Connector runs when the ShipBob
adapter is installed. Transport: ShipBob Developer API 2026-07
(REST/JSON) over HTTPS - api.shipbob.com, or
sandbox-api.shipbob.com on sandbox instances. Auth: Personal Access
Token as a Bearer token, plus the shipbob_channel_id header on
every write (cached on the instance by Test Connection).
Shared behaviour for every flow below:
- Triggers - the scheduler (per-instance cadences on the Synchronisation tab), the Run-an-Operation wizard, per-record buttons, or a webhook delivery; polling remains the net.
- Logging - every run writes a Sync Log entry: full request and response (URL, headers with credentials redacted, body), every Odoo action taken, and every record touched. Errors are retryable from the log entry.
- Watermarks - each flow stamps its last-run time on the instance; the scheduler only fires when the cadence has elapsed.
- License - flows pause if the licensing service reports the installation suspended for non-payment.
1. Connection test and channel discovery
| Test Connection | GET /channel - validates the PAT and lists the channels behind it. An empty Channel ID is auto-filled (a channel with orders_write scope wins) |
| Fetch Warehouses | GET /fulfillment-center - offers the numeric FC ids on the warehouse mapping line |
| Load Requested Methods | GET /shipping-method - the merchant's Ship Option Mapping names become the Accepted Services list |
2. Order push
| Trigger | Cron (order cadence), wizard, auto-send on confirmation |
| Direction | Odoo -> ShipBob |
| Data sent | Recipient name, address, email, phone; SKUs, quantities, prices; shipping method; purchase date; fulfillment center; tags (customer ref, delivery/packing notes) |
| Odoo records | 3PL Order binding (pending -> sent) |
| Failure | Retryable Sync Log error; nothing partially written |
3. Status poll and despatch write-back (tracking delta)
| Trigger | Cron (status cadence), manual, order.shipped / order.shipment.tracking.updated webhooks |
| Direction | ShipBob -> Odoo |
| Data received | Order + shipment statuses; per-SKU shipped quantities with lot numbers and expiration dates; carrier, service, tracking numbers and URL |
| Odoo records | Delivery picking validated (with lots on lot-tracked instances); backorders; carrier + tracking on the picking; binding state despatched |
| Checkpoint | With Mark Tracking Uploaded on (default), the shipments are flagged at ShipBob after the write-back - best-effort, a failed flagging only means the order reappears next poll |
| Failure | Savepoint-protected - a failed write-back leaves no partial documents; error is retryable |
4. Order amendment
| Trigger | Update at 3PL on an order with at least one shipment not yet labelled |
| Calls | GET /order/{id}, then per shipment PUT /shipment/{id}:updateAddress; line items via POST /shipment/{id}:updateLineItems only when the order has exactly ONE open shipment |
| Data sent | Recipient address/contact; full replacement line list keyed on ShipBob inventory ids (resolved from SKUs via the catalogue) |
| Outcome | Per-shipment is_success flags checked; the amendment errors only when no shipment accepted anything. Shipping method changes are not possible after creation |
5. Order cancellation
| Trigger | Order cancelled in Odoo |
| Calls | POST /order/{id}:cancel (channel header required) |
| Outcome | ShipBob cancels the order and all shipments; once a shipment is labelled the cancel is rejected and the order is flagged instead |
6. Inventory sync
ShipBob reports stock account-wide - map ONE Odoo warehouse per instance. Lot detail is fetched per inventory item, so lot-tracked catalogues poll one extra call per SKU.
7. Product push and match
| Match | GET /product (cursor-paginated) - every variant's SKU, name and barcode (UPC/GTIN); Odoo products match by SKU and bindings are created |
| Push (new) | POST /product - name, type Regular, one variant with SKU, weight (converted kg -> oz) and UPC barcode |
| Push (re-push) | The SKU is looked up first; existing products update via PATCH /product/{id} with the variant id |
8. ASN / GRN (Warehouse Receiving Orders)
ShipBob requires a tracking number per box - the receipt's Tracking Reference is sent, falling back to the ASN reference.
9. Returns
10. Webhooks
| Register | POST /webhook once per topic: order.shipped, order.shipment.tracking.updated, order.shipment.delivered, order.shipment.cancelled, return.updated, wro.completed - partial success is visible per topic |
| Deliveries | HMAC-SHA256 signed (webhook-signature header), retried with exponential backoff for 24 hours, may arrive out of order - handled idempotently |
| Net | Polling cadences remain active as the safety net |
ShipBob is a trademark of its respective owner; the name is used solely to identify the service this module interoperates with.