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.

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.

Minimum data for auto-reconciliation

For an import to auto-reconcile without manual intervention, the minimum identifiers are:

• clientCode at the root level
• warehouseCode at the root level
• products[].productCode on every product line

These values must match existing records in Consignly. If any one of them is missing or cannot be resolved, the import will go to the reconciliation queue.

Addresses follow a separate rule:

• If originAddress.code or destinationAddress.code matches an existing Consignly address, that code is enough for address reconciliation.
• If an address code is not supplied, or does not resolve, the address can only auto-reconcile when the client partner settings allow address creation and the payload includes enough address data to create the record.

For address auto-creation, these settings apply:

• Allow consignee create controls destination address creation for outwards imports.
• Allow origin create controls origin address creation for inwards imports.
• Validate address enforces valid street address format before automatic address creation.
• Require address coordinates enforces valid latitude/longitude before automatic address creation.

For the full request schema and field-level rules, see the consignment import endpoint.

Reconciliation behaviour is configurable per client partner:

In practice, the minimum payload for predictable auto-reconciliation requires resolvable clientCode, warehouseCode, and products[].productCode values. Additionally, include address codes for any addresses that should match existing records, or provide the minimum required address components.

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 destinationAddress.code; this value must be the destination warehouse 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:

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:

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

Related

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