Consignment Import

The Consignment Imports endpoint enables the creation of new consignments by submitting import data. This is the primary method for programmatically creating consignments in Consignly.

Endpoints Overview

Create Consignment Import

A new consignment is created by submitting import data. The import is processed asynchronously and results in a consignment when successful.

Endpoint: POST /v1/consignment-imports

Authentication

Requires Bearer token authentication.

Request Body

{
  "idempotencyKey": "unique-import-key-12345",
  "consignmentType": 1,
  "clientCode": "ECL",
  "referenceNumber": "PO-98765",
  "externalId": "EXT-12345",
  "carrierCode": "FFC",
  "carrierReference": "FF-12345",
  "enteredDate": "2024-01-15T00:00:00Z",
  "expectedArrivalDateTime": "2024-01-20T14:00:00Z",
  "expectedDispatchDateTime": "2024-01-18T09:00:00Z",
  "expectedDeliveryDateTime": "2024-01-20T16:00:00Z",
  "warehouseCode": "WH01",
  "originAddress": {
    "code": "ORIG-001",
    "name": "Supplier Warehouse",
    "email": "supplier@example.com",
    "phone": "+64 9 123 4567",
    "streetAddress": "123 Supplier Road",
    "suburb": "Industrial Park",
    "city": "Auckland",
    "state": "Auckland",
    "postCode": "1010",
    "country": "New Zealand",
    "latitude": -36.8485,
    "longitude": 174.7633
  },
  "originAddressAttention": "Dispatch Manager",
  "destinationAddress": {
    "code": "DEST-001",
    "name": "Customer Site",
    "email": "customer@example.com",
    "phone": "+64 4 987 6543",
    "streetAddress": "456 Business Street",
    "suburb": "CBD",
    "city": "Wellington",
    "state": "Wellington",
    "postCode": "6011",
    "country": "New Zealand"
  },
  "destinationAddressAttention": "Receiving Dept",
  "destinationAuthorityToLeave": false,
  "deliveryInstructions": "Deliver to loading dock B",
  "pickingInstructions": "Handle with care - fragile items",
  "receiversReference": "REC-001",
  "sendersReference": "SEND-001",
  "poNumber": "PO-98765",
  "soNumber": "SO-54321",
  "containerNumber": "MSKU1234567",
  "containerSealNumber": "SEAL001",
  "containerSize": 3,
  "containerType": 1,
  "containerTareWeightKG": 2300,
  "containerGrossWeightKG": 15000,
  "containerYardCode": "CY001",
  "containerYardReference": "CY-REF-001",
  "containerVesselName": "MV Pacific Star",
  "containerVoyage": "VOY-2024-001",
  "loadShippingPortCode": "CNSHA",
  "dischargeShippingPortCode": "NZAKL",
  "serviceTypeCodes": ["B2B", "PALLET-DEVAN"],
  "notes": [
    {
      "note": "Priority customer - handle with care",
      "displayOnPrintOut": true,
      "attachments": [
        {
          "fileName": "packing-list.pdf",
          "contentType": "application/pdf",
          "content": "base64-encoded-content-here"
        }
      ]
    }
  ],
  "products": [
    {
      "productCode": "PROD-A",
      "goodsDescription": "Product A - Premium Grade",
      "batch": "BATCH-2024-001",
      "bestBeforeDate": "2025-06-30T00:00:00Z",
      "expiryDate": "2025-12-31T00:00:00Z",
      "packagingDate": "2024-01-10T00:00:00Z",
      "productionDate": "2024-01-05T00:00:00Z",
      "sellByDate": "2025-03-31T00:00:00Z",
      "logisticUnitSsccNumber": "123456789012345678",
      "logisticUnitReferenceNumber": "LU-REF-001",
      "isManualReconciliationRequired": false,
      "criticalStockStatus": 2,
      "attributes": [
        {
          "name": "Color",
          "description": "Blue"
        },
        {
          "name": "Size",
          "description": "Large"
        }
      ],
      "items": [
        {
          "quantity": 100,
          "weightKG": 500,
          "volumeM3": 2.5
        }
      ]
    }
  ]
}

Request Body Fields

Root Level Fields

