Everything you need to connect the LataSys 3PL Connector to James and James Fulfilment via the ControlPort Client API v2: prerequisites, connection setup, mappings, capabilities and provider-specific behaviour.

What this adapter provides

Prerequisites

• The LataSys 3PL Connector (core app) installed and licensed.
• A James and James account with ControlPort access, and from their side:
• an API key generated in ControlPort Settings, encoded into the bearer token per their recipe (published behind the client portal under Settings - API Authentication);
• an approved E-Commerce Channel Account (Settings - Channels; you request approval in the UI and their team approves it) - its numeric id is required before any order can be pushed;
• at least one active Return Reason if you will register returns.
• Verify the encoded token against the live account during onboarding: the encoding recipe is not public, so the token cannot be validated offline.

Installation

Install the LataSys 3PL Connector: James and James (ControlPort) 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: every request carries Authorization: Bearer <encoded token>. On the instance's Connection tab:

1. The API root URL is https://api.controlport.co.uk for every environment (ControlPort has no separate sandbox host); override only if James and James gave you a different host.
2. Paste the encoded bearer token into the API Key field, then press Test Connection. The test lists your warehouse ids - the same ids the warehouse mappings need. The instance moves from Draft to Connected and the full HTTP exchange is captured in the Sync Log.

Mappings

• Warehouses - press Fetch Warehouses and map each Odoo warehouse to its numeric ControlPort warehouse id. Orders from an unmapped warehouse are left to ControlPort's automatic (cheapest-cost) warehouse allocation; ASNs always require a mapped warehouse.
• Carriers - press Fetch Carriers to pull the carrier/service list for the first mapped warehouse. The remote carrier code is ControlPort's numeric carrier id - exactly what order create accepts as preferred_carrier_id. Note ControlPort may ignore the preference if that carrier has no suitable service for an order.
• Statuses - press Load Missing Defaults. The adapter seeds ControlPort's status vocabulary (pending, picking, awaiting_pack, packing, checking, amending, boxed, labelled, despatched, held, returned, deleted, plus the needs-attention codes) with canonical meanings; despatched triggers the despatch write-back.
• Requested Methods - press Load Requested Methods. The options are the fixed postage-speed vocabulary (0 Urgent, 1 Priority, 2 Standard, 3 Economy) plus your carriers (code = carrier id). Map each requested-delivery-method value your orders use: a 0-3 code becomes the order's postage_speed, a carrier id becomes its preferred_carrier_id. Unmapped values fall back to a keyword heuristic, then to ControlPort's default (Standard).

ControlPort Options tab

Callbacks / webhooks

ControlPort has no webhook-registration API. Two complementary routes:

• Account-wide - paste the instance's webhook URL (Connection tab) into ControlPort's own settings as the Order / ASN callback URL.
• Per-record - switch on Send Callback URLs and the adapter attaches the webhook URL to every order and ASN it sends.

Either way, inbound events trigger a targeted re-check of the referenced record; scheduled polling remains the safety net.

Provider-specific behaviour

• Integer ids everywhere - ControlPort keys orders, products, warehouses, carriers, batches, suppliers and ASNs by its own integer ids. Order and ASN lines are resolved from SKUs to ControlPort product ids at push time; a push fails with the full list of unknown SKUs, so push the products first.
• Contacts - ControlPort requires name, phone, address line 1, city, country NAME (not code) and postcode on every shipping, billing and supplier contact; missing data raises a clear error before anything is sent.
• State-gated edits - amendments are accepted until the order starts picking (lines, billing, warehouse) or is labelled (address, speed, tracked/signed-for); holds toggle until picking; cancels are possible until labelled (pending orders are deleted, processing orders return to stock). Later attempts surface as retryable logged errors with ControlPort's own message.
• Products - creation requires a harmonised code (8-10 digits, from the Odoo HS Code, 00000000 placeholder when unset), a customs description (the product name, trimmed to 40 characters) and an alpha-3 country of origin (converted from the product's origin country, falling back to the company country).
• Returns - registering a return notifies ControlPort of the expected items and creates a return ASN; the API produces no label (tracked return labels are a separate ControlPort feature their customer service enables per account). Returned orders are also discovered by polling orders in status returned; quantities are taken from the despatched parcels, as the REST API does not expose per-line received-return figures - the Order Return callback carries the authoritative event.
• GRNs - ASN status booked_in marks the delivery complete and books the announced quantities; the received/discrepancy breakdown (stockable vs unstockable) only travels on the ASN Update callback.
• ASNs expire - ControlPort expires ASNs after a prolonged period of inactivity (about 90 days); only active or expired ASNs can be cancelled.

Troubleshooting

See also: James and James (ControlPort) adapter - process maps for the end-to-end flow diagrams.

James and James, James and James Fulfilment and ControlPort are trademarks of their respective owner; the names are used solely to identify the service this module interoperates with.