Everything you need to connect the LataSys 3PL Connector to ShipHero: prerequisites, connection setup, mappings, capabilities and provider-specific behaviour.

What this adapter provides

Prerequisites

• The LataSys 3PL Connector (core app) installed and licensed.
• A ShipHero account with API access and developer user credentials (email and password), or an existing refresh token.
• Your account's API request quota (credits) accommodates your sync cadences - the adapter respects the quota, but very aggressive cadences on large catalogues consume it faster.

Installation

Install the LataSys 3PL Connector: ShipHero 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

Authentication is a Bearer token with refresh:

1. Choose the environment and leave the API root URL at its default unless instructed otherwise.
2. Enter either the developer-user email and password (the adapter obtains and refreshes tokens itself), or paste an existing refresh token.
3. Press Test Connection - Draft moves to Connected.

Tokens live around 28 days. The daily token cron renews them two days before expiry; you never manage tokens manually. If credentials are revoked on the provider side, flows log a clear token error in the Sync Log until they are re-entered.

Mappings

• Warehouses - press Fetch Warehouses to pull the warehouse ids straight into the mappings, then link each to its Odoo warehouse.
• Carriers - pick the carrier source on the instance form, then press Fetch Carriers. Use Historical Orders (the default, works on every account) sweeps the shipping labels of despatched orders, compiles the carrier/service pairs actually used, auto-maps them and creates delivery methods for anything unmatched. Use Experimental Functionality queries ShipHero's experimental API for the full catalogue with display names - only available on accounts where ShipHero has enabled experimental access (an HTTP error from Fetch Carriers means it is not). Exactly one source can be active at a time. The first matching mapping wins at despatch.
• Statuses - press Load Missing Defaults to seed status meanings; the canonical column drives despatch write-back and cancellation handling.
• Requested Methods - press Load Requested Methods to pull the accepted services and add a mapping row for every requested-delivery-method value your orders have used. Mapped values decide the carrier and service sent on each order; anything unmapped falls back to the Fallback Carrier and Fallback Service below.

Webhooks

Press Register Webhooks (Synchronisation tab) to subscribe ShipHero's push events - shipment updates, order cancellations, inventory updates, return updates and purchase-order updates - to this instance's webhook URL. Events trigger a targeted check the moment they arrive; polling stays on as the safety net. Registering again is safe: already-registered subscriptions are recorded and skipped.

ShipHero Options tab

The carrier-source toggles (Use Historical Orders / Use Experimental Functionality) also live here - see Mappings above.

Shared options worth reviewing

These live on the core instance form and apply to every provider:

• Requested Method Field - the technical name of the sale-order field carrying the customer's requested delivery method. It feeds the Requested Methods mapping and the service sent to ShipHero. Leave the default on databases migrated from the legacy integration; clear it if your orders only ever use Odoo's native Delivery Method.
• Order Reference Sent - whether ShipHero receives the Odoo order number or the customer reference (falling back to the order number). The customer reference option suits sales-channel setups where the shop's own number should appear on despatch paperwork.
• Create Returns Locations (Returns settings) - creates a returns holding location per mapped warehouse under a '3PL Returns' parent outside every warehouse's stock tree, so restockable returned goods do not count towards availability, reservations or replenishment until someone transfers them back into stock.

Provider-specific behaviour

• Despatch detail comes from the shipments query: lines, quantities, lots, carrier and tracking numbers per shipment; the write-back validates the delivery, applies the instance's lot-tracking policy and creates backorders on short-ship.
• Suppliers - queued suppliers are pushed as vendors (company, email and account reference).
• Quotas - the adapter paginates conservatively to stay within ShipHero's credit-based throttling; sustained quota exhaustion surfaces as retryable Sync Log errors.

Troubleshooting

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

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