Everything you need to connect the LataSys 3PL Connector to ShipBob: prerequisites, connection setup, mappings, capabilities and provider-specific behaviour. ShipBob's Developer API is versioned REST/JSON (this adapter speaks the 2026-07 version).

What this adapter provides

Prerequisites

• The LataSys 3PL Connector (core app) installed and licensed.
• A ShipBob merchant account (production, or a sandbox account on sandbox-api.shipbob.com).
• A Personal Access Token (PAT) created in the ShipBob dashboard under Integrations > API Tokens. The token owns a channel - ShipBob's per-integration data scope - which this adapter discovers automatically.

Installation

Install the LataSys 3PL Connector: ShipBob Adapter module. The provider then appears in the provider list when creating a 3PL instance, along with its provider card (API operations reference) under Configuration - Providers.

Connection setup

1. Create the instance with provider ShipBob and pick the environment - Sandbox targets sandbox-api.shipbob.com (sandbox accounts have their own tokens), Production targets api.shipbob.com.
2. Enter the PAT in the API Key field and press Test Connection. The test calls GET /channel, validates the token and auto-fills the Channel ID on the ShipBob Options tab (preferring a channel with orders_write scope). The channel id is sent as the shipbob_channel_id header on every write and scopes reads to this integration's own orders.

Mappings

• Warehouses are fulfillment centers - press Fetch Warehouses and pick the numeric ShipBob fulfillment center id on the mapping line. The mapped center pins order creation (location_id), receiving orders and returns. Note that ShipBob reports stock account-wide across its network - map ONE Odoo warehouse per instance so quantities are not double-counted.
• Shipping methods via Requested Methods - press Load Requested Methods to pull the merchant's Ship Option Mapping names from GET /shipping-method, then map your requested-delivery-method values onto them. The mapping wins; the raw requested value and the carrier mapping's service code are the fallbacks; the instance's Default Shipping Method (Standard) is the last resort. A name ShipBob does not recognise is created on their side and defaults to Standard.
• Statuses - press Load Missing Defaults. Completed, LabeledCreated and Fulfilled count as despatched (a labelled shipment already carries tracking); OnHold and Exception surface as Hold; Cancelled/CleanSweeped follow your remote-cancel policy.

ShipBob Options tab

Provider-specific behaviour

• References - our configured order reference is sent as ShipBob's immutable reference_id (and the Odoo order name as the display order_number); ShipBob's numeric order id becomes the remote reference. Orders split into one or more shipments, each with its own status, tracking and lot detail - multi-parcel orders write back every tracking number.
• Tracking delta - ShipBob's recommended polling pattern is supported end to end: despatched-but-unsynced orders are the HasTracking=true&IsTrackingUploaded=false filter, and after each despatch write-back the shipments are flagged via POST /shipment:batchUpdateTrackingUpload so nothing is processed twice. The flagging is best-effort - a failed checkpoint never breaks the write-back; the order simply reappears next poll.
• Amendments are per shipment - ShipBob has no order-level update. The delivery address is pushed to every shipment not yet labelled or cancelled (:updateAddress); line items are a FULL replacement keyed on ShipBob inventory ids and are only pushed when the order has exactly one open shipment (replaying the order's lines onto each shipment of a split order would duplicate them). Both endpoints answer HTTP 200 with an is_success flag - the adapter checks it and only errors when no shipment accepted anything. The shipping method cannot be changed after creation.
• Notes travel as tags - ShipBob has no free-text instruction field its warehouse acts on; the customer reference, delivery note and packing note are attached as order tags (visible over the API, not in the Merchant Portal).
• Inventory ids - shipment line items and returns are keyed on ShipBob's inventory id, not the SKU. The adapter resolves them from the product catalogue (GET /product) on demand.
• Stock - the fulfillable quantity syncs (on-hand minus committed). On instances with "Products Use Batch/Lot Tracking" enabled, lot lines come from the per-item grouped-by-lot endpoint; when the mapped fulfillment center appears in a lot's location breakdown, that location's quantity wins over the account total.
• ASNs are Warehouse Receiving Orders - one box (EverythingInOneBox), the receipt's lines as box items and the receipt's scheduled date as the expected arrival. ShipBob requires a tracking number per box: the receipt's Tracking Reference is used, falling back to the ASN reference (which then doubles as the box label identifier). The WRO response carries a box_labels_uri packing slip - include it in each box. GRNs read the WRO's received quantities (no lot breakdown on the read side).
• Returns - registering a return creates a ShipBob return order with requested action Restock; ShipBob does not generate a customer shipping label, and the return reference (RMA) must appear on the box. The returns poll maps ShipBob's inventory-id lines back to SKUs via the catalogue; processed quantities and actions (Restock/Dispose/Quarantine) become the received quantities and grading.
• Webhooks - Register Webhooks subscribes six topics (order.shipped, order.shipment.tracking.updated, order.shipment.delivered, order.shipment.cancelled, return.updated, wro.completed) to the instance webhook URL, one subscription per topic so a missing scope fails only its own topic. Deliveries are HMAC-SHA256 signed (webhook-signature header) and retried with exponential backoff for 24 hours; polling remains the safety net.

Troubleshooting

See also: ShipBob adapter - process maps for the end-to-end flow diagrams.

ShipBob is a trademark of its respective owner; the name is used solely to identify the service this module interoperates with.