Partner API v.1.0
This API lets you integrate directly with our platform instead of using the customer portal. It exposes:
- read access to your account's shipments: tracking, PO and container details, dates and events, documents, and current freight rates
- the ability to request quotes and create shipments, with confirmations returned directly in the response
- updating a shipment you created until it has been sent to a third-party system, and triggering the send of a shipment to the External TMS as a prealert or shipping order
- filing a shipment's US ISF-10 (Importer Security Filing) with the customs Brokerage System, with any ISF field you want to supply and the rest taken from the shipment
- creating a shipment's US customs entry in the Brokerage System the same way, with any entry field you want to supply and the rest taken from the shipment
- filing (or amending) a shipment's EU ICS2 Entry Summary Declaration (ENS) with EU customs, with any ICS2 field you want to supply and the rest taken from the shipment
- managing your SKU catalog (add, edit, and read SKUs with their stock on hand), and assigning goods lines to a SKU by its code when creating or updating a shipment
- notifying a warehouse of an inbound shipment, reporting pickup/dropoff trucker details, and initiating a consolidation of existing freight into a new warehouse stay
- asynchronous delivery of status changes and quote results via webhook (signed with a secret we issue, optionally carrying an auth header you supply — see Webhooks)
Base path:
/api/partner/v1/
Your API host is provided during onboarding. Examples in this guide use example.com as a
placeholder host.
Authentication:
Authorization: Bearer {api_token}- one token per partner account; issued out of band and tied to one or more customer companies (a token never sees data belonging to a company outside its account)
- API tokens cannot be used to sign in to the web portal
Transport requirements:
- HTTPS only
Content-Type: application/jsonon all requests and responses- all timestamps are ISO 8601 with a UTC offset (
2026-04-10T09:15:00+00:00) - the API is versioned in the URL path (
/v1/); breaking changes ship as/v2/, and/v1/is supported for at least 12 months after/v2/ships
Idempotency:
POST /shipments/,POST /shipments/{pod_id}/documents/,POST /quotes/, andPOST /skus/accept anIdempotency-Keyheader- replaying the same key returns the original response instead of creating a duplicate; keys are honored for 24 hours
- only a successful (
201) response is cached against the key — a request that fails validation isn't, so correcting and retrying with the same key is always safe - reusing a key with a different request body is rejected with
409 Conflict PATCH /shipments/{pod_id}/,PATCH /skus/...,POST /shipments/{pod_id}/send-to-tms/,POST /isf/,POST /entry/andPOST /ics2/don't take anIdempotency-Key: repeating the same update leaves the record the same, and a shipment is only ever sent to the External TMS once, its ISF filed once, its entry created once (unless you ask for a further one withnew_entry: true), and its ICS2 declaration lodged once (a repeat send returns409; an ICS2 request that changes a lodged declaration amends it)
Companies:
- if your account covers more than one company, read endpoints return data for all of them;
every shipment, quote, and SKU carries a
companyobject ({"id": 12, "name": "..."}) saying which one it belongs to, and?company_id=<id>narrows any read endpoint to one company - create endpoints (
POST /shipments/,/quotes/,/warehouse-stays/,/consolidations/,/skus/) take an optionalcompany_idin the request body (onPOST /skus/, per SKU). It can be omitted while your account has exactly one company; with more than one it is required, and a missing or unknowncompany_idis rejected with400 - endpoints that act on an existing record (accepting a quote, notifying a warehouse for an existing shipment) always use that record's own company
Sandbox mode:
- we can switch your account into sandbox mode while you build your integration; every
response then carries an
X-Sandbox-Mode: trueheader - reads (
GET) are live: they return your companies' real data, exactly as in live mode - writes (
POST/PATCH/DELETE) are validated and answered exactly as in live mode (same status codes, errors, and response bodies, including generated ids), but nothing is saved or sent on: no shipment, quote, document, or warehouse stay is created, nothing is pushed to the External TMS (tms_push.statusisnot_requested), and no webhook event fires for it. Ids returned by a sandbox write can't be read back afterwards, andIdempotency-Keyreplay isn't available - exception: webhook registration and management (
/webhooks/...) is live in sandbox mode, so the subscriptions you register stay registered and receive real events for your companies' shipments
- US customs filings (Send ISF,
Send Entry) go to the customs brokerage system your
deployment is connected to, called the Brokerage System throughout this guide. Which
system that is is set up for you by our operations team; the API, its fields
(
brokerage_reference,entry_number,filing_status, ...) and the webhook events are the same whichever system it is, so your integration doesn't change if it does filing_statusin_brokeragemeans the filing is in the Brokerage System with the broker
- shipments are sent on (Create Shipment's auto-send,
Send Shipment to External TMS) to the transport
management system our operations team runs your shipments in, called the External TMS
throughout this guide. The API, its fields (
tms_push,tms_order_id,linked_to_tms_order) and theshipment.tms_push.*webhook events are the same whichever system it is, so your integration doesn't change if it does
Pagination (all list endpoints):
{
"count": 134,
"next": "https://example.com/api/partner/v1/shipments/?page=2",
"previous": null,
"results": [ ]
}
Endpoints
1. List Shipments
GET /api/partner/v1/shipments/
Query parameters (all optional):
reference— partial, case-insensitive match on the shipment'spod_id,file_number, tracking number (the bill of lading, booking or AWB we track it by), any value inreferences, any container number, or anypo_numberon the shipmentstatus— one of the values listed under Shipment objectmode,trade,load— see Field valuesupdated_since— ISO 8601 timestamp; returns shipments updated at or after this timecompany_id— only shipments for this one of your companies (see Companies, above)page,page_size(maxpage_sizeis 100)
Response: paginated list of Shipment objects.
2. Get Shipment
GET /api/partner/v1/shipments/{pod_id}/
Returns the full Shipment object, including routing legs, parties, references, containers, pieces, and current event.
3. List Shipment Events
GET /api/partner/v1/shipments/{pod_id}/events/
Returns the event history for the shipment, oldest first. Only events marked as externally visible are returned.
{
"results": [
{
"event": "departed_origin_port",
"label": "Departed origin port",
"location": "Shanghai, CN",
"due_at": "2026-04-02T14:00:00+00:00",
"completed_at": "2026-04-02T14:00:00+00:00",
"updated_at": "2026-04-02T14:05:12+00:00",
"estimated": false
},
{
"event": "eta_destination_port",
"label": "ETA destination port",
"location": "Los Angeles, CA",
"due_at": "2026-04-20T00:00:00+00:00",
"completed_at": null,
"updated_at": "2026-04-03T08:30:00+00:00",
"estimated": true
}
]
}
estimated is true while completed_at is null — due_at is then the planned or
predicted time rather than an actual one. updated_at is when the event was last changed
on our side (e.g. a new ETA, a completed date, a re-typed event). event is the standard event code and is null for
events that have not been mapped to one; use label for display.
4. List Shipment Documents
GET /api/partner/v1/shipments/{pod_id}/documents/
Returns document metadata only, limited to documents that are visible in the customer
portal. Use the download_url on each item to fetch the file.
{
"results": [
{
"document_id": "DOC-248",
"document_type": "bol",
"file_name": "BOL-BKG-1001.pdf",
"uploaded_at": "2026-04-01T10:00:00+00:00",
"download_url": "https://example.com/api/partner/v1/documents/248/download/"
}
]
}
5. Download Document
GET /api/partner/v1/documents/{document_id}/download/
{document_id} accepts either the document_id from the documents list (DOC-248) or the bare
number (248). Streams the file. Content-Type matches the original upload;
Content-Disposition carries the original file name. Prefer the download_url from the
documents list rather than building or caching URLs yourself.
6. List Freight Rates
GET /api/partner/v1/rates/
Query parameters:
origin,destination— UN/LOCODEmode—ocean,air,rail,roadload—fcl,lcl,ftl,ltl,ftx,b2b,consol(not restricted bymodethe way Create Shipment'sloadis — a rate can be published with any mode/load pairing)container_type— e.g.40HC,20GP(ocean FCL only — see below)effective_date— defaults to today
Returns only published rates visible to your account: general rates (no customer set) plus
any rate specifically published for one of your account's companies (narrow with ?company_id=).
A rate published for a head office also applies to its branch offices, so a branch company sees
its head office's rates too (a head office does not see rates published for its branches).
Every published rate is returned — lane rates (with origin/destination/mode/load/
container_type) and facility/accessorial rate cards (storage, handling, drayage), where those
lane fields are "". The origin/destination/mode/load/container_type filters only
match lane rates.
{
"results": [
{
"rate_id": "RATE-4471",
"facility": { "code": "PDX", "name": "Portland" },
"customer": { "company_id": 12, "name": "Acme Imports" },
"charge_code": "OCFRT",
"charge_name": "Ocean Freight",
"description": "Shanghai to Los Angeles, 40HC",
"packaging_type": "",
"goods_description": "",
"quote_category": "shipping",
"rate_type": "shipment",
"origin": { "unlocode": "CNSHA", "name": "Shanghai" },
"destination": { "unlocode": "USLAX", "name": "Los Angeles" },
"mode": "ocean",
"load": "fcl",
"container_type": "40HC",
"task": null,
"pricing_basis": "flat",
"quantity_basis": "",
"uom": "",
"currency": "USD",
"all_in_rate": "3450.00",
"weight_per": null,
"volume_per": null,
"minimum": null,
"maximum": null,
"valid_from": "2026-04-01",
"valid_to": "2026-04-30",
"billing_frequency": "",
"start_milestone": "",
"end_milestone": "",
"dim_weight_ratio": null
}
]
}
Field notes:
facility/customerarenullwhen the rate applies to all facilities / all customers.charge_codeis the rate's code;charge_name, when set, is the name of the automatic charge line the rate produces;descriptionis the rate's display name.packaging_type/goods_description— when set, the rate only applies to pieces with that packaging type / whose goods description contains that text.quote_category—warehouseorshipping.rate_type—general,shipment,task, ordate_based;taskis the task/service name for task-specific rates.pricing_basis—flat,piece,quantity, ordim_weight;quantity_basis—per_pallet,per_piece,per_weight,per_volume, or"".all_in_rateis the price: the amount per unit, or the total for a flat rate.weight_per/volume_perare the weight / volume increments for per-weight, per-volume, and dim-weight pricing;minimum/maximumcap the total charge.billing_frequency(dayormonth),start_milestone, andend_milestoneare only set ondate_basedrates;dim_weight_ratio(weight per CBM) only ondim_weightrates.
container_type is only ever set for an ocean + fcl rate; it's "" for every other
mode/load combination. There is no carrier or transit_days field — this reflects a rate
card, not a live carrier quote.
7. Request a Quote
POST /api/partner/v1/quotes/
Submits a quote request. This response only confirms the request was received — rate
desks price ad hoc lanes asynchronously. The priced quote (or rejection) is delivered later
via the quote.priced / quote.rejected webhook. Use GET /quotes/{quote_request_id}/ if
you need to poll instead.
Request body:
{
"mode": "ocean",
"load": "fcl",
"origin": { "unlocode": "CNSHA", "name": "Shanghai" },
"destination": { "unlocode": "USLAX", "name": "Los Angeles" },
"ready_date": "2026-05-01",
"incoterm": "FOB",
"cargo": {
"containers": [
{ "container_type": "40HC", "count": 2 }
],
"pieces": [
{
"pieces": 48,
"packaging_type": "boxes",
"description": "widgets",
"weight": { "value": 18000, "unit": "kg" },
"dimensions": { "length": 120, "width": 125, "height": 100, "unit": "cm" },
"sku": "SKU-123",
"serial_number": "SN_123456"
}
]
},
"notes": "Requesting expedited transit if available."
}
Required fields: mode, origin, destination
Optional fields: load, ready_date, incoterm, cargo, notes
There is no reference field — a quote has no caller-supplied reference to echo back, only the
system-generated quote_request_id. Quoting is available for mode ocean, air, or road
only — rail is rejected with 400. load is one of fcl, lcl, ftl, ltl (not ftx,
b2b, consol — quoting has no load type for air). cargo.containers uses the same shape as
containers on Create Shipment, but only the first container line
is used — a quote covers one container type/count, not a mixed set. cargo.pieces descriptions
and weights are aggregated into a single total for the quote, not kept as separate lines.
Success response (201) — the full Quote object, with pricing fields still
empty:
{
"quote_request_id": "QT-7C3D1A9B4E",
"status": "submitted",
"mode": "ocean",
"load": "fcl",
"origin": { "unlocode": "CN", "name": "Shanghai" },
"destination": { "unlocode": "US", "name": "Los Angeles" },
"currency": "USD",
"all_in_rate": null,
"transit_days": null,
"valid_until": null,
"created_at": "2026-04-10T09:15:00+00:00"
}
status on creation is always submitted. See Quote object for the full
set of terminal statuses delivered via webhook. Note origin/destination on a quote only
ever carry a 2-letter country code, not the full UN/LOCODE you submitted — see the Quote
object's notes below.
8. Get Quote
GET /api/partner/v1/quotes/{quote_request_id}/
Returns the current Quote object. Useful as a fallback if a webhook delivery was missed; not required for normal operation.
This endpoint also adds a quote_pdf field: the priced quote document, inlined as base64 —
the same content_base64 shape used for document uploads. It is null until a rate desk has
finalized the quote (a draft still being priced is never exposed). The PDF is rendered at
request time, so it always reflects the current pricing, validity date and estimated transit
days. The PDF is the same freight-quote layout ops see in the quote editor's document preview,
and both it and file_name carry the quote_request_id. quote_pdf is not included on the Request a Quote response or the quote.priced
webhook — call this endpoint to fetch it.
{
"quote_request_id": "QT-7C3D1A9B4E",
"status": "priced",
"...": "... the rest of the Quote object ...",
"quote_pdf": {
"file_name": "QT-7C3D1A9B4E.pdf",
"content_type": "application/pdf",
"content_base64": "JVBERi0xLjcK..."
}
}
9. Accept a Quote
POST /api/partner/v1/quotes/{quote_request_id}/accept/
Converts a priced quote into a shipment. Equivalent to calling POST /shipments/ pre-filled
from the quote. Returns the same confirmation shape as Create Shipment,
including the resulting tms_push outcome if your account auto-sends to the External TMS. Only valid
while the quote's status is priced and before valid_until has passed.
No request body is required. The quote's quote_request_id is carried over to the shipment as a
Quote Number reference.
10. Create Shipment
POST /api/partner/v1/shipments/
Creates a shipment on your account. The response is the confirmation — there is no
separate "created" webhook. Subsequent progress is delivered via the
shipment.status_changed, shipment.event_completed, and shipment.tms_push.* webhooks
described below.
Request body:
{
"mode": "ocean",
"trade": "import",
"load": "fcl",
"incoterm": "FOB",
"origin": { "unlocode": "CNSHA", "name": "Shanghai" },
"destination": { "unlocode": "USLAX", "name": "Los Angeles" },
"parties": [
{
"name": "Blue Ocean Supply Co.",
"address_line1": "123 Factory Rd",
"city": "Shenzhen",
"state": "",
"postal_code": "518000",
"country": "CN",
"contact_name": "Li Wei",
"contact_phone": "+86 138 0000 0000",
"roles": ["pickup_from", "shipper"]
},
{
"name": "Acme Imports DC",
"address_line1": "500 Warehouse Way",
"city": "Ontario",
"state": "CA",
"postal_code": "91761",
"country": "US",
"contact_name": "Jane Doe",
"contact_phone": "+1 909-555-0100",
"roles": ["deliver_to"]
}
],
"ready_date": "2026-04-10",
"notes": "Fragile cargo, handle with care.",
"pieces": [
{
"pieces": 48,
"packaging_type": "boxes",
"pallets": 1,
"description": "widgets",
"weight": { "value": 18000, "unit": "kg" },
"dimensions": { "length": 120, "width": 125, "height": 100, "unit": "cm" },
"sku": "SKU-123",
"serial_number": "SN_123456",
"po_number": "PO-100234"
}
],
"containers": [
{ "container_type": "40HC", "count": 2 }
],
"references": [
{ "reference_type": "Booking Number", "reference_number": "BKG-1001" },
{ "reference_type": "PO Number", "reference_number": "PO-100234" }
],
"documents": [
{
"document_type": "commercial_invoice",
"file_name": "invoice-100234.pdf",
"content_base64": "JVBERi0xLjQKJ..."
}
],
"metadata": {
"source_system": "partner_tms"
}
}
Required fields: references (at least one), mode, origin, destination
Optional fields: trade, load, incoterm, parties, ready_date, notes, pieces,
containers, documents, metadata
Behavior:
partiescarries the shipper, consignee, and pickup/delivery contacts. Add a party with thepickup_fromrole and one with thedeliver_torole for door-to-door legs; omit them for a port/airport-to-port/airport move. One party may hold several roles. Party fields and accepted roles are listed under Field valuesmode,trade, andloadmust be a valid combination —loadis restricted bymode(see Field values); an invalid combination is rejected with400- purchase order numbers are entered per line as
pieces[].po_numberand/or as aPO Numberentry inreferences; there is no separate purchase-order object pieces[].sku,pieces[].serial_number, andpieces[].po_numberare each up to 100 characters; longer values are rejected with400pieces[].skuassigns the line to a SKU in the shipment company's SKU catalog: see Goods lines by SKU codeready_dateadds a pending "Cargo Ready" event, due that day, to the shipment timeline (and is also used as the first leg's scheduled departure)notesis added to the shipment as an internal note for the operations teamcontainersonly needscontainer_typeandcountat booking time; the carrier-assignedcontainer_numberis almost never known yet. Responses list each container individually (count: 2becomes two entries, each with its owncontainer_id), and the number is populated once assigned — it appears inGET /shipments/{pod_id}/and theshipment.container_assignedwebhookpieces[].weightandpieces[].dimensionsfollow the pallet rule: whenpalletsis1(the default),weightis the total for the whole line anddimensionsare for one piece; whenpalletsis greater than1, both describe a single pallet and are multiplied bypallets. Weight units arekgorlbs; dimension units arecm,in, orftdocuments[]takes the same fields and limits as Upload Document (10MB per file,document_typefrom Document types); documents that arrive after booking (e.g. abolissued later) should be sent with Upload Document instead- whether this shipment is auto-sent to the External TMS on creation is controlled by an
account-level setting on our side, not by this request. An auto-send picks prealert or
shipping order automatically based on the shipment's own details (trade direction, routing,
whether the prealert channel is configured). If your account has this enabled, the outcome
shows up in this response's
tms_pushblock and in theshipment.tms_push.succeeded/.failedwebhook - if your account doesn't auto-send, or you want to fix the shipment first or choose the document type yourself, leave it unsent here, correct it with Update Shipment, and send it with Send Shipment to External TMS. There is only one send per shipment, and once it has been sent the shipment can no longer be updated through the API
Success response (201) — the full Shipment object, exactly as
GET /shipments/{pod_id}/ will return it:
{
"pod_id": "POD-01JQXYZABC1",
"status": "new",
"mode": "ocean",
"trade": "import",
"load": "fcl",
"incoterm": "FOB",
"origin": { "unlocode": "CNSHA", "name": "Shanghai" },
"destination": { "unlocode": "USLAX", "name": "Los Angeles" },
"parties": [
{
"name": "Blue Ocean Supply Co.",
"address_line1": "123 Factory Rd",
"city": "Shenzhen",
"state": "",
"postal_code": "518000",
"country": "CN",
"contact_name": "Li Wei",
"contact_phone": "+86 138 0000 0000",
"roles": ["pickup_from", "shipper"]
},
{
"name": "Acme Imports DC",
"address_line1": "500 Warehouse Way",
"city": "Ontario",
"state": "CA",
"postal_code": "91761",
"country": "US",
"contact_name": "Jane Doe",
"contact_phone": "+1 909-555-0100",
"roles": ["deliver_to"]
}
],
"ready_date": "2026-04-10",
"eta_destination": null,
"notes": "Fragile cargo, handle with care.",
"containers": [
{ "container_id": "CNT-8F31", "container_type": "40HC", "container_number": null },
{ "container_id": "CNT-8F32", "container_type": "40HC", "container_number": null }
],
"pieces": [
{
"label_code": "PC-8F2A1B3C9D0E",
"pieces": 48,
"packaging_type": "boxes",
"pallets": 1,
"description": "widgets",
"weight": { "value": 18000, "unit": "kg" },
"dimensions": { "length": 120, "width": 125, "height": 100, "unit": "cm" },
"sku": "SKU-123",
"serial_number": "SN_123456",
"po_number": "PO-100234",
"container_number": null,
"catalog_sku": { "id": "SKU-41", "sku_code": "SKU-123", "name": "Widget, blue" }
}
],
"references": [
{ "reference_type": "Booking Number", "reference_number": "BKG-1001" },
{ "reference_type": "PO Number", "reference_number": "PO-100234" }
],
"current_event": null,
"tms_push": {
"status": "not_requested",
"document_type": null,
"tms_order_id": null,
"detail": ""
},
"created_at": "2026-04-10T09:15:00+00:00",
"updated_at": "2026-04-10T09:15:00+00:00"
}
tms_push reflects your account's configured send-to-TMS setting, not anything supplied in
this request — there is one send per shipment, not a per-type choice. Because the send happens
synchronously as part of creating the shipment, this response already carries the real outcome:
status: "not_requested"— your account isn't configured to auto-send to the External TMSstatus: "succeeded"— sent;document_type(prealertorshippingorder, chosen automatically) andtms_order_idare populatedstatus: "failed"— your account is configured to send, but it couldn't (e.g. required data was missing);detailexplains why
There is no "queued" state and no separate webhook for this specific outcome — see
shipment.tms_push.succeeded / .failed below, which exist for the case where a send is
triggered later (by Send Shipment to External TMS or by our operations
team), not for one already reported here.
11. Upload Document
POST /api/partner/v1/shipments/{pod_id}/documents/
Adds a document to an existing shipment. For documents you already have in hand at booking
time, use the documents field on Create Shipment instead — this
endpoint is for anything that arrives afterward (for example a bol, packing_list, or
proof_of_delivery; see Document types).
Request body:
{
"document_type": "bol",
"file_name": "BOL-BKG-1001.pdf",
"content_base64": "JVBERi0xLjQKJ..."
}
The URL must end in /. A POST to .../documents (no trailing slash) is redirected, and
most HTTP clients (Python requests included) follow that redirect as a GET, so you get
back an empty documents list and nothing is uploaded. Set allow_redirects=False (or your
client's equivalent) to make that mistake fail loudly.
content_base64 is the file's bytes base64-encoded into a string (in Python,
base64.b64encode(f.read()).decode("ascii")), not a file object or multipart upload.
Required fields: file_name, content_base64
document_type is optional and must be one of the values in
Document types. Any other value (or none) is stored as other, with your
value kept as the document's label.
Limits: 10MB per file (decoded size). Invalid base64 returns 400. Supports the
Idempotency-Key header like the other create endpoints: a retry with the same key and
body returns the original response without adding a second copy.
Success response (201), the same shape as an item in
List Shipment Documents:
{
"document_id": "DOC-250",
"document_type": "bol",
"file_name": "BOL-BKG-1001.pdf",
"uploaded_at": "2026-04-11T09:00:00+00:00",
"download_url": "https://example.com/api/partner/v1/documents/250/download/"
}
Uploaded documents are visible to the customer in the portal and in the Docs tab of the shipment's file for operations.
A shipment.document_available webhook fires for every new portal-visible document, whether it
was added here, at creation, or by operations staff.
12. Get Shipment Status
GET /api/partner/v1/shipments/{pod_id}/ (see Get Shipment)
Same endpoint used for full detail also reflects current status; there is no separate status-only endpoint.
13. Notify Warehouse of an Inbound Shipment
POST /api/partner/v1/shipments/{pod_id}/warehouse-stay/
Tells us to expect a shipment at one of our warehouses — the same action as an inbound notification through our own operations system. This is a separate step from Create Shipment: creating a shipment declares the booking, this declares that (some or all of) it is physically inbound to a warehouse.
Request body:
{
"facility_code": "SEA01",
"estimated_arrival_date": "2026-05-01",
"pickup_trucker_name": "Harbor Drayage",
"dropoff_trucker_name": "Local Cartage Co",
"notes": "Fragile cargo, handle with care.",
"pieces": [
{
"pieces": 4,
"packaging_type": "pallet",
"description": "widgets",
"weight": { "value": 900, "unit": "kg" }
}
]
}
Required fields: facility_code
Optional fields: estimated_arrival_date, pickup_trucker_name, dropoff_trucker_name,
notes, pieces (same shape as Create Shipment's pieces)
Behavior:
pickup_trucker_name/dropoff_trucker_nameare matched case-insensitively to an existing company, or created if none exists — same behavior as Create Shipment'sparties- the resulting status is always
in_bound— you can tell us freight is coming, but only we can assert it's been physically received or made available; there's no field to set this yourself piecesare reconciled against the pieces declared on Create Shipment that aren't on a warehouse stay yet, so a shipment never lists the same goods twice:- omit
pieces(or send[]) and the shipment's existing pieces move onto this warehouse stay unchanged, keeping theirlabel_codes - send
piecesand your list replaces them: each line you send takes over an existing piece (an identical line, matched onsku,serial_number,po_number,descriptionandpackaging_type, first; otherwise the next one in order), keeping itslabel_codebut taking your counts, weight and dimensions. Extra lines are added as new pieces. Existing pieces you didn't send are removed, unless we have already invoiced or dispatched them. - pieces already on an earlier warehouse stay are left alone, so calling this again adds another stay with only the new lines you send
- there is no facility-level access restriction on this endpoint the way our own internal integrations are restricted to specific warehouses — your account boundary is your own company's data, not a facility list
Success response (201) — the Warehouse Stay object:
{
"pod_id": "POD-01JQXYZABC1",
"shipment_number": "ACMEIM-260501-001",
"status": "in_bound",
"facility_code": "SEA01",
"estimated_arrival_date": "2026-05-01",
"pickup_trucker_name": "Harbor Drayage",
"dropoff_trucker_name": "Local Cartage Co",
"notes": "Fragile cargo, handle with care.",
"pieces": [
{
"label_code": "PC-8F2A1B3C9D0E",
"pieces": 4,
"packaging_type": "pallet",
"pallets": 1,
"description": "widgets",
"weight": { "value": 900, "unit": "kg" },
"dimensions": null,
"sku": "",
"serial_number": "",
"po_number": "",
"container_number": null,
"catalog_sku": null
}
],
"created_at": "2026-04-10T09:15:00+00:00",
"updated_at": "2026-04-10T09:15:00+00:00"
}
label_code is a stable per-piece identifier — hang on to it if you'll want to reference this
specific piece later, e.g. for Initiate a Consolidation.
14. Get Warehouse Stay
GET /api/partner/v1/shipments/{pod_id}/warehouse-stay/
Returns the same Warehouse Stay object as the notify response.
404 if no warehouse stay has been notified for this shipment yet. If more than one warehouse
stay has ever been attached to the same shipment, this returns only the most recently created
one.
15. Create Warehouse Stay (Standalone)
POST /api/partner/v1/warehouse-stays/
Same as Notify Warehouse of an Inbound Shipment, but for freight that has no shipment yet — creates a new shipment and its warehouse stay together in one call, so you don't need to call Create Shipment first. Use this when you have nothing to report except that freight is inbound to a warehouse (e.g. a domestic drop-off with no international routing worth declaring).
Request body: everything from Notify Warehouse, plus:
{
"reference": "PO-100234",
"mode": "road",
"trade": "domestic",
"facility_code": "SEA01"
}
Additional optional fields: reference, mode, load, trade — see
Field values. None of these are required; omit them entirely for a
warehouse-only notification with no routing leg at all.
Success response (201): the same Warehouse Stay object, now with a
real pod_id usable with every other endpoint in this API (GET /shipments/{pod_id}/, events,
documents, and so on).
16. Initiate a Consolidation
POST /api/partner/v1/consolidations/
Combines existing pieces — identified by the label_code returned on any piece you've already
received back from this API — into a new warehouse stay. This is the same action as the
"Consolidate" function in our operations system. Every referenced piece must already belong to
one of your warehouse stays for the company the consolidation is for (company_id, see
Companies above), in received or available status, with no active
holds, and all in the same facility.
Request body:
{
"pieces": [
{"label_code": "PC-8F2A1B3C9D0E", "quantity": 4},
{"label_code": "PC-1A2B3C4D5E6F"}
],
"facility_code": "SEA01",
"po_number": "PO-100234",
"expected_pickup_date": "2026-05-05",
"pickup_trucker_name": "Fast Freight LLC",
"make_available": false
}
Required fields: at least one piece (via pieces or piece_label_codes), facility_code
Optional fields: po_number, expected_pickup_date, pickup_trucker_name, make_available
Choosing pieces:
pieces— a list of{"label_code", "quantity"}.quantityis how many of that line'spiecesto take; leave it out to take the whole line. It must be at least 1 and no more than the line currently holds, or the request is rejected with a400. Eachlabel_codemay appear only oncepiece_label_codes— a plain list of label codes, each taken whole. Still accepted; if a label code is in both lists, the quantity frompiecesis used- taking part of a line splits it: the quantity you take moves onto the new warehouse stay and
keeps the original
label_code; what's left stays on the source warehouse stay under a newlabel_code(read it back from that stay if you need it later)
pickup_trucker_name is matched to an existing trucking company by name (case-insensitive), or
created if none matches — the same as pickup_trucker_name on the other warehouse stay
endpoints — and comes back as pickup_trucker_name on the response.
Behavior:
- a piece belonging to another account never resolves — you'll get a
400listing it as unknown, not a403, so this can't be used to probe whether a label_code exists - by default, the new warehouse stay is created with two tasks already on it — "Pick Freight" and "Pack Freight" — mirroring what happens when this is done internally. You don't choose or configure these
- set
make_available: trueto skip the pick/pack tasks entirely and mark the new warehouse stay ready for pickup immediately instead
Success response (201): the same Warehouse Stay object — its
pod_id is new (a consolidation always gets its own shipment identity, separate from wherever
the source pieces came from), and pieces lists everything just consolidated onto it.
17. Update Shipment
PATCH /api/partner/v1/shipments/{pod_id}/
Changes a shipment on your account. Send only the fields you want to change; anything you leave out stays as it is.
A shipment that has already been sent to a third-party system can't be updated. Once it has been sent to the External TMS — by your account's auto-send, by Send Shipment to External TMS, or by our operations team — or is linked to an order in the External TMS, or has an ICS2 customs declaration filed for it, this endpoint returns
409 Conflictwith"code": "shipment_locked"and changes nothing: the copy in that system would otherwise silently go out of date. Contact our operations team to change it. Make any corrections before you send the shipment to the External TMS.
Request body — any of the Create Shipment fields except company_id
and documents:
{
"incoterm": "DAP",
"destination": { "unlocode": "USLGB", "name": "Long Beach" },
"ready_date": "2026-04-20",
"references": [
{ "reference_type": "Booking Number", "reference_number": "BKG-1002" }
]
}
How each field is applied:
| Field | Effect |
|---|---|
reference, incoterm, metadata |
replaced |
mode, trade, load, origin, destination |
set on the shipment's route. Only possible while the route is a single leg; once our operations team has split it into several legs these are rejected with 400 |
ready_date |
moves the pending "Cargo Ready" event (and the route's scheduled departure) to the new day |
notes |
added as a new internal note for the operations team (earlier notes are kept) |
parties |
replaces every party in the roles listed under Parties |
pieces |
replaces all pieces (a sku code links each line to your SKU catalog, as on create). Rejected with 400 once the cargo has a warehouse stay |
containers |
replaces all containers (same container_type + count shape as create). Rejected with 400 once any container number has been assigned |
references |
replaces the references you sent through the API (at least one is required); references added by our operations team or carriers are kept |
mode, trade and load must still be a valid combination after the change (see
Field values). Sending company_id or documents, or an empty body, returns
400; add documents with Upload Document.
Success response (200): the full, updated Shipment object.
Errors:
409 Conflict— the shipment was already sent to a third-party system (see above):
{
"detail": "This shipment was already sent to the External TMS as a prealert, so it can't be updated through the API. Contact our operations team to change it.",
"code": "shipment_locked"
}
400 Bad Request— a field failed validation or a change can't be applied (multi-leg route, assigned container numbers, cargo already in a warehouse);detailsays which404 Not Found— the shipment doesn't exist or isn't on your account
18. Send Shipment to External TMS
POST /api/partner/v1/shipments/{pod_id}/send-to-tms/
Sends the shipment to the External TMS. Use this when your account doesn't auto-send on create, or when you want to choose the document type yourself. A shipment is sent once; after that it can't be sent again or changed through Update Shipment.
Choosing the document type:
document_type |
What it is | When to use it |
|---|---|---|
"prealert" |
An inbound notice to the destination office | Import shipments moving by air or ocean whose origin and destination have codes |
"shippingorder" |
A booking / shipping instruction | Anything else: exports, domestic moves, rail, or when you don't have port/airport codes |
omitted or null |
We choose | prealert when the shipment qualifies for one, otherwise shippingorder |
shipping_order is accepted as a spelling of shippingorder. Any other value returns 400.
Request body:
{ "document_type": "prealert" }
An empty body ({}) lets us choose.
Minimum required information:
| Required | shippingorder |
prealert |
|---|---|---|
| Shipment belongs to your company (always true for shipments you created) | ✓ | ✓ |
mode |
✓ (any) | ✓ air or ocean |
trade |
✓ (any) | ✓ must be import |
origin and destination with a name |
✓ | ✓ |
origin.unlocode and destination.unlocode |
— | ✓ 3-letter IATA airport codes for air, 5-character UN/LOCODEs for ocean (we try to look the code up from name if you leave it out, but sending it is safer) |
| The prealert channel to the External TMS is configured for your deployment (on our side) | — | ✓ |
Everything else on the shipment (parties, pieces, containers, references, documents, incoterm,
ready date) is optional and goes into the send when present. A forced prealert that the
shipment doesn't qualify for is refused; it is not quietly sent as a shipping order.
Check before you send: GET /api/partner/v1/shipments/{pod_id}/send-to-tms/ tells you, without sending anything,
which type we would choose and what each type still needs:
{
"pod_id": "POD-01JQXYZABC1",
"already_sent": false,
"linked_to_tms_order": false,
"automatic_document_type": "shippingorder",
"document_types": {
"prealert": {
"ready": false,
"missing": ["Trade must be import (a prealert is an inbound notification)"]
},
"shippingorder": { "ready": true, "missing": [] }
},
"tms_push": { "status": "not_requested", "document_type": null, "tms_order_id": null, "detail": "" }
}
Success response (200) — the shipment's tms_push block:
{
"status": "succeeded",
"document_type": "prealert",
"tms_order_id": "FILE-000123",
"detail": ""
}
The shipment.tms_push.succeeded webhook fires as well; the shipment's tms_push in
Get Shipment shows the same result from then on.
Errors:
400 Bad Request— the shipment is missing information for the requested (or chosen) type. Nothing is sent;missinglists what to add (fix it with Update Shipment and try again). Theshipment.tms_push.failedwebhook fires:
{
"status": "failed",
"document_type": null,
"tms_order_id": null,
"detail": "Add the following before sending to the External TMS: Trade must be import (a prealert is an inbound notification).",
"missing": ["Trade must be import (a prealert is an inbound notification)"]
}
409 Conflict— already sent, or the shipment is linked to an existing External TMS order ("code": "already_sent", with the currenttms_push)502 Bad Gateway— the shipment was complete but the delivery to the External TMS failed on our side;missingis empty. Safe to retry later404 Not Found— the shipment doesn't exist or isn't on your account
In sandbox mode the request is checked exactly as in live mode (same 400 / 409), but nothing
is sent: a request that would have been sent returns 200 with status: "not_requested", the
document_type that would have been used, and detail: "Sandbox mode: not sent to the External TMS.".
19. SKU Catalog
Your SKU catalog is the list of products you ship and store with us — the same catalog you see under SKU Catalog in the customer portal. Each company on your account has its own catalog; a SKU code is unique within a company (ignoring case), and two of your companies may each have a SKU with the same code. Every SKU is returned as a SKU object.
quantity_on_hand is never set directly: it is the number of pieces linked to the SKU that are
in one of our warehouses right now (received and not yet departed). Link goods lines to a SKU
by sending its code as pieces[].sku (see Goods lines by SKU code).
SKUs are never deleted through the API; set is_active to false to retire one. A retired SKU
is no longer linked to new goods lines, but it keeps its code.
List SKUs
GET /api/partner/v1/skus/
Query parameters (all optional):
| Parameter | Effect |
|---|---|
sku_code |
exact code, ignoring case |
search |
part of the code, name, or manufacturer part number, or an exact UPC/EAN/ISBN |
is_active |
true or false; both are returned when omitted |
updated_since |
ISO 8601 timestamp; SKUs changed at or after it |
company_id |
one of your companies |
Returns a paginated list of SKU objects, ordered by sku_code.
Get SKU
GET /api/partner/v1/skus/{sku_id}/
sku_id is the SKU's id (SKU-41; the bare number 41 works too). To look a SKU up by its
code, use GET /skus/?sku_code=WID-BLUE-01. Returns 404 for a SKU that isn't on your account.
Add SKU(s)
POST /api/partner/v1/skus/
Send one SKU:
{
"sku_code": "WID-BLUE-01",
"name": "Widget, blue",
"upc": "012345678905",
"unit_of_measure": "case",
"units_per_package": 12,
"weight": { "value": 1.2, "unit": "kg" },
"dimensions": { "length": 30, "width": 20, "height": 10, "unit": "cm" },
"hs_code": "8479.89",
"country_of_origin": "CN"
}
or several at once (up to 500) as {"skus": [ ... ]}, each item shaped like the single SKU.
Required on each SKU: sku_code, name, and company_id when your account has more than one
company. Every other field from the SKU object is optional, except id,
company, supplier, quantity_on_hand, created_at and updated_at, which we set. The
supplier is named with supplier_id or supplier_name (case-insensitive) and must be a company
already on record as one of your suppliers; contact our operations team to add a new supplier.
Success response (201): the SKU object for a single SKU, or
{"results": [ ... ]} in request order for several.
A request with several SKUs is all-or-nothing: if any SKU fails, none is added, and the 400
lists the errors per SKU in request order ({} for a SKU that was fine):
{
"skus": [
{},
{ "sku_code": ["This company already has a SKU with code WID-BLUE-01."] }
]
}
Edit SKU
PATCH /api/partner/v1/skus/{sku_id}/
Send only the fields to change; anything left out stays as it is. Fields that can be empty
(reorder_point, unit_cost, sales_price, lead_time_days, supplier_id, weight,
dimensions) take null to clear them. weight and dimensions are replaced as a whole. A
SKU's company can't be changed (company_id returns 400), and a new sku_code must not
already be used by another SKU of the same company.
{ "name": "Widget, navy blue", "reorder_point": 50, "weight": null }
Success response (200): the updated SKU object.
Edit SKUs (several at once)
PATCH /api/partner/v1/skus/
{
"skus": [
{ "id": "SKU-41", "sku_code": "WID-NAVY-01" },
{ "sku_code": "GAD-02", "reorder_point": 10, "is_active": false }
]
}
Each item (up to 500) picks one SKU, then carries the fields to change, as in Edit SKU:
- by
id: any field may change, includingsku_code - or by
sku_code: the code picks the SKU and is not changed. Addcompany_idwhen more than one of your companies has that code
All-or-nothing, like adding several: an unknown SKU or a failing field anywhere returns 400
with per-item errors and changes nothing. A SKU may appear only once per request.
Success response (200): {"results": [ ... ]}, the updated SKU objects in
request order.
20. Send ISF to Brokerage System
POST /api/partner/v1/isf/
Files the shipment's US ISF-10 (Importer Security Filing, "10+2") with the customs
Brokerage System. Name the shipment with file_number or reference_number; every ISF field is
optional. We start from what the shipment already has (consignee tax ID, master bill, parties,
routing, goods lines from your SKU catalog) and lay the values you send on
top: a field you send wins, and a field you leave out (or send blank) keeps the shipment's
value. If a required field is missing from both the shipment and your request, nothing is
sent and the response lists exactly which fields to add.
Unless your deployment transmits straight to CBP (see below), the ISF lands in the Brokerage System
for the broker, who completes anything still open and transmits it to CBP. The response's incomplete
list shows what the broker will still need.
Minimal request (everything else from the shipment):
{ "file_number": "SI-000123" }
Full request:
{
"reference_number": "MAEU987654321",
"importer_tax_id": "12-3456789",
"shipment_type": "01",
"transaction_type": "CT",
"bond_holder": "importer",
"bond_holder_id": "12-3456789",
"bond_type": "continuous",
"surety_code": "457",
"carrier_scac": "MAEU",
"port_of_unlading": "USLAX",
"place_of_delivery": "USDAL",
"etd": "2026-11-20",
"eta": "2026-12-08",
"assigned_to": "jdoe",
"bills": [
{ "type": "OB", "number": "MAEU987654321" },
{ "type": "BM", "number": "SCLX00012345" }
],
"parties": {
"SE": { "name": "Blue Ocean Supply Co.", "street": "88 Harbour Rd", "city": "Shenzhen", "country": "CN" },
"BY": { "name": "Acme Imports", "tax_id": "12-3456789" },
"ST": { "name": "Acme Dallas DC", "street": "100 Logistics Way", "city": "Dallas", "state": "TX", "postal_code": "75201", "country": "US" },
"LG": { "name": "Shenzhen CFS", "street": "5 Port Ave", "city": "Shenzhen", "country": "CN" },
"CS": { "name": "Shenzhen CFS", "street": "5 Port Ave", "city": "Shenzhen", "country": "CN" },
"CN": { "name": "Acme Imports", "tax_id": "12-3456789" }
},
"lines": [
{
"manufacturer": { "name": "Widget Works Ltd", "mid": "CNWIDWOR2NIN", "street": "2 Factory Rd", "city": "Ningbo", "country": "CN" },
"country_of_origin": "CN",
"hts": "8471.30.0100",
"description": "Laptop computers"
}
]
}
Identifying the shipment (at least one is required):
| Field | Required | Matches |
|---|---|---|
file_number |
one of the two | the shipment's file number (exact, any case) |
reference_number |
one of the two | the shipment's file number, any reference on the shipment (booking, PO, bill of lading, ...), its pod_id, tracking number or a container number (exact, any case) |
Send both to narrow a reference that more than one of your shipments carries. Only shipments on your account are found.
ISF fields:
| Field | Required | Format / values | Taken from the shipment when left out |
|---|---|---|---|
importer_tax_id |
Required (request or shipment) | IRS/EIN NN-NNNNNNN (9 digits without the dash are accepted), CBP-assigned NNNNNN-NNNNN, or SSN NNN-NN-NNNN. Also used as the bond holder ID |
the first tax ID found on the shipment's consignee, deliver-to or customer company; on a shipment linked to an External TMS order, a party company with no tax ID first takes the one the External TMS holds for it |
bills |
Required (request or shipment): at least one | list (up to 10) of { "type": "OB" \| "BM", "number": "..." }. OB = master / ocean bill (default), BM = AMS house bill. A leading 4-letter SCAC is sent as the issuer SCAC. Replaces the shipment's bills when sent |
the shipment's master bill (transport document) reference |
shipment_type |
Optional | 01 standard (default) … 11 (CBP ISF shipment type codes) |
01 |
transaction_type |
Optional | CT compliant (default), FR, FT, FX |
CT |
bond_holder |
Optional | importer (default), broker, custodian-of-merchandise, carrier, ftz-operator, isf-bond |
importer |
bond_holder_id |
Optional | tax ID, same formats as importer_tax_id |
importer_tax_id |
bond_type |
Optional | continuous or single-transaction |
continuous |
surety_code |
Optional | up to 3 characters | — |
carrier_scac |
Optional | 2–4 letter SCAC of the ocean carrier | — |
port_of_unlading |
Optional | 5-character UN/LOCODE or 5-digit Schedule K code | the last ocean leg's destination |
place_of_delivery |
Optional | 5-character UN/LOCODE or 5-digit Schedule K code | the last routing leg's destination |
etd |
Optional | YYYY-MM-DD |
the first leg's scheduled departure |
eta |
Optional | YYYY-MM-DD |
the last ocean leg's scheduled arrival |
assigned_to |
Optional | the Brokerage System username of the broker's user the ISF is assigned to, up to 20 characters, no spaces (ask our operations team for it) | — (assigned to our integration user) |
parties |
Optional* | object keyed by ISF party code (below). Only the fields you send change; the rest keep the shipment's values | the shipment's parties (see below) |
lines |
Optional* | list (up to 500) of product lines (below). Replaces the shipment's lines when sent | one line per distinct product on the shipment's goods lines (HTS, origin and supplier from the SKU catalog) |
* Required when your deployment transmits ISFs straight to CBP; see Transmitted ISFs.
Party codes (parties):
| Code | ISF element | Prefilled from the shipment's |
|---|---|---|
SE |
Seller | seller, else shipper, else pickup-from party |
BY |
Buyer | buyer, else consignee, else deliver-to party |
ST |
Ship-to party | ship-to, else deliver-to, else consignee party |
LG |
Container stuffing location | stuffing location, else CFS, else shipper party |
CS |
Consolidator (stuffer) | consolidator, else CFS party |
CN |
Consignee number | consignee, else deliver-to party |
Party object (also the manufacturer of a line) — every field optional:
| Field | Format |
|---|---|
name |
up to 35 characters |
tax_id |
same formats as importer_tax_id |
mid |
manufacturer ID, up to 15 characters (sent for manufacturers and sellers) |
street |
up to 210 characters |
city |
up to 35 characters |
state |
state / province code, up to 3 characters |
postal_code |
up to 15 characters |
country |
2-letter ISO country code |
A complete party has a name (or mid) plus a tax_id, an mid, or street + city +
country; the consignee (CN) needs a tax_id.
Product line (lines[]) — every field optional:
| Field | Format |
|---|---|
manufacturer |
party object (above); lines with the same manufacturer are sent as one manufacturer with several products |
country_of_origin |
2-letter ISO country code |
hts |
6 to 10 digits; dots and spaces are dropped (8471.30.0100) |
description |
up to 200 characters |
Unknown fields (for example a misspelled importer_taxid) are rejected with 400 rather than
ignored, so nothing you meant to file is silently dropped.
Transmitted ISFs
By default an ISF goes to the brokerage system and the broker transmits it, so only importer_tax_id and a
bill of lading are required, and the other ISF-10 elements come back in incomplete. If your
deployment is set up to transmit ISFs straight to CBP (transmitted: true in the response;
ask our operations team), every ISF-10 element is required as well: all six parties above
(each complete as described), and at least one line with a complete manufacturer,
country_of_origin and hts.
Responses
Success (200):
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"status": "uploaded",
"detail": "ISF uploaded to brokerage system (reference 98765).",
"brokerage_reference": "98765",
"transmitted": false,
"filing_status": "in_brokerage",
"warnings": [],
"can_resend": false,
"incomplete": [
{ "field": "parties.LG.name", "message": "Container stuffing location: name" },
{ "field": "lines", "message": "At least one product line (manufacturer, country of origin, HTS)" }
],
"isf": {
"importer_tax_id": "12-3456789",
"shipment_type": "01",
"transaction_type": "CT",
"bond_holder": "importer",
"bond_holder_id": "12-3456789",
"bond_type": "continuous",
"surety_code": "",
"carrier_scac": "",
"port_of_unlading": "USLAX",
"place_of_delivery": "USDAL",
"etd": "2026-11-20",
"eta": "2026-12-08",
"assigned_to": "jdoe",
"bills": [ { "type": "OB", "number": "MAEU987654321" } ],
"parties": { "SE": { "name": "Blue Ocean Supply Co.", "tax_id": "", "mid": "", "street": "88 Harbour Rd", "city": "Shenzhen", "state": "", "postal_code": "", "country": "CN" } },
"lines": [ ]
}
}
isf shows every ISF field as it was sent (your values merged with the shipment's).
filing_status is in_brokerage (with the broker) or transmitted (sent on to CBP). CBP's answer
arrives later: subscribe to the ISF webhook events (shipment.isf.accepted,
shipment.isf.rejected, ...) to hear about it.
warnings lists what the Brokerage System noted while taking the ISF, for example
"The ISF could not be reassigned to user jdoe because the User could not be found" when
assigned_to isn't a user there (the ISF then stays with our login's user). The ISF is still
uploaded: don't send it again; correct the assignment with our operations team if needed. The Brokerage System
gives no reference number with such an answer, so brokerage_reference is then empty.
Every response says whether sending the ISF again is right, in can_resend: false once the
ISF is in the Brokerage System (200 uploaded, 409 already_sent), true when nothing
reached it (400, 502 brokerage_rejected, sandbox not_sent).
Errors:
400 Bad Request,"code": "missing_required_fields"— a required field is missing from both the shipment and the request. Nothing is saved or sent;missingnames each field (use the same name in your next request) andincompletelists the optional ISF-10 data still open:
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"detail": "Missing required ISF fields: importer_tax_id, bills.",
"code": "missing_required_fields",
"missing": [
{ "field": "importer_tax_id", "message": "Importer tax ID (IRS/EIN NN-NNNNNNN): send importer_tax_id, or set the tax ID on the shipment's consignee, deliver-to or customer company." },
{ "field": "bills", "message": "At least one bill of lading (master bill OB or AMS house bill BM): send bills, or add the master bill to the shipment." }
],
"incomplete": [ ]
}
Field names are paths into the request: parties.SE.name, lines[0].hts,
lines[0].manufacturer.tax_id (a party's tax_id entry means "a tax ID, an MID, or
street + city + country").
- 400 Bad Request — a field has the wrong format, an unknown field was sent, or neither
file_number nor reference_number was given (field-based errors, as elsewhere in this API)
- 400 Bad Request, "code": "ambiguous_reference" — more than one of your shipments carries
that reference_number; matches lists them (pod_id, file_number). Add file_number
- 404 Not Found, "code": "not_found" — no shipment on your account matches
- 409 Conflict, "code": "already_sent" — the shipment's ISF is already in the Brokerage
System (with its brokerage_reference, filing_status and the upload's warnings). There is one open ISF per shipment; contact our
operations team to cancel it if it has to be filed again
- 502 Bad Gateway, "code": "brokerage_rejected" — the Brokerage System refused the ISF or
couldn't be reached; detail carries its reason (for example an importer it doesn't know
yet). Nothing reached the Brokerage System (can_resend: true).
The attempt is recorded for our operations team; you can correct and retry
- 503 Service Unavailable, "code": "isf_not_configured" — ISF filing isn't set up for your
deployment
POST /isf/ doesn't take an Idempotency-Key: a repeat send of the same shipment returns
409.
In sandbox mode the request is checked exactly as in live mode (same 400 / 404 / 409),
but nothing is saved or sent: a request that would have been sent returns 200 with
status: "not_sent", detail: "Sandbox mode: not sent to the Brokerage System." and the isf that would
have been sent. In sandbox mode the shipment's External TMS order isn't consulted, so
importer_tax_id and a bill must be on the shipment or in the request.
Exception: when your deployment's Brokerage System connection is itself a sandbox (test)
system, a sandbox request is sent to it as in live mode and answered as in live mode
(status: "uploaded", brokerage_reference, ...), but still nothing is saved on our side.
Because nothing is saved, the sandbox doesn't remember an earlier send: the same shipment can be
sent to the test system again without a 409.
21. File ICS2 with EU Customs
POST /api/partner/v1/ics2/
Files the shipment's EU ICS2 Entry Summary Declaration (ENS) with EU customs. Name the shipment with file_number or reference_number (exactly as for
Send ISF); every ICS2 field is optional. We start from what the
shipment already has (routing, ports and dates, master and house bill, parties, containers,
goods lines) and lay the values you send on top: a field you send wins, and a field you
leave out (or send blank) keeps the shipment's value. If a field the declaration requires is
missing from both the shipment and your request, nothing is saved or sent and the response
lists exactly which fields to add, by their path in the request.
Minimal request (everything else from the shipment):
{ "file_number": "SI-000123" }
The following fields can be sent:
| Field | Required | Contents |
|---|---|---|
file_number |
one of the two | the shipment's file number (exact, any case) |
reference_number |
one of the two | the shipment's file number, any reference on the shipment, its pod_id, tracking number or a container number (exact, any case) |
filing_type |
Optional | F11 sea, complete (master + house); F15 sea, house filing; F26 air, pre-loading + house; F34 express road; F50 road. Default: by the shipment's main transport mode, normally F15 ocean, F26 air, F50 road / rail (set per deployment). Can't change once the declaration has been filed |
general |
Optional | the declaration level (activeBorderTransportMeans, consignmentMasterLevel, customsOfficeOfFirstEntry, addressedMemberState, ...) |
houses |
Optional | list of house consignments, each with its house-level fields and its goodsItem list |
Full F15 example:
{
"reference_number": "MAEU123456789",
"filing_type": "F15",
"general": {
"addressedMemberState": { "country": "NL" },
"activeBorderTransportMeans": { "modeOfTransport": "1" },
"customsOfficeOfFirstEntry": { "referenceNumber": "NL000396" }
},
"houses": [
{
"containerIndicator": "1",
"placeOfAcceptance": { "UNLOCODE": "CNSHA" },
"placeOfDelivery": { "UNLOCODE": "NLRTM" },
"transportDocumentMasterLevel": { "documentNumber": "MAEU123456789", "type": "N704" },
"transportDocumentHouseLevel": { "documentNumber": "HBL0001", "type": "N714" },
"carrier": { "contactId": "300001" },
"consignor": {
"contact": {
"contact_name": "Shenzhen Parts Co", "type_of_person": "2", "street": "Nanshan Rd", "street_number": "8",
"city": "Shenzhen", "postcode": "518000", "country_id": "CN"
}
},
"consignee": { "contactId": "300003" },
"goodsShipment": { "buyer": { "contactId": "300003" }, "seller": { "contactId": "300002" } },
"transportCharges": { "methodOfPayment": "Y" },
"countriesOfRoutingOfConsignment": [
{ "sequenceNumber": "1", "country": "CN" },
{ "sequenceNumber": "2", "country": "NL" }
],
"transportEquipment": [
{ "containerIdentificationNumber": "MSCU1234567", "containerSizeAndType": "20",
"containerPackedStatus": "B", "containerSupplierType": "2" }
],
"goodsItem": [
{
"commodity": { "descriptionOfGoods": "Bicycle parts", "commodityCode": { "harmonizedSystemSubHeadingCode": "871499" } },
"weight": { "grossMass": "1200.50" },
"packaging": [ { "typeOfPackages": "PX", "numberOfPackages": "4", "shippingMarks": "NO MARKS" } ]
}
]
}
]
}
How your values are combined with the shipment's:
- objects are merged field by field; a value you send replaces the shipment's, a field you
leave out or send as
""/nullkeeps it housesand each house'sgoodsItemare matched by position:houses[0]is the declaration's first house,houses[0].goodsItem[1]its second goods item. Send{}for a house or item you don't want to change; extra entries are added, and houses or items you don't send are kept (they are never removed through the API)- any other list (
countriesOfRoutingOfConsignment,packaging,transportEquipment,seal,supportingDocuments, ...) ends up as long as the list you send, each entry merged with the shipment's entry at the same position. A single object sent where a list belongs (for example"transportEquipment": {"containerSizeAndType": "45"}, as amissingpath without an index suggests) updates the first entry and keeps the others - shipping marks (
packaging[].shippingMarks) are filed with letters, digits and spaces only, as customs requires: any other character is filed as a space (SKU-45632is filed asSKU 45632,N/MasN M), and marks left empty are filed asNO MARKS - numbers may be sent as JSON numbers or strings (
1200.5or"1200.5"); dates and times asYYYY-MM-DDThh:mm:ssZ(UTC) - a party (
carrier,consignor,consignee,notifyParty,goodsShipment.buyer,goodsShipment.seller) is either{"contactId": "..."}, a contact already registered in the system, or{"contact": { ... }}with the party's name, address and EORI (will be registered for you when the declaration is sent; see the contact fields); see Parties for who each one is LRN,specificCircumstancesIndicatorand thedeclarant/representativeparties are set by us for every declaration and are rejected if sent- unknown fields (for example a misspelled
descriptionOfGood) are rejected with400rather than ignored. Fields yourfiling_typedoesn't use are kept and not sent; the response lists them underignored
ICS2 parties
The parties follow the EU's definitions, which differ from how a bill of lading names them:
| Party | Who it is | Taken from the shipment |
|---|---|---|
carrier |
The ocean carrier (shipping line) or airline that brings the goods into the EU, i.e. the operator of the vessel or aircraft — not the NVOCC or forwarder that issued the house bill. EU customs requires its EORI (contact.eori_number), even on a house-level (F15) filing. When the carrier's EORI isn't known, the declarant's EORI and details are filed as the carrier and the response lists it under warnings |
the carrier party, else the main routing leg's carrier (a carrier typed by name uses the details of the carrier company with that name or SCAC) |
consignor |
The shipper of the house consignment (the seller/exporter as it appears on the house bill) | shipper party |
consignee |
The party the goods are consigned to in the EU | consignee party |
notifyParty |
The notify party on the bill | notify party |
goodsShipment.seller / goodsShipment.buyer |
The parties to the sale (often the consignor and consignee) | shipper / consignee parties |
| declarant (set by us) | The filer: you, through us. It isn't sent in the request | — |
A shipping line's or airline's EORI is the same on every declaration, so it is recorded once on
the carrier in our directory, and every declaration for that carrier picks it up, whether the
shipment's routing leg picks the carrier or just names it ("APL"), as long as only one active
carrier has that name, legal name or SCAC. Until a carrier's EORI is recorded, its declarations
name the declarant as carrier (warnings: "Carrier has no EORI: the declarant's EORI and details
are filed as the carrier"); ask our operations team to add the carrier's EORI so later
declarations, and amendments of earlier ones, name the actual carrier.
Which fields are required
Every field is optional in the request. Whether the declaration needs a field depends on the filing type, following the EU's ICS2 ENS completion rules. The complete list, with Required / Conditional / Optional / not used for each filing type, is in the ICS2 field reference, and
GET /api/partner/v1/ics2/fields/?filing_type=F11
returns the same list for one filing type as JSON (always current; the rules POST /ics2/
checks):
{
"filing_type": "F11",
"filing_type_label": "F11 - Sea & inland waterways, complete (master + house)",
"fields": [
{ "field": "general.customsOfficeOfFirstEntry.referenceNumber", "requirement": "required",
"within": "general.customsOfficeOfFirstEntry", "group": false, "occurs": "1..1",
"format": "an8 (Code List Value)", "code_list": "CustomsOfficeOfFirstEntry", "rule": "" },
{ "field": "houses[].notifyParty", "requirement": "conditional", "within": "", "group": true,
"occurs": "0..1", "format": "", "code_list": "", "rule": "C0001" }
],
"party_contact_fields": [
{ "field": "contact_name", "requirement": { "carrier": "required", "consignor": "required", "...": "..." },
"format": "an..70", "code_list": "" }
],
"rules": { "C0001": "IF 'CONSIGNMENT (HOUSE LEVEL)/ADDITIONAL INFORMATION/Code' is '10600' THEN this class is M, ELSE it is O." }
}
requirement is required, conditional (required when its rule applies) or optional.
A field inside a group (within) is only required when that group is on the declaration.
The fields most declarations need, by filing type (R required, C conditional, — not used):
| Field | F11 | F15 | F26 | F34 | F50 | Usually taken from the shipment |
|---|---|---|---|---|---|---|
general.activeBorderTransportMeans.modeOfTransport |
R | R | R | R | R | the main leg's mode |
general.activeBorderTransportMeans.identificationNumber / typeOfIdentification / typeOfMeansOfTransport / nationality |
R | — | — | R | R | flight number (air); otherwise — |
general.activeBorderTransportMeans.estimatedDateAndTimeOfDeparture / ...Arrival |
R | — | — | R | R | the main leg's ETD / ETA |
general.activeBorderTransportMeans.countriesOfRoutingOfMeansOfTransport (2+) |
R | — | — | R | R | loading and unloading countries |
general.customsOfficeOfFirstEntry.referenceNumber |
R | R | — | R | R | the EU customs office of entry at the port of unloading, when exactly one serves it (see Customs offices of first entry) |
general.addressedMemberState.country |
— | R | R | — | — | the unloading country |
general.consignmentMasterLevel.placeOfLoading / placeOfUnloading / placeOfAcceptance / placeOfDelivery |
R | — | — | R | R | the routing legs |
general.consignmentMasterLevel.transportDocumentMasterLevel |
R | — | — | — | R | the master bill |
general.consignmentMasterLevel.carrier / consignor |
R | — | — | R / — | R | the shipment's parties |
general.consignmentMasterLevel.transportCharges.methodOfPayment |
R | — | — | — | R | the shipment's method of payment (set on the shipment by our operations team) |
houses[].containerIndicator, placeOfAcceptance, placeOfDelivery |
R | R | R | R | R | containers, routing legs |
houses[].transportDocumentHouseLevel |
R | R | R | R | R | the house bill |
houses[].transportDocumentMasterLevel, houses[].carrier |
— | R | R | — | — | the master bill; the carrier party, else the main routing leg's carrier (matched to its company by name) |
houses[].consignor |
R | R | R | R | — | shipper party |
houses[].consignee |
C | C | C | R | — | consignee party |
houses[].transportCharges.methodOfPayment |
R | R | R | R | R | the shipment's method of payment (set on the shipment by our operations team); codes A cash, B credit card, C cheque, D ACH / direct debit, H electronic funds transfer, Y account holder with carrier, Z not prepaid |
houses[].countriesOfRoutingOfConsignment (2+) |
R | R | R | R | R | acceptance and delivery countries |
houses[].transportEquipment |
C | C | C | C | C | the shipment's containers: number, seal, size/type from the container type (40ST -> 45), supplier type 2 (carrier supplied) |
houses[].goodsItem[].commodity.descriptionOfGoods, commodityCode.harmonizedSystemSubHeadingCode |
R | R | R | R | R | goods lines: the line's HS code, else its catalog SKU's |
houses[].goodsItem[].weight.grossMass (kg) |
R | R | R | R | R | goods lines |
houses[].goodsItem[].packaging[].typeOfPackages (+ numberOfPackages, shippingMarks unless bulk) |
R | R | R | R | R | goods lines: packaging, piece count; marks from the line's SKU or label, else NO MARKS (filed with letters, digits and spaces only) |
The field reference is authoritative where this summary is short.
Customs offices of first entry
general.customsOfficeOfFirstEntry.referenceNumber is the 8-character code of the EU customs
office where the goods first arrive in the EU (for example FR002730, Marseille port). When
exactly one office of entry serves the shipment's port of unloading for its transport mode, it is
filled in for you. Some ports have several (Le Havre, Frankfurt airport) or none that we can
match by name; for those, look the office up and send its code:
GET /api/partner/v1/ics2/customs-offices/?unlocode=FRLEH&mode=ocean
| Parameter | Matches |
|---|---|
unlocode |
offices serving that port (UN/LOCODE), most specific match first |
country |
2-letter country code |
mode |
ocean, air, road or rail: offices handling that transport |
q |
words in the office's code, name or city (q=roissy) |
All parameters are optional and can be combined; with none, every office is listed.
{
"count": 2,
"results": [
{ "code": "FR002270", "name": "Le Havre Produits Pétroliers", "city": "LE HAVRE", "postal_code": "76083",
"country": "FR", "unlocode": "", "modes": ["ocean"] },
{ "code": "FR002300", "name": "Le Havre Port bureau", "city": "LE HAVRE", "postal_code": "76083",
"country": "FR", "unlocode": "", "modes": ["air", "inland_waterway", "ocean", "rail"] }
]
}
The list is the EU's official list of customs offices that act as offices of entry. A code that
isn't in it is still accepted and comes back as a warnings entry, in case the EU added the
office after our latest update of the list.
Responses
Success (200):
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"lrn": "POD261112AB12CD3",
"mrn": "",
"filing_type": "F15",
"filing_status": "submitted",
"status": "submitted",
"detail": "Submitted to customs.",
"submission_reference": "SUB-1",
"warnings": [],
"ignored": [],
"ics2": {
"filing_type": "F15",
"general": { "LRN": "POD261112AB12CD3", "addressedMemberState": { "country": "NL" }, "...": "..." },
"houses": [ { "containerIndicator": "1", "...": "...", "goodsItem": [ { "...": "..." } ] } ]
}
}
status is submitted (a new declaration) or amendment_submitted (a change to one already
lodged). ics2 shows the declaration as it was sent (your values merged with the shipment's;
fields the filing type doesn't use are left out; shipping marks as filed). A party shows its
contact details and, once registered, its contactId; a carrier filed as the declarant shows
only the declarant's contactId. lrn is our Local Reference Number for the
declaration; mrn, customs' Movement Reference Number, follows once customs accepts it, and
customs' answers (acceptance, referrals, do-not-load) are handled by our operations team and
reported on the shipment's events. warnings lists things worth checking that don't block
sending, each with the field it concerns and a message, for example:
"warnings": [
{ "field": "houses[0].carrier", "message": "House 1: Carrier has no EORI: the declarant's EORI and details are filed as the carrier" },
{ "field": "general.customsOfficeOfFirstEntry.referenceNumber", "message": "Customs office of first entry › Reference number: 'FR009999' is not an EU customs office of entry in our list — double-check it" }
]
Other warnings flag a UN/LOCODE missing from our copy of the code list.
Errors:
400 Bad Request,"code": "missing_required_fields"— a field the declaration requires is missing from both the shipment and the request. Nothing is saved or sent.missingnames each field by its path in the request (send it under that name),invalidlists values with the wrong format or code, if any:
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"lrn": "POD261112AB12CD3",
"mrn": "",
"filing_type": "F15",
"filing_status": "draft",
"detail": "Missing required ICS2 fields: general.customsOfficeOfFirstEntry.referenceNumber, houses[0].goodsItem[0].commodity.descriptionOfGoods.",
"code": "missing_required_fields",
"missing": [
{ "field": "general.customsOfficeOfFirstEntry.referenceNumber", "message": "Customs office of first entry › Reference number is required" },
{ "field": "houses[0].goodsItem[0].commodity.descriptionOfGoods", "message": "House 1 › Item 1: Commodity › Description of goods is required" }
],
"invalid": [],
"warnings": [],
"ignored": []
}
A party's missing contact details are reported on the party (houses[0].consignor) with the
contact field named in message. Repeated entries are counted from 0, like the request
(houses[0].goodsItem[0].packaging[1].typeOfPackages). The lrn shown isn't kept: the
declaration is only created once a request goes through.
- 400 Bad Request, "code": "invalid_fields" — nothing is missing but a value has the wrong
format or isn't in its code list (invalid lists them, same shape as missing)
- 400 Bad Request — an unknown field was sent, a field has the wrong shape (an object where a
single value belongs, ...), filing_type isn't one of the five, or neither file_number nor
reference_number was given (field-based errors keyed by request path, as elsewhere in this API)
- 400 Bad Request, "code": "ambiguous_reference" / 404 Not Found, "code": "not_found" —
as for Send ISF
- 409 Conflict, "code": "already_submitted" — the declaration is already lodged and the
request changes nothing in it
- 409 Conflict, "code": "filing_type_locked" — the declaration was already filed under
another filing type
- 409 Conflict, "code": "submission_in_progress" — the declaration is being submitted right
now; retry shortly
- 502 Bad Gateway, "code": "filing_failed" — the declaration (or one of its parties) was
refused when it was filed, or the customs system couldn't be reached; detail carries the
reason. The declaration is kept with what you sent and our operations team is notified; you
can correct it and send again
- 503 Service Unavailable, "code": "ics2_not_configured" — ICS2 filing isn't set up for your
account yet; contact our operations team
POST /ics2/ doesn't take an Idempotency-Key: repeating a request that changes nothing
returns 409 already_submitted.
In sandbox mode the request is checked exactly as in live mode (same 400 / 404, and 409
while a submission is in progress or the filing type is locked), and is then filed with the
customs sandbox (a test system; nothing reaches EU customs), so you get back a complete
filing: 200 with status: "submitted", "sandbox": true, detail: "Sandbox mode: filed with the
customs sandbox, not with EU customs. Nothing is kept.", the sandbox lrn and the ics2 as it was
filed (or 502 filing_failed with the sandbox's reason). Each sandbox request files the shipment's
declaration afresh under a new LRN -- also when it was already lodged live, which it doesn't
touch -- and nothing is saved, so no shipment.ics2.* webhook follows and the LRN can't be read
back. Where the customs sandbox isn't set up for your deployment, a request that would have
been sent returns 200 with status: "not_sent", detail: "Sandbox mode: not filed with customs."
and the ics2 that would have been filed.
22. Send Entry to Brokerage System
POST /api/partner/v1/entry/
Creates the shipment's US customs entry (CBP Form 7501 / 3461 data) in the customs
Brokerage System. Name the shipment with file_number or reference_number (exactly as for
Send ISF); every entry field is optional. We start from what the
shipment already has (consignee tax ID, destination port, arrival date, vessel and voyage,
weight, goods lines from your SKU catalog) and lay the values you send on
top: a field you send wins, and a field you leave out (or send blank) keeps the shipment's
value. If a required field is missing from both the shipment and your request, nothing is
sent and the response lists exactly which fields to add.
The entry lands in the Brokerage System as a draft for the broker, who completes anything still open and
files it with CBP. The response's incomplete list shows what the broker will still need.
Follow the entry from there with the Entry webhook events.
Minimal request (everything else from the shipment):
{ "file_number": "SI-000123" }
Full request:
{
"reference_number": "MAEU987654321",
"importer_tax_id": "12-3456789",
"entry_type": "01",
"entry_port": "2704",
"unlading_port": "2704",
"entry_date": "2026-12-08",
"arrival_date": "2026-12-08",
"mode_transportation": "11",
"carrier_code": "MAEU",
"vessel_name": "MAERSK ESSEX",
"voyage_no": "448E",
"description": "Laptop computers",
"gross_weight": 1200,
"assigned_to": "jdoe",
"lines": [
{
"invoice_number": "INV-2026-001",
"country_of_origin": "CN",
"mid": "CNWIDWOR2NIN",
"description": "Laptop computers",
"hts": "8471.30.0100",
"value": 12500.00,
"quantity": 100,
"uom": "PCS",
"po_number": "PO-7781",
"part_number": "LT-14"
}
]
}
Identifying the shipment (at least one is required):
| Field | Required | Matches |
|---|---|---|
file_number |
one of the two | the shipment's file number (exact, any case) |
reference_number |
one of the two | the shipment's file number, any reference on the shipment (booking, PO, bill of lading, ...), its pod_id, tracking number or a container number (exact, any case) |
new_entry |
Optional | true to create a further entry when the shipment's entry is already in the Brokerage System (for example a split shipment). Default false: a repeat request is refused with 409 instead of creating a second entry |
Entry fields:
| Field | Required | Format / values | Taken from the shipment when left out |
|---|---|---|---|
importer_tax_id |
Required (request or shipment) | IRS/EIN NN-NNNNNNN (9 digits without the dash are accepted), CBP-assigned NNNNNN-NNNNN, or SSN NNN-NN-NNNN. Also sent as the ultimate consignee |
the first tax ID found on the shipment's consignee, deliver-to or customer company; on a shipment linked to an External TMS order, a party company with no tax ID first takes the one the External TMS holds for it |
entry_port |
Required (request or shipment) | 4-digit CBP port code (2704 Los Angeles). Also sent as the processing port |
the shipment's port of entry from its routing: the last US port reached by air, else by rail, else by ocean; with road legs only, the last US place. Sent when it has a known CBP code |
entry_type |
Optional | 2-digit CBP entry type (01 consumption, 03 AD/CVD, 11 informal, 21 warehouse, ...) |
01 |
unlading_port |
Optional | 4-digit CBP port code | the last US port an ocean leg discharges at |
entry_date |
Optional† | YYYY-MM-DD |
the actual arrival, else the estimated arrival |
arrival_date |
Optional | YYYY-MM-DD |
same as entry_date |
mode_transportation |
Optional | 10 vessel non-container, 11 vessel container, 20/21 rail, 30/31 truck, 40 air, 41 air container |
11 ocean, 40 air |
carrier_code |
Optional | 2–4 character carrier SCAC / IATA code | — |
vessel_name |
Optional | up to 35 characters | the first leg's vessel |
voyage_no |
Optional | up to 5 characters | the first leg's voyage |
description |
Optional | up to 200 characters | the shipment's nature of goods |
gross_weight |
Optional | whole kilograms (integer, at least 1) | the shipment's gross weight |
assigned_to |
Optional | the Brokerage System username of the broker's user the entry is assigned to, up to 20 characters, no spaces (ask our operations team for it) | — (assigned to our integration user) |
lines |
Optional† | list (up to 999) of invoice lines (below). Replaces the shipment's lines when sent | one line per distinct product on the shipment's goods lines (HTS and origin from the SKU catalog, PO and SKU code from the goods line) |
† Not needed to create the entry, but our broker needs it before filing with CBP; while it is
missing it is listed in incomplete.
Invoice line (lines[]) — every field optional; lines with the same invoice_number are sent
as one invoice, one tariff per line:
| Field | Format | Needed before filing (incomplete when missing) |
|---|---|---|
invoice_number |
up to 17 letters, digits or dashes | yes |
country_of_origin |
2-letter ISO country code | yes |
mid |
manufacturer ID, up to 15 characters | yes |
hts |
10 digits; dots and spaces are dropped (8471.30.0100) |
yes |
value |
entered value in USD, a number (12500.00) |
yes |
description |
up to 200 characters | — |
quantity |
a number | — |
uom |
unit of measure, up to 5 characters (PCS when a quantity is sent without one) |
— |
po_number |
up to 50 characters | — |
part_number |
up to 50 characters | — |
Unknown fields (for example a misspelled entry_prot) are rejected with 400 rather than
ignored, so nothing you meant to file is silently dropped.
Responses
Success (200):
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"status": "uploaded",
"detail": "Sent to the Brokerage System — draft entry ND7-2511816-7.",
"entry_number": "ND7-2511816-7",
"filing_status": "in_brokerage",
"incomplete": [
{ "field": "lines[0].mid", "message": "Line 1: manufacturer ID (MID)" }
],
"entry": {
"importer_tax_id": "12-3456789",
"entry_type": "01",
"entry_port": "2704",
"unlading_port": "2704",
"entry_date": "2026-12-08",
"arrival_date": "2026-12-08",
"mode_transportation": "11",
"carrier_code": "",
"vessel_name": "MAERSK ESSEX",
"voyage_no": "448E",
"description": "Laptop computers",
"gross_weight": "1200",
"assigned_to": "jdoe",
"lines": [
{ "invoice_number": "INV-2026-001", "country_of_origin": "CN", "mid": "", "description": "Laptop computers",
"hts": "8471300100", "value": "12500", "quantity": "100", "uom": "PCS", "po_number": "PO-7781", "part_number": "LT-14" }
]
}
}
entry shows every entry field as it was sent (your values merged with the shipment's).
entry_number is the entry number the Brokerage System assigned. CBP's progress arrives later: subscribe to the
Entry webhook events (shipment.entry.filed, shipment.entry.released, ...)
to hear about it.
Errors:
400 Bad Request,"code": "missing_required_fields"— a required field is missing from both the shipment and the request. Nothing is saved or sent;missingnames each field (use the same name in your next request) andincompletelists the data the broker will still need:
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"detail": "Missing required entry fields: importer_tax_id, entry_port.",
"code": "missing_required_fields",
"missing": [
{ "field": "importer_tax_id", "message": "Importer tax ID (IRS/EIN NN-NNNNNNN): send importer_tax_id, or set the tax ID on the shipment's consignee, deliver-to or customer company." },
{ "field": "entry_port", "message": "Port of entry (4-digit CBP port code, e.g. 2704): send entry_port, or route the shipment to a US port with a known CBP code (the last US port reached by air, rail or ocean, else the last US place by road)." }
],
"incomplete": [
{ "field": "entry_date", "message": "Entry date (YYYY-MM-DD)" },
{ "field": "lines", "message": "At least one invoice line (invoice number, country of origin, HTS, value, MID)" }
]
}
Field names are paths into the request: entry_port, lines[0].hts, lines[1].mid.
- 400 Bad Request — a field has the wrong format, an unknown field was sent, or neither
file_number nor reference_number was given (field-based errors, as elsewhere in this API)
- 400 Bad Request, "code": "ambiguous_reference" / 404 Not Found, "code": "not_found" —
as for Send ISF
- 409 Conflict, "code": "already_sent" — the shipment's entry is already in the Brokerage
System (with its
entry_number and filing_status). Send new_entry: true to create a further entry
- 502 Bad Gateway, "code": "brokerage_rejected" — the Brokerage System refused the entry or
couldn't be reached; detail carries its reason. The attempt is recorded for our operations team;
you can correct and retry
- 503 Service Unavailable, "code": "entry_not_configured" — entry filing isn't set up for
your deployment
POST /entry/ doesn't take an Idempotency-Key: a repeat send of the same shipment returns
409 unless it says new_entry: true.
In sandbox mode the request is checked exactly as in live mode (same 400 / 404 / 409),
but nothing is saved or sent: a request that would have been sent returns 200 with
status: "not_sent", detail: "Sandbox mode: not sent to the Brokerage System." and the entry that would
have been sent.
Exception: when your deployment's Brokerage System connection is itself a sandbox (test)
system, a sandbox request is sent to it as in live mode and answered as in live mode
(status: "uploaded", entry_number, ...), but still nothing is saved on our side.
Webhooks
Status updates, event updates, push outcomes, ISF and entry filing updates, ICS2 declaration updates, and quote results are delivered by POSTing an event to a URL you register — they are never returned by polling a "status" endpoint on the resources above.
How webhook deliveries are authenticated
- We issue the signing secret. Registering a webhook returns a
secret(whsec_...) once. Every delivery is signed with it in theX-PartnerAPI-Signatureheader, and you verify that signature to know the request came from us — see Verifying signatures. You can't choose this secret, but you can replace it at any time withrotate-secret. - You may also give us a token of your own. If your receiver can't compute an HMAC (an API
gateway, an automation tool that only checks a static key), register an
auth_header_name/auth_header_valueand we send that header, unchanged, on every delivery as well. It is optional and does not replace the signature. - Your API token is never sent to your webhook. The bearer token you call this API with is only for your requests to us.
Each delivery therefore carries these request headers:
| Header | Always sent? | Value |
|---|---|---|
Content-Type |
yes | application/json |
X-PartnerAPI-Signature |
yes | t={unix timestamp},v1={hex HMAC-SHA256} |
your auth_header_name |
only if registered | your auth_header_value, verbatim |
Registering a webhook
POST /api/partner/v1/webhooks/
{
"url": "https://partner.example.com/webhooks/ops-control",
"event_types": [
"shipment.status_changed",
"shipment.event_completed",
"shipment.tms_push.succeeded",
"shipment.tms_push.failed",
"quote.priced",
"quote.rejected",
"quote.expired"
]
}
event_types is required and lists exactly the events this webhook receives; see the
Event catalog for every type. Customs filing events (shipment.isf.*,
shipment.entry.*, shipment.ics2.*) are never sent unless you list them.
url must be https, must not contain credentials (user:pass@), and its host must resolve
only to public IP addresses — private, loopback, link-local, and other internal ranges are
rejected with 400. The same check runs again before every delivery, so a host that later
starts resolving to an internal address stops receiving events: the attempt is not sent, counts
as a failed attempt (it shows in GET /webhooks/{webhook_id}/deliveries/ with
last_response_status: null), and is retried on the normal schedule in case DNS is corrected.
A rejected URL returns a field error, for example:
{
"url": [
"Webhook host 'intranet.partner.example.com' resolves to a non-public address."
]
}
Other url messages: Webhook URLs must use https., Webhook URLs must not contain
credentials; use auth_header_name/auth_header_value instead., and Could not resolve webhook
host '...'. (the host must already resolve in public DNS when you register).
Optionally, if your receiver can't verify signatures (an API gateway, an automation tool that only checks a static key), give us a header to send on every delivery:
{
"url": "https://partner.example.com/webhooks/ops-control",
"event_types": ["shipment.status_changed"],
"auth_header_name": "Authorization",
"auth_header_value": "Bearer your-own-token"
}
auth_header_valueis sent verbatim;auth_header_namedefaults toAuthorizationwhen omitted. Any other header name works (e.g.X-Api-Key), exceptX-PartnerAPI-Signature,Content-Type,Content-Length,Host,Transfer-Encoding, andConnection.- The value is write-only: responses show
auth_header_name(ornullwhen none is set), never the value. - The header is sent in addition to the signature, not instead of it. Verifying the signature is still recommended.
Response (201, secret shown once — store it, it cannot be retrieved again):
{
"webhook_id": "WH-4A21",
"url": "https://partner.example.com/webhooks/ops-control",
"event_types": [ "shipment.status_changed", "..." ],
"auth_header_name": "Authorization",
"secret": "whsec_2f6b1e...",
"created_at": "2026-04-10T09:15:00+00:00"
}
Managing webhooks
| Method | Path | Purpose |
|---|---|---|
GET |
/webhooks/ |
List your subscriptions (no secrets or auth header values) |
GET |
/webhooks/{webhook_id}/ |
One subscription |
PATCH |
/webhooks/{webhook_id}/ |
Change any of url, event_types, auth_header_name, auth_header_value. The two auth fields are replaced together: sending auth_header_name requires auth_header_value, and an empty auth_header_value removes the header. A new url goes through the same checks as registration. |
POST |
/webhooks/{webhook_id}/rotate-secret/ |
Issue a new signing secret, returned once in the response (same shape as registration) |
DELETE |
/webhooks/{webhook_id}/ |
Remove the subscription |
GET |
/webhooks/{webhook_id}/deliveries/ |
Last 100 delivery attempts (status, response code, timestamps) for debugging |
Rotating the signing secret
POST /webhooks/{webhook_id}/rotate-secret/ replaces the secret immediately. There is no
overlap period: every delivery sent after the call, including retries of events queued before
it, is signed with the new secret. To rotate without rejecting events, have your receiver accept
either the old or the new secret for a few minutes, call rotate, store the new secret, then drop
the old one. Using verify_signature from Verifying signatures:
def verify_with_any(secrets, raw_body, header_value):
return any(verify_signature(s, raw_body, header_value) for s in secrets if s)
# during the switch-over window:
ok = verify_with_any([NEW_SECRET, OLD_SECRET], raw_body, request.headers["X-PartnerAPI-Signature"])
The partner-supplied auth header is independent of the secret: rotating the secret leaves it
unchanged, and changing it with PATCH leaves the secret unchanged.
Event envelope
Every webhook is a single POST to your URL with this shape:
{
"event_id": "EVT-01JQABC123",
"event_type": "shipment.status_changed",
"occurred_at": "2026-04-11T16:05:00+00:00",
"data": { }
}
data holds the relevant object for that event type — see the tables below. event_id is
unique per event (shared across every subscription an event fans out to, so two of your
subscriptions receiving the same event see the same event_id) but is not sortable — because
delivery is at-least-once, dedupe on it rather than assuming exactly-once delivery, and use
occurred_at if you need ordering.
Event catalog
| Event type | Fired when | data contains |
|---|---|---|
shipment.status_changed |
The shipment's top-level status changes | pod_id, previous_status, status, changed_at |
shipment.event_completed |
An externally visible event is completed | pod_id, event, label, location, due_at, completed_at, updated_at |
shipment.container_assigned |
The carrier assigns a container number to a container line | pod_id, container_id, container_type, container_number, assigned_at |
shipment.tms_push.succeeded |
A send to the External TMS completes successfully | pod_id, document_type (prealert|shippingorder), tms_order_id, pushed_at |
shipment.tms_push.failed |
A send to the External TMS fails | pod_id, error, failed_at |
shipment.document_available |
A new document is added to the shipment | pod_id, document_id, document_type (see Document types), file_name |
shipment.isf.status_changed |
The shipment's ISF changes status (any change below, plus transmitted and cancelled) |
ISF event data |
shipment.isf.sent |
The ISF is uploaded to the Brokerage System (status in_brokerage, or transmitted when your deployment transmits straight to CBP) |
ISF event data |
shipment.isf.failed |
Sending the ISF to the Brokerage System failed (status error) |
ISF event data; detail carries the reason |
shipment.isf.accepted |
CBP accepted the ISF (status accepted or accepted_warnings) |
ISF event data |
shipment.isf.rejected |
CBP rejected the ISF (status rejected) |
ISF event data; customs_status / detail carry CBP's answer |
shipment.entry.status_changed |
One of the shipment's entries changes status (any change below, plus cancelled) |
Entry event data |
shipment.entry.sent |
The entry is created in the Brokerage System (status in_brokerage) |
Entry event data |
shipment.entry.failed |
Sending the entry to the Brokerage System failed (status error) |
Entry event data; detail carries the reason |
shipment.entry.filed |
The entry is filed with CBP (status filed) |
Entry event data |
shipment.entry.on_hold |
CBP put the entry on hold (status on_hold) |
Entry event data; customs_status / detail carry CBP's answer |
shipment.entry.released |
CBP released the cargo (status released) |
Entry event data; cargo_release_date is set |
shipment.ics2.status_changed |
The shipment's ICS2 declaration changes status (every change in ICS2 events, plus risk_analysis and invalidated) |
ICS2 event data |
shipment.ics2.submitted |
The declaration (or an amendment, amendment: true) is lodged with customs (status submitted) |
ICS2 event data |
shipment.ics2.accepted |
Customs registered the declaration (status accepted); mrn is set |
ICS2 event data |
shipment.ics2.cleared |
Customs finished its risk assessment (status cleared) |
ICS2 event data |
shipment.ics2.action_required |
Customs needs something: a request for information (information_request), screening (screening_request), or a do-not-load instruction (do_not_load) |
ICS2 event data; action_required / response_deadline say what and by when |
shipment.ics2.rejected |
Customs rejected the declaration (status rejected) or an amendment (amendment: true) |
ICS2 event data; detail carries customs' reasons |
shipment.ics2.failed |
Filing the declaration failed (status error) |
ICS2 event data; detail carries the reason |
quote.priced |
A rate desk returns pricing for a submitted quote request | full Quote object with status: "priced" |
quote.rejected |
A quote request cannot be priced | quote_request_id |
quote.expired |
A priced quote passes valid_until without being accepted |
quote_request_id |
ISF events
ISF events are only sent to subscriptions that list them in event_types: register (or
PATCH) a webhook with the ISF event types you want, e.g. only the customs outcome:
{
"url": "https://partner.example.com/webhooks/isf",
"event_types": ["shipment.isf.accepted", "shipment.isf.rejected", "shipment.isf.failed"]
}
or shipment.isf.status_changed alone to follow every step. They fire for every ISF on your
companies' shipments, whether it was filed with Send ISF to Brokerage System,
by our operations team, or automatically from the External TMS. One change can match more than one type
(an upload is both shipment.isf.status_changed and shipment.isf.sent); a subscription that
lists both receives one delivery for each, with different event_ids.
data:
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"isf_id": "ISF-42",
"previous_status": "in_brokerage",
"status": "accepted",
"brokerage_reference": "98765",
"isf_transaction_number": "ST9-12345678944",
"bill_type": "OB",
"bill_number": "MAEU987654321",
"transmitted": true,
"customs_status": "Accepted",
"detail": "The Brokerage System: Accepted",
"changed_at": "2026-11-21T15:10:00+00:00"
}
| Field | Meaning |
|---|---|
isf_id |
our id for this ISF filing (a shipment gets a new one if an ISF is cancelled and filed again) |
status |
in_brokerage (with our broker), transmitted (sent to CBP), error (send failed), accepted, accepted_warnings, rejected (CBP's answer), cancelled |
previous_status |
the status before; may also be draft or ready_to_send (an ISF being prepared, which fires no event itself) |
brokerage_reference |
the Brokerage System's reference for the upload (blank until uploaded) |
isf_transaction_number |
the ISF transaction number CBP assigned (blank until CBP answers) |
bill_type, bill_number |
the bill of lading the ISF was filed under (OB master, BM AMS house bill) |
transmitted |
whether the ISF has been transmitted to CBP |
customs_status |
CBP's latest status text as the Brokerage System reports it |
detail |
why the status changed: the upload confirmation, the Brokerage System's error for error, or CBP's answer |
changed_at |
when the status changed |
Entry events
Entry events are only sent to subscriptions that list them in event_types: register (or
PATCH) a webhook with the entry event types you want, e.g. only holds and releases:
{
"url": "https://partner.example.com/webhooks/entry",
"event_types": ["shipment.entry.on_hold", "shipment.entry.released", "shipment.entry.failed"]
}
or shipment.entry.status_changed alone to follow every step. They fire for every entry on your
companies' shipments, whether it was created with Send Entry to Brokerage System,
by our operations team, automatically from the External TMS, or directly in the Brokerage System by the broker. A
shipment can have more than one entry: entry_id tells them apart. One change can match more
than one type (a send is both shipment.entry.status_changed and shipment.entry.sent); a
subscription that lists both receives one delivery for each, with different event_ids.
data:
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"entry_id": "ENTRY-57",
"previous_status": "filed",
"status": "released",
"entry_number": "ND7-2511816-7",
"entry_type": "01",
"port_of_entry": "2704",
"customs_status": "Cargo released",
"status_7501": "Accepted",
"cargo_release_date": "2026-12-09",
"detail": "The Brokerage System: Cargo released",
"changed_at": "2026-12-09T18:02:00+00:00"
}
| Field | Meaning |
|---|---|
entry_id |
our id for this entry (a shipment may have several) |
status |
in_brokerage (with our broker), error (send failed), filed (filed with CBP), on_hold (CBP hold), released (cargo released), cancelled |
previous_status |
the status before; may also be draft or ready_to_send (an entry being prepared, which fires no event itself) |
entry_number |
the Brokerage System's entry number (blank until the entry is in it) |
entry_type |
the CBP entry type |
port_of_entry |
the port of entry as the Brokerage System reports it (blank until the Brokerage System reports on the entry) |
customs_status |
CBP's latest status text as the Brokerage System reports it |
status_7501 |
the entry summary (7501) status as the Brokerage System reports it |
cargo_release_date |
the date CBP released the cargo (YYYY-MM-DD), or null |
detail |
why the status changed: the send confirmation, the Brokerage System's error for error, or CBP's answer |
changed_at |
when the status changed |
ICS2 events
ICS2 events are only sent to subscriptions that list them in event_types: register (or
PATCH) a webhook with the ICS2 event types you want, e.g. only the customs outcome and
anything customs needs from you:
{
"url": "https://partner.example.com/webhooks/ics2",
"event_types": ["shipment.ics2.accepted", "shipment.ics2.action_required", "shipment.ics2.rejected", "shipment.ics2.failed"]
}
or shipment.ics2.status_changed alone to follow every step. They fire for every ICS2
declaration on your companies' shipments, whether it was sent with
File ICS2 with EU Customs, by our operations team, or automatically
from the External TMS. Preparing a declaration (draft, ready to file, editing an amendment) fires
nothing. One change can match more than one type (a submission is both
shipment.ics2.status_changed and shipment.ics2.submitted); a subscription that lists both
receives one delivery for each, with different event_ids.
Customs often sends a rejection first and its reasons about a minute later; when the reasons
arrive, shipment.ics2.rejected is sent again (same status, new event_id) with the reasons
in detail. A failed amendment is answered in the POST /ics2/ response; the declaration
stays lodged, so no event fires for it.
data:
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "SI-000123",
"ics2_id": "ICS2-17",
"lrn": "POD261112AB12CD3",
"mrn": "26NL010000G5FEDAT0",
"filing_type": "F15",
"previous_status": "submitted",
"status": "accepted",
"amendment": false,
"action_required": "",
"response_deadline": null,
"detail": "Registered by customs, MRN 26NL010000G5FEDAT0.",
"changed_at": "2026-11-21T15:10:00+00:00"
}
| Field | Meaning |
|---|---|
ics2_id |
our id for this declaration (a shipment gets a new one if a declaration is invalidated and filed again) |
lrn |
our Local Reference Number for the declaration |
mrn |
customs' Movement Reference Number (blank until customs registers the declaration) |
filing_type |
F11, F15, F26, F34 or F50 |
status |
submitted (lodged), accepted (registered), risk_analysis (customs is assessing it), cleared (assessment complete), information_request, screening_request, do_not_load (customs needs action), rejected, error (sending failed), invalidated (withdrawn); amendment_draft only on an amendment customs rejected |
previous_status |
the status before; may also be draft, ready_to_file, submitting or amendment_draft (a declaration being prepared, which fires no event itself) |
amendment |
true when this is a submitted or rejected amendment to a declaration customs already has |
action_required |
what customs asked for, while a referral is open |
response_deadline |
when customs needs the answer by, if known (ISO 8601) |
detail |
why the status changed: the submission confirmation, why filing failed for error, customs' message or rejection reasons |
changed_at |
when the status changed |
Verifying signatures
Each request carries:
X-PartnerAPI-Signature: t=1744300500,v1=5e3a1f...
Compute the expected signature as HMAC-SHA256(secret, "{t}.{raw_request_body}") and compare
to v1 using a constant-time comparison. Reject any request where t is more than 5 minutes
from the current time, to guard against replay.
import hashlib
import hmac
import time
def verify_signature(secret, raw_body, header_value, tolerance_seconds=300):
parts = dict(p.split("=", 1) for p in header_value.split(","))
timestamp, signature = parts["t"], parts["v1"]
if abs(time.time() - int(timestamp)) > tolerance_seconds:
return False
signed_payload = f"{timestamp}.{raw_body.decode()}"
expected = hmac.new(secret.encode(), signed_payload.encode(), hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
Delivery and retries
- your endpoint must respond
2xxwithin 10 seconds; anything else counts as a failure - redirects are not followed — a
3xxresponse counts as a failure, so register the final URL - failed deliveries are retried with backoff: immediately, then at 1m, 5m, 30m, 2h, and 12h
- after the final retry the delivery is marked
failedand viewable atGET /webhooks/{webhook_id}/deliveries/; it is not retried further - if a delivery is missed, reconcile using
GET /shipments/{pod_id}/orGET /quotes/{quote_request_id}/— both always reflect current state regardless of webhook delivery
Data Models
Shipment object
{
"pod_id": "POD-01JQXYZABC1",
"file_number": "FILE-000123",
"company": { "id": 12, "name": "Acme Imports" },
"status": "in_transit",
"mode": "ocean",
"trade": "import",
"load": "fcl",
"incoterm": "FOB",
"origin": { "unlocode": "CNSHA", "name": "Shanghai" },
"destination": { "unlocode": "USLAX", "name": "Los Angeles" },
"routing": [
{
"sequence": 1,
"origin": { "unlocode": "CNSHA", "name": "Shanghai, CN" },
"etd": "2026-04-01T08:00:00Z",
"atd": "2026-04-02T14:00:00Z",
"destination": { "unlocode": "USLAX", "name": "Los Angeles, CA, US" },
"eta": "2026-04-20T06:00:00Z",
"ata": null,
"mode": "ocean",
"vessel": "MAERSK ESSEX",
"voyage": "412E",
"flight": "",
"carrier": "Maersk"
},
{
"sequence": 2,
"origin": { "unlocode": "USLAX", "name": "Los Angeles, CA, US" },
"etd": null,
"atd": null,
"destination": { "unlocode": "", "name": "Ontario, CA, US" },
"eta": null,
"ata": null,
"mode": "road",
"vessel": "",
"voyage": "",
"flight": "",
"carrier": "Acme Trucking"
}
],
"parties": [
{
"name": "Blue Ocean Supply Co.",
"address_line1": "123 Factory Rd",
"city": "Shenzhen",
"state": "",
"postal_code": "518000",
"country": "CN",
"contact_name": "Li Wei",
"contact_phone": "+86 138 0000 0000",
"roles": ["pickup_from", "shipper"]
},
{
"name": "Acme Imports DC",
"address_line1": "500 Warehouse Way",
"city": "Ontario",
"state": "CA",
"postal_code": "91761",
"country": "US",
"contact_name": "Jane Doe",
"contact_phone": "+1 909-555-0100",
"roles": ["deliver_to"]
}
],
"ready_date": "2026-04-10",
"eta_destination": "2026-04-20",
"notes": "Fragile cargo, handle with care.",
"containers": [
{ "container_id": "CNT-8F31", "container_type": "40HC", "container_number": "MSCU1234567" },
{ "container_id": "CNT-8F32", "container_type": "40HC", "container_number": null }
],
"pieces": [
{
"label_code": "PC-8F2A1B3C9D0E",
"pieces": 48,
"packaging_type": "boxes",
"pallets": 1,
"description": "widgets",
"weight": { "value": 18000, "unit": "kg" },
"dimensions": { "length": 120, "width": 125, "height": 100, "unit": "cm" },
"sku": "SKU-123",
"serial_number": "SN_123456",
"po_number": "PO-100234",
"container_number": "MSCU1234567",
"catalog_sku": { "id": "SKU-41", "sku_code": "SKU-123", "name": "Widget, blue" }
}
],
"references": [
{ "reference_type": "Booking Number", "reference_number": "BKG-1001" },
{ "reference_type": "PO Number", "reference_number": "PO-100234" }
],
"current_event": {
"event": "departed_origin_port",
"label": "Departed origin port",
"due_at": "2026-04-02T14:00:00+00:00",
"completed_at": "2026-04-02T14:00:00+00:00",
"updated_at": "2026-04-02T14:05:12+00:00",
"estimated": false
},
"tms_push": {
"status": "succeeded",
"document_type": "prealert",
"tms_order_id": "SC-88213",
"detail": ""
},
"created_at": "2026-04-10T09:15:00+00:00",
"updated_at": "2026-04-11T16:05:00+00:00"
}
status values: new, in_bound, received, on_hold, available, departed,
pending_pickup, dispatched, in_transit, final_mile_processing, delivered,
pending_confirmation, pending_departure, arrived, out_for_delivery, closed,
cancelled. A newly created shipment is always new.
file_number is our own file/job number for this shipment — the identifier our operations
team and any paperwork we send you will reference. It's auto-assigned immediately on
creation and present from your very first response onward; operations may later relabel it
to match a different internal reference format. It can be null only for pre-existing
shipments from before file numbers were tracked -- treat pod_id as the one identifier
guaranteed to be stable and always present.
origin and destination summarize the whole trip: the first leg's origin and the last
leg's destination. routing lists every leg in order (sequence), each with its own
origin/destination, planned (etd, eta) and actual (atd, ata) departure and
arrival times (ISO 8601, null until known), mode, vessel/voyage (ocean),
flight (air), and carrier (name, "" when unknown). routing is [] until the
shipment has routing.
current_event is the most recent event that has been completed, or null if none has been
yet. Its fields match the items returned by List Shipment Events.
containers[].container_number and pieces[].container_number are null until the carrier
assigns a number and the line is loaded — see shipment.container_assigned above.
tms_push.status values: not_requested, succeeded, failed. There is one send per
shipment, and document_type (prealert or shippingorder) reports which kind it was — chosen
by us on an auto-send, or by you on Send Shipment to External TMS.
pieces[].label_code is a stable per-piece identifier, usable later with
Initiate a Consolidation.
Quote object
{
"quote_request_id": "QT-7C3D1A9B4E",
"company": { "id": 12, "name": "Acme Imports" },
"status": "priced",
"mode": "ocean",
"load": "fcl",
"origin": { "unlocode": "CN", "name": "Shanghai" },
"destination": { "unlocode": "US", "name": "Los Angeles" },
"currency": "USD",
"all_in_rate": "3450.00",
"transit_days": 18,
"valid_until": "2026-04-24",
"created_at": "2026-04-10T09:15:00+00:00"
}
status values: submitted, priced, rejected, expired, accepted
There is no reference or carrier field. origin.unlocode / destination.unlocode are
2-letter country codes, not the full UN/LOCODE you submitted — a quote only stores a port name
and country, unlike a shipment's full routing leg.
Warehouse Stay object
{
"pod_id": "POD-01JQXYZABC1",
"shipment_number": "ACMEIM-260501-001",
"status": "in_bound",
"facility_code": "SEA01",
"estimated_arrival_date": "2026-05-01",
"pickup_trucker_name": "Harbor Drayage",
"dropoff_trucker_name": "Local Cartage Co",
"notes": "Fragile cargo, handle with care.",
"pieces": [
{
"label_code": "PC-8F2A1B3C9D0E",
"pieces": 4,
"packaging_type": "pallet",
"pallets": 1,
"description": "widgets",
"weight": { "value": 900, "unit": "kg" },
"dimensions": null,
"sku": "",
"serial_number": "",
"po_number": "",
"container_number": null,
"catalog_sku": null
}
],
"created_at": "2026-04-10T09:15:00+00:00",
"updated_at": "2026-04-10T09:15:00+00:00"
}
status is always in_bound on creation — it changes only when we physically handle the
freight (received, available, dispatched, and so on; see the Shipment object
for the full status list, which this shares). pickup_trucker_name/dropoff_trucker_name are
null if none was given. pod_id links back to the Shipment object this
warehouse stay belongs to — a partner-created warehouse stay always has one, whether it was
attached to an existing shipment, created standalone, or produced by a consolidation.
shipment_number is that same shipment's file_number — a partner-created warehouse stay
always has a linked shipment, so it's populated the same way and to the same value.
SKU object
{
"id": "SKU-41",
"company": { "id": 12, "name": "Acme Imports" },
"sku_code": "WID-BLUE-01",
"name": "Widget, blue",
"description": "",
"upc": "012345678905",
"ean": "",
"isbn": "",
"mpn": "",
"category": "Hardware",
"brand": "Acme",
"manufacturer": "",
"color": "Blue",
"size": "",
"material": "",
"flavor": "",
"attributes": { "style": "slim" },
"unit_of_measure": "case",
"units_per_package": 12,
"reorder_point": 50,
"unit_cost": 4.25,
"sales_price": 9.99,
"currency": "USD",
"supplier": { "id": 77, "name": "Blue Ocean Supply Co." },
"supplier_sku": "BOS-4471",
"lead_time_days": 30,
"supplier_terms": "Net 30",
"weight": { "value": 1.2, "unit": "kg" },
"dimensions": { "length": 30, "width": 20, "height": 10, "unit": "cm" },
"hs_code": "8479.89",
"country_of_origin": "CN",
"is_active": true,
"notes": "",
"quantity_on_hand": 240,
"created_at": "2026-04-10T09:15:00+00:00",
"updated_at": "2026-04-12T14:02:00+00:00"
}
| Field | Notes |
|---|---|
sku_code |
up to 100 characters, unique per company (ignoring case) |
name |
up to 255 characters |
upc, ean, isbn |
up to 32 characters each |
unit_of_measure |
each, box, case, pallet (default each) |
units_per_package |
items in one unit of measure, at least 1 (default 1) |
weight |
the weight of one unit of measure; unit is kg or lbs |
dimensions |
the size of one unit of measure; unit is cm, in, or ft |
unit_cost, sales_price |
up to 4 decimal places, not negative |
currency |
3-letter code (default USD) |
country_of_origin |
2-letter ISO country code |
attributes |
any other variant options, as a JSON object |
supplier |
null when none is set |
weight, dimensions |
null when not set |
quantity_on_hand |
read-only; see SKU Catalog |
Field values
Mode, trade, and load
| Field | Values |
|---|---|
mode |
ocean, air, rail, road |
trade |
import, export, domestic |
load is restricted by mode:
mode |
Allowed load |
|---|---|
ocean, rail |
fcl, lcl |
road |
ftl, ltl |
air |
ftx, b2b, consol |
Parties
Fields on each parties[] entry:
| Field | Required | Notes |
|---|---|---|
name |
yes | |
roles |
yes | One or more of the roles below |
address_line1, address_line2, city, state, postal_code, country |
no | |
contact_name, contact_email, contact_phone |
no |
Accepted roles: shipper, consignee, notify, pickup_from, deliver_to, bill_to.
Pieces
| Field | Values |
|---|---|
weight.unit |
kg, lbs |
dimensions.unit |
cm, in, ft |
Goods lines by SKU code
On Create Shipment, Update Shipment, and the
warehouse-stay endpoints (13,
15), pieces[].sku assigns a goods line to a SKU: when
the code matches an active SKU in the shipment company's catalog (ignoring
case), the line is linked to it and the fields you left out are filled from the catalog:
| Line field | Filled from the SKU when omitted |
|---|---|
description |
name |
packaging_type |
unit_of_measure (Each, Box, Case, Pallet) |
dimensions |
dimensions |
weight |
the SKU's weight × pieces (only while pallets is 1) |
Anything you send on the line wins over the catalog. The linked SKU comes back on each piece as
catalog_sku ({"id", "sku_code", "name"}):
{ "pieces": [ { "sku": "WID-BLUE-01", "pieces": 20 } ] }
A code that isn't in the catalog (or belongs to a retired SKU, or to another company) is still
saved on the line as plain text, with catalog_sku: null; check catalog_sku in the response
if every line must be linked. Add the SKU first with Add SKU(s) to link it.
Reference types
references[].reference_type uses the platform's standard reference types. Commonly used
values: Booking Number, PO Number, Bill of Lading, House Bill, Master Bill,
Air Bill, Order Number, Invoice Number, Shipper Reference, Consignee Reference,
General Reference.
Document types
document_type on Upload Document, on Create Shipment's documents[],
in List Shipment Documents responses, and in the
shipment.document_available webhook is always one of these values:
| Value | Meaning |
|---|---|
bol |
Bill of Lading |
commercial_invoice |
Commercial Invoice |
packing_list |
Packing List |
invoice |
Invoice |
credit_note |
Credit Note |
purchase_order |
Purchase Order |
transport_order |
Transport Order |
quote |
Quote |
pickup_order |
Pickup Order |
delivery_order |
Delivery Order |
availability_notice |
Availability Notice |
proof_of_delivery |
Proof of Delivery |
certificate_of_origin |
Certificate of Origin |
phyto_sanitary_certificate |
Phyto Sanitary Certificate |
dangerous_goods_declaration |
Dangerous Goods Declaration |
hazmat_cert |
Hazmat Certificate |
hold_report |
Hold Report |
receipt |
Receipt |
label |
Pallet Label |
photo |
Photo |
other |
Other |
Send the value in the left column (matching ignores case and surrounding spaces, and responses
always return it in lowercase). When you send a value that isn't in this list (or
leave document_type out), the document is stored as other and your value is kept as its
label; responses and webhooks for it report other.
tms_push.document_type (prealert or shippingorder) is a different field: it names the
kind of send made to the External TMS, not the type of a document on the shipment, and it
never takes the values above.
Error Handling
Typical responses:
401 Unauthorized— missing or invalid bearer token403 Forbidden— token is valid but not authorized for the requested account or resource404 Not Found— resource does not exist or does not belong to your account400 Bad Request— validation error in the JSON payload409 Conflict—Idempotency-Keyreused with a different request body; a shipment that was already sent to a third-party system can't be updated ("code": "shipment_locked"); or a shipment was already sent to the External TMS, or its ISF or entry already filed ("code": "already_sent"), or its ICS2 declaration already lodged with nothing to change ("code": "already_submitted")502 Bad Gateway— Send Shipment to External TMS couldn't deliver to the External TMS, Send ISF to Brokerage System or Send Entry to Brokerage System was refused by the Brokerage System, or File ICS2 with EU Customs was refused when filed; retry later503 Service Unavailable— Send ISF to Brokerage System, Send Entry to Brokerage System or File ICS2 with EU Customs isn't set up for your account429 Too Many Requests— rate limit exceeded; seeRetry-Afterheader
Validation responses use field-based JSON errors, for example:
{
"origin": [
"Unknown UN/LOCODE."
]
}
Rate Limiting
Default limit is 120 requests/minute per token. Responses include:
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1744300560
Example cURL
Create a shipment:
curl -X POST https://example.com/api/partner/v1/shipments/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3f9a7b2c-1e4d-4a6b-9c3e-2b1a4f8d7c6e" \
-d '{
"references": [
{ "reference_type": "Booking Number", "reference_number": "BKG-1001" }
],
"mode": "ocean",
"origin": { "unlocode": "CNSHA" },
"destination": { "unlocode": "USLAX" }
}'
Correct a shipment before it is sent (only the fields you send change):
curl -X PATCH https://example.com/api/partner/v1/shipments/POD-01JQXYZABC1/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"trade": "import",
"destination": { "unlocode": "USLGB", "name": "Long Beach" }
}'
Check what a send to the External TMS would need, then send it as a prealert:
curl https://example.com/api/partner/v1/shipments/POD-01JQXYZABC1/send-to-tms/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN"
curl -X POST https://example.com/api/partner/v1/shipments/POD-01JQXYZABC1/send-to-tms/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"document_type": "prealert"}'
File a shipment's ISF, adding the seller and one product line to what the shipment has:
curl -X POST https://example.com/api/partner/v1/isf/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"file_number": "SI-000123",
"parties": {"SE": {"name": "Blue Ocean Supply Co.", "street": "88 Harbour Rd", "city": "Shenzhen", "country": "CN"}},
"lines": [{"manufacturer": {"name": "Widget Works Ltd", "street": "2 Factory Rd", "city": "Ningbo", "country": "CN"},
"country_of_origin": "CN", "hts": "8471.30.0100"}]
}'
Create a shipment's customs entry, adding the port of entry and one invoice line to what the shipment has:
curl -X POST https://example.com/api/partner/v1/entry/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"file_number": "SI-000123",
"entry_port": "2704",
"lines": [{"invoice_number": "INV-2026-001", "country_of_origin": "CN", "mid": "CNWIDWOR2NIN",
"hts": "8471.30.0100", "value": 12500.00, "quantity": 100}]
}'
Lodge a shipment's ICS2 declaration, adding the customs office and an HS code to what the shipment has:
curl -X POST https://example.com/api/partner/v1/ics2/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"file_number": "SI-000123",
"general": {"customsOfficeOfFirstEntry": {"referenceNumber": "NL000396"}},
"houses": [{"goodsItem": [{"commodity": {"commodityCode": {"harmonizedSystemSubHeadingCode": "871499"}}}]}]
}'
List the fields an F11 declaration takes, with which are required:
curl https://example.com/api/partner/v1/ics2/fields/?filing_type=F11 \
-H "Authorization: Bearer $PARTNER_API_TOKEN"
Request a quote:
curl -X POST https://example.com/api/partner/v1/quotes/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mode": "ocean",
"origin": { "unlocode": "CNSHA" },
"destination": { "unlocode": "USLAX" },
"ready_date": "2026-05-01",
"cargo": {
"containers": [
{ "container_type": "40HC", "count": 2 }
]
}
}'
Register a webhook:
curl -X POST https://example.com/api/partner/v1/webhooks/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://partner.example.com/webhooks/ops-control",
"event_types": ["shipment.status_changed", "quote.priced"]
}'
Register a webhook that also sends your own token on every delivery:
curl -X POST https://example.com/api/partner/v1/webhooks/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://partner.example.com/webhooks/ops-control",
"event_types": ["shipment.status_changed"],
"auth_header_name": "X-Api-Key",
"auth_header_value": "'"$MY_RECEIVER_KEY"'"
}'
Change that token later (or send "auth_header_value": "" to remove it):
curl -X PATCH https://example.com/api/partner/v1/webhooks/WH-4A21/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"auth_header_name": "X-Api-Key", "auth_header_value": "'"$MY_NEW_RECEIVER_KEY"'"}'
Rotate the signing secret (the response contains the new secret, shown once):
curl -X POST https://example.com/api/partner/v1/webhooks/WH-4A21/rotate-secret/ \
-H "Authorization: Bearer $PARTNER_API_TOKEN"
End-to-End Example
- Partner registers a webhook for
shipment.*andquote.*events. - Partner calls
POST /shipments/. This account is configured on our side to auto-send to the External TMS, so the send happens before the response comes back: the response confirms creation withpod_idandtms_push.status = "succeeded",tms_push.document_type = "prealert"— our system chose that document type on its own. (An account without auto-send would instead fix anything missing withPATCH /shipments/{pod_id}/and then callPOST /shipments/{pod_id}/send-to-tms/, optionally naming the document type.) - As the shipment moves,
shipment.event_completedandshipment.status_changedevents arrive as updates are ingested. - Separately, partner calls
POST /quotes/for a new request. Response confirms submission. - When the rate desk prices it,
quote.pricedarrives with the rate. - Partner calls
POST /quotes/{quote_request_id}/accept/, which creates a new shipment the same wayPOST /shipments/would.