Partner API v.1.0

This API lets you integrate directly with our platform instead of using the customer portal. It exposes:

Base path:

/api/partner/v1/

Your API host is provided during onboarding. Examples in this guide use example.com as a placeholder host.

Authentication:

Transport requirements:

Idempotency:

Companies:

Sandbox mode:

Brokerage System:

External TMS:

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):

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:

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:

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:

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:

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:

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:

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:

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 Conflict with "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:

{
  "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"
}

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:

{
  "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)"]
}

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:

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:

{
  "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:

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:

{
  "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:

{
  "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

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"
}

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

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:

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

  1. Partner registers a webhook for shipment.* and quote.* events.
  2. 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 with pod_id and tms_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 with PATCH /shipments/{pod_id}/ and then call POST /shipments/{pod_id}/send-to-tms/, optionally naming the document type.)
  3. As the shipment moves, shipment.event_completed and shipment.status_changed events arrive as updates are ingested.
  4. Separately, partner calls POST /quotes/ for a new request. Response confirms submission.
  5. When the rate desk prices it, quote.priced arrives with the rate.
  6. Partner calls POST /quotes/{quote_request_id}/accept/, which creates a new shipment the same way POST /shipments/ would.