Consignment Import

Consignment imports are the mechanism for creating consignments in Consignly via the API. An import submission is accepted, validated, and processed asynchronously, resulting in a consignment being created in the platform.

Imports are the primary integration path for external systems, carriers, and automation workflows that need to push consignment data into Consignly. Each import is scoped to the caller's identity connection, ensuring data isolation between integrations.

Processing Lifecycle

When sending a consignment import the API accepts a valid request immediately and returns a 202 Accepted with the new import ID — the consignment is then processed asynchronously. The consignment will have the same ID as the import ID.

POST /v1/consignment-imports
  └─ Validate request structure
  └─ Acquire idempotency lock (if key provided)
  └─ Store import record → return 202 with consignmentImportId

Background processing:
  └─ Resolve references (client, warehouse, carrier, products)
  └─ Create consignment (if all references resolved)
  └─ OR → Place in reconciliation queue (if unresolved references)

Monitoring the import process can be done using a webhook for the consignment-import-reconciled event or using the GET /v1/consignments/{consignmentId or importId}/check-exists to test the state using the following response codes.

Response	Meaning
`201 Created`	Consignment was created successfully
`202 Accepted`	Import is still being processed
`404 Not Found`	Import or consignment not found

Note that the consignment import data can only be created via the API. Updates to the import records are not supported.

Idempotency

Provide an idempotencyKey in the request body to prevent duplicate consignment creation when retrying failed or timed-out requests.

The key is scoped to the caller's identity connection — the same key value can be used by different connections without conflict
Maximum length: 200 characters
If a key has already been used by the same connection, the request is rejected with 409 Conflict
Omit the key when each request is intentionally unique

Use idempotency keys any time the same import payload may be submitted more than once (e.g., retries, queued systems with at-least-once delivery).

Reference Resolution and Reconciliation

During background processing, the system resolves references by code: clientCode, warehouseCode, carrierCode, address code and productCode on each product line. Addresses will also attempt to resolve to an existing record by text matches. If any reference cannot be matched to an existing record, the import is placed in the reconciliation queue rather than failing outright. Imports in the reconciliation queue require manual resolution in the Consignly portal before the consignment is created.

Reconciliation behaviour is configurable per client partner:

Setting	Effect
Auto-reconciliation enabled	System attempts to create missing addresses and partners automatically
Allow consignee create	Creates a new consignee address if one is not found
Allow origin create	Creates a new origin address if one is not found
Validate address	Validates address data during reconciliation
Provisional products	Allows unknown product codes to be imported as provisional products pending manual resolution

Warehouse Transfers

When an outwards consignment's destination address is a warehouse managed by Consignly then an inwards consignment can automatically be created at the destination warehouse. This is referred to as Consignly Connect.

The feature must be enabled for the organisation
The destination warehouse is identified by matching the address provided in the import. Ie, setting the warehouse code to destination address code.
The outwards and inwards consignments are linked as a transfer pair

See What is Consignly Connect? for details on sharing consignment data between organisations.

Consignment Types

All three consignment types can be created via import:

Value	Type	Description
`0`	PointToPoint	Direct transfer bypassing warehouse storage
`1`	Inwards	Receiving inventory into the warehouse
`2`	Outwards	Dispatching inventory from the warehouse

Attachments

Attachments can be added to Notes on the consignment

For each attachment, provide either:

content — Base64-encoded file content inline
downloadUrl — A URL from which the API will download the file at submission time

Both fileName and contentType are optional when using downloadUrl; the API will derive them from the downloaded file if not provided.

File type and size restrictions apply. Only supported MIME types and files within the allowed size limit will be accepted.

Products and Serial Numbers

Each product line in the import maps to a product on the client's partner record via productCode. Each product requires at least one item in the items array.

Non-serialised products: Use a single item with the total quantity.

Serialised products depend on the product's serial capture mode configured in Consignly:

Mode	Direction	Behaviour
Full-capture	Inwards	Supply serials if known; capture can be deferred to receiving
Full-capture	Outwards	Supply specific serials to pin allocation, or omit to let Consignly allocate during picking
Release-capture	Inwards/Outwards	Do not supply serials — captured by warehouse staff at time of pick or receipt

When specifying serials, each serial must be its own item object with quantity: 1. Never specify a serial with a quantity greater than 1.

Logistic Units

Logistic unit data is specified at the product line level using logisticUnitSsccNumber and logisticUnitReferenceNumber. Multiple product lines can reference the same logistic unit by sharing the same SSCC number — Consignly will associate all matching product lines with the same unit.

Inwards: Products are received onto the specified logistic unit
Outwards: The product line requests inventory from the specified logistic unit

Consignment Import Endpoints — Request schema, parameters, and examples
Consignments — Consignment types, statuses, and lifecycle
Partners — Client and carrier code resolution

Consignments

Partners