Auto-Reconciliation Required Fields

For imports expected to auto-reconcile without manual intervention, these identifiers are required and must match existing records in Consignly.

Consignment Type Values

Address Object

Address reconciliation follows this order:

1. If code is provided, Consignly checks code match first.
2. If code is missing or does not resolve, Consignly attempts component-based address matching.
3. If no existing address is matched, Consignly can create a new address when client partner settings allow it and required fields are present.

Address creation from import data is controlled by client partner settings:

• Allow consignee create applies to destinationAddress on outwards imports.
• Allow origin create applies to originAddress on inwards imports.
• Validate address requires a valid street address format to match/create.
• Require address coordinates requires valid latitude/longitude before auto-create will run.

For the most predictable imports, use originAddress.code and destinationAddress.code whenever those addresses already exist in Consignly.

For Consignly Connect warehouse transfers, destinationAddress.code must be the destination warehouse code. See Consignment Import fundamentals.

Minimum fields for new address creation:

• name
• streetAddress
• city
• postCode
• country
• state when applicable for the country or region

Container Fields

For containerised consignments, containerNumber, containerSize, and containerType are required.

Container Size Values

Container Type Values

Product Object

Critical Stock Status Values

Product Attribute Object

Product Item Object

Items Array Usage

Non-serialised products:

• Use a single item object with the total quantity

Serialised products depend on the product's serial capture mode (configured per organisation/product):

Full-capture serials:

• Inwards:
  • Supply serials if known
  • If serials are unknown, the import may still process, but serials must be supplied before receiving can be completed
• Outwards:
  • Supply serials if specific units must be picked/dispatched
  • If any serial will do, omit serials and provide only the quantity — Consignly will allocate serials during picking

Release-capture serials:

• Inwards and Outwards:
  • Do not supply serials in the import payload
  • Serials are captured by the warehouse team at time of pick

Important: Only when specifying serials should item.quantity be 1 per item object. Otherwise, use a single item with the total quantity.

Note Object

Note Attachment Object

Understanding Logistic Units in Imports

Logistic unit data is provided at the product line level, not as separate objects. This allows multiple product lines to reference the same or different logistic units.

How Logistic Units Work

• Inwards consignments: Product/item data is received into the warehouse on the logistic unit specified by logisticUnitSsccNumber and logisticUnitReferenceNumber
• Outwards consignments: The product line is tagged as requesting inventory from the specified logistic unit

Example: Multiple Products on Same Logistic Unit

{
  "consignmentType": 1,
  "clientCode": "ECL",
  "products": [
    {
      "productCode": "PROD-A",
      "batch": "BATCH-001",
      "logisticUnitSsccNumber": "123456789012345678",
      "items": [{ "quantity": 50, "weightKG": 250 }]
    },
    {
      "productCode": "PROD-B",
      "batch": "BATCH-002",
      "logisticUnitSsccNumber": "123456789012345678",
      "items": [{ "quantity": 30, "weightKG": 150 }]
    }
  ]
}

Both products reference the same SSCC number, so they will be associated with the same logistic unit.

Request Examples

Minimal Request

{
  "consignmentType": 1,
  "clientCode": "ECL",
  "products": [
    {
      "productCode": "PROD-A",
      "items": [{ "quantity": 100 }]
    }
  ]
}

Serialised Products (Full-Capture with Known Serials)

When importing serialised products where serials are known and must be specified, provide each serial number as a separate item with quantity: 1:

{
  "consignmentType": 1,
  "clientCode": "ECL",
  "products": [
    {
      "productCode": "SERIAL-PROD",
      "batch": "BATCH-001",
      "items": [
        { "serial": "SN-001", "quantity": 1 },
        { "serial": "SN-002", "quantity": 1 },
        { "serial": "SN-003", "quantity": 1 }
      ]
    }
  ]
}

Serialised Products (Quantity Only)

For full-capture serialised products on Outwards consignments where any available serial will do, or for release-capture products, simply specify the quantity:

{
  "consignmentType": 2,
  "clientCode": "ECL",
  "products": [
    {
      "productCode": "SERIAL-PROD",
      "batch": "BATCH-001",
      "items": [{ "quantity": 3 }]
    }
  ]
}

Request Example (cURL)

curl -X POST "https://api.consignlyhq.com/v1/consignment-imports" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "unique-import-12345",
    "consignmentType": 1,
    "clientCode": "ECL",
    "referenceNumber": "PO-98765",
    "warehouseCode": "WH01",
    "products": [
      {
        "productCode": "PROD-A",
        "batch": "BATCH-001",
        "items": [{ "quantity": 100, "weightKG": 500 }]
      }
    ]
  }'

Response

Status: 202 Accepted

{
  "consignmentId": "550e8400-e29b-41d4-a716-446655440100"
}

Idempotency

The idempotencyKey field prevents duplicate consignment creation:

• When submitting an import with an idempotency key that has already been used, the request will be rejected with a 409 Conflict status
• Use idempotency keys when retrying failed requests to prevent duplicates
• Keys should be unique per logical import operation
• Maximum length: 200 characters

Processing Flow

1. Import is validated and accepted (returns 202)
2. Import is processed asynchronously
3. Consignment is created when processing completes
4. Use GET /v1/consignments/{consignmentId}/check-exists to check status:
   • 201: Consignment created successfully
   • 202: Import still being processed
   • 404: Import/consignment not found

Import Processing and Reconciliation

Consignment imports are processed asynchronously with a reconciliation workflow for unresolved references:

1. Initial Validation: The API validates the basic request structure and returns 202 Accepted
2. Background Processing: The import is queued for background processing
3. Reference Resolution: The system attempts to resolve all reference codes (product, client, warehouse, carrier)
4. Reconciliation Queue: If any references cannot be resolved, the import is placed in a reconciliation queue rather than failing outright
5. Manual Reconciliation: Imports in the reconciliation queue require manual resolution in the Consignly portal

Important: Invalid reference codes (product codes, client codes, warehouse codes, carrier codes) do not cause immediate API validation errors. Instead, they result in imports requiring manual reconciliation. Always verify the reference codes are correctly configured in Consignly before submitting imports.

Notes and Gotchas

SSCC Validation

SSCC numbers must be valid 18-digit Serial Shipping Container Codes including the check digit. The logisticUnitReferenceNumber can also be used to uniquely identify each logistic unit without adhering to the SSCC standard.

Container Field Requirements

For containerised consignments, containerNumber, containerType, and containerSize are required and must be specified together as a set.

For non-containerised consignments, omit all three fields.

If only some of these fields are supplied:

• The import will be accepted (valid JSON)
• But the import cannot be processed and will remain unreconciled/pending until corrected

Gotcha: Always provide all three container identification fields together, or omit them entirely.

Automatic vs Manual Reconciliation

Consignly will accept properly formed JSON for processing. Depending on the organisation's settings and whether the payload can be reconciled against existing Consignly data:

• The import may be automatically processed and create a consignment immediately
• Or it may be held in the Pending Import queue for manual reconciliation

Common reasons an import may require manual reconciliation:

• Product code does not exist for the specified client
• Carrier code cannot be matched to an existing carrier partner
• Warehouse code is not recognized
• Other referenced codes/entities cannot be resolved

Address Match and Auto-Creation

For addresses, imports follow this sequence:

• Try code match first when code is provided.
• If code is missing or unresolved, try component-based matching.
• If still unmatched, create a new address only when relevant client settings allow it and required fields are supplied (name, streetAddress, city, country, postCode, and state where applicable).

Manual Reconciliation Flag

Setting isManualReconciliationRequired: true on a product line will:

• Flag the import as requiring manual intervention
• Highlight the specific line(s) that require review in the Consignly portal

This is useful for verification before stock is received or allocated.

Critical Stock Status for Outwards

For Outwards consignments, the criticalStockStatus field may be omitted when there is no preference for critical or non-critical stock during inventory allocation. If specified:

• 1 (CriticalStock) - Prefer allocating from critical stock
• 2 (NonCriticalStock) - Prefer allocating from non-critical stock

Error Cases

Related Endpoints

• Consignments - Manage created consignments
• Partners - Look up client and carrier codes
• Partner Products - Look up product codes
• Warehouses - Look up warehouse codes