API Reference

Consignments

Consignments represent shipments of inventory, either inward (receiving inventory into a warehouse) or outward (dispatching inventory from a warehouse). This endpoint group provides comprehensive management of consignments including CRUD operations, status updates, and document generation.

Endpoints Overview

Method Endpoint Description
GET /v1/consignments Get a page of consignments
GET /v1/consignments/{consignmentId} Get consignment details
GET /v1/consignments/{consignmentId}/check-exists Check if consignment exists
PUT /v1/consignments/{consignmentId}/status Update consignment status
PUT /v1/consignments/{consignmentId}/priority Update consignment priority
PUT /v1/consignments/{consignmentId}/general Update general details
PUT /v1/consignments/{consignmentId}/route Update route details
PUT /v1/consignments/{consignmentId}/void Void a consignment
POST /v1/consignments/{consignmentId}/edi-detail Update EDI details
PUT /v1/consignments/{consignmentId}/connection-result Update connection result
GET /v1/consignments/{consignmentId}/product-information Get product information

Document Generation

Method Endpoint Description
GET /v1/consignments/{consignmentId}/detail-pdf Get consignment detail PDF
POST /v1/consignments/{consignmentId}/detail-pdf/print Print consignment detail PDF
GET /v1/consignments/{consignmentId}/detail-xlsx Get consignment detail XLSX
GET /v1/consignments/{consignmentId}/dispatch-confirmation-pdf Get dispatch confirmation PDF
POST /v1/consignments/{consignmentId}/dispatch-confirmation-pdf/print Print dispatch confirmation PDF
GET /v1/consignments/{consignmentId}/dispatch-confirmation-xlsx Get dispatch confirmation XLSX
GET /v1/consignments/{consignmentId}/receipt-confirmation-pdf Get receipt confirmation PDF
POST /v1/consignments/{consignmentId}/receipt-confirmation-pdf/print Print receipt confirmation PDF
GET /v1/consignments/{consignmentId}/receipt-confirmation-xlsx Get receipt confirmation XLSX
GET /v1/consignments/{consignmentId}/picking-list-pdf Get picking list PDF
POST /v1/consignments/{consignmentId}/picking-list-pdf/print Print picking list PDF
GET /v1/consignments/{consignmentId}/dg-declaration-pdf Get DG declaration PDF
POST /v1/consignments/{consignmentId}/dg-declaration-pdf/print Print DG declaration PDF

Get a Page of Consignments

Retrieve a paginated list of consignments with optional filters.

Endpoint: GET /v1/consignments

Query Parameters

Parameter Type Required Description
PageIndex integer No Page number (default: 1)
PageSize integer No Items per page (default: 25, max: 500)
SearchText string No Filter by consignment number, reference number, client name, or container number
ClientId uuid No Filter by client ID
CarrierId uuid No Filter by carrier ID
WarehouseId uuid No Filter by warehouse ID (origin or destination)
Status integer No Filter by consignment status
EdiStatus integer[] No Filter by EDI status (use null for unset)
ConsignmentNumbers string No Filter by consignment numbers (comma-separated, exact match)
ExternalId string No Filter by external ID

Consignment Status Values

Value Status Description
-2 Void Consignment has been voided
-1 Open Filter status for finding all non-void, non-closed consignments
0 Complete Consignment is complete
1 Pending Awaiting processing
2 ReadyToPick Ready for picking
3 ReadyToDispatch Ready to be dispatched
4 ReadyToReceive Ready to receive
5 InProgress Point-to-Point consignment currently being processed
6 Closed Consignment is closed
7 InTransit Currently in transit
8 Draft Draft consignment

Request Example 

curl -X GET "https://api.consignlyhq.com/v1/consignments?PageIndex=1&PageSize=25&Status=1&ClientId=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response Example 

{
  "index": 1,
  "total": 150,
  "consignments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "clientId": "550e8400-e29b-41d4-a716-446655440001",
      "clientName": "Example Client Ltd",
      "clientCode": "ECL",
      "carrierId": "550e8400-e29b-41d4-a716-446655440002",
      "carrierName": "Fast Freight Co",
      "carrierCode": "FFC",
      "carrierReferenceNumber": "FF-12345",
      "carrierRunNumber": "RUN-001",
      "carrierRunOrdinal": 1,
      "consignmentNumber": "CON-2024-001234",
      "referenceNumber": "PO-98765",
      "dateEntered": "2024-01-15",
      "type": 1,
      "status": 1,
      "warehouseId": "550e8400-e29b-41d4-a716-446655440003",
      "warehouseCode": "WH01",
      "warehouseName": "Main Warehouse",
      "ediStatus": 1
    }
  ]
}

Error Cases

Status Cause Resolution
400 Invalid query parameters Verify parameter formats and values
401 Invalid or expired token Refresh access token
403 Insufficient permissions Check API scopes

Get Consignment Details

Retrieve full details for a specific consignment.

Endpoint: GET /v1/consignments/{consignmentId}

Path Parameters

Parameter Type Required Description
consignmentId uuid Yes The consignment ID

Request Example 

curl -X GET "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response Example 

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "client": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "externalId": "CLI-001",
    "name": "Example Client Ltd",
    "code": "ECL",
    "email": "client@example.com",
    "relationship": 3,
    "status": 1
  },
  "type": 1,
  "status": 1,
  "isVoid": false,
  "consignmentNumber": "CON-2024-001234",
  "idempotencyKey": "unique-key-123",
  "externalId": "EXT-12345",
  "referenceNumber": "PO-98765",
  "dateEntered": "2024-01-15",
  "expectedArrivalDateTime": "2024-01-20T14:00:00Z",
  "expectedDispatchDateTime": "2024-01-18T09:00:00Z",
  "expectedDeliveryDateTime": "2024-01-20T16:00:00Z",
  "actualDispatchDateTime": null,
  "actualReceiveDateTime": null,
  "warehouse": {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "name": "Main Warehouse",
    "code": "WH01",
    "status": 1,
    "addressId": "550e8400-e29b-41d4-a716-446655444010",
    "latitude": -36.9082,
    "longitude": 174.8086,
    "timezoneId": "Pacific/Auckland"
  },
  "carrier": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "externalId": null,
    "name": "Fast Freight Co",
    "code": "FFC",
    "email": null,
    "relationship": 2,
    "status": 1
  },
  "carrierReferenceNumber": "FF-12345",
  "carrierRunNumber": "RUN-001",
  "carrierRunOrdinal": 1,
  "originAddress": {
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "type": 1,
    "name": "Main Warehouse",
    "code": "WH01",
    "email": null,
    "phone": null,
    "streetAddress": "123 Industrial Ave",
    "suburb": "Industrial Park",
    "city": "Auckland",
    "state": "Auckland",
    "postCode": "1010",
    "country": "New Zealand",
    "latitude": -36.9082,
    "longitude": 174.8086
  },
  "originAddressAttention": "Warehouse Manager",
  "destinationAddress": {
    "id": "550e8400-e29b-41d4-a716-446655440011",
    "type": 3,
    "name": "Customer Site",
    "code": null,
    "email": "customer@example.com",
    "phone": "+64 4 555 1234",
    "streetAddress": "456 Business St",
    "suburb": null,
    "city": "Wellington",
    "state": null,
    "postCode": "6011",
    "country": "New Zealand",
    "latitude": -41.2865,
    "longitude": 174.7762
  },
  "destinationAddressAttention": "Receiving Dept",
  "destinationAuthorityToLeave": false,
  "defaultDispatchWarehouseLocation": null,
  "defaultReceiveWarehouseLocation": null,
  "containerNumber": "MSKU1234567",
  "containerSealNumber": "SEAL001",
  "containerSize": 2,
  "containerType": 1,
  "containerTareWeightKG": 2200.0,
  "containerGrossWeightKG": 24000.0,
  "containerStatus": 1,
  "containerReceivedDate": null,
  "containerReturnedDate": null,
  "containerYard": null,
  "containerYardReference": null,
  "containerVesselName": "Ever Given",
  "containerVoyage": "VOY-2024-001",
  "dischargeShippingPort": {
    "id": "550e8400-e29b-41d4-a716-446655449400",
    "code": "NZAKL",
    "name": "Auckland",
    "country": "New Zealand"
  },
  "loadShippingPort": {
    "id": "550e8400-e29b-41d4-a716-446655449410",
    "code": "CNSHA",
    "name": "Shanghai",
    "country": "China"
  },
  "deliveryInstructions": "Leave at reception",
  "pickingInstructions": "Handle with care",
  "receiversReference": "REC-001",
  "sendersReference": "SEND-001",
  "poNumber": "PO-98765",
  "soNumber": "SO-54321",
  "sourceIntegrationType": 1,
  "ediStatus": 1,
  "metrics": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "type": 0,
      "unitType": null,
      "value": 500
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "type": 3,
      "unitType": "CTN",
      "value": 10
    }
  ],
  "consumables": [],
  "tasks": [],
  "notes": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440040",
      "note": "Urgent delivery required",
      "displayOnPrintOut": true,
      "attachmentCount": 0
    }
  ],
  "pods": [],
  "products": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440030",
      "description": "Product A - 500g",
      "partnerProduct": {
        "id": "550e8400-e29b-41d4-a716-446655440031",
        "code": "PROD-A",
        "name": "Product A",
        "volumeM3": 0.005,
        "weightKG": 0.5,
        "productGroupId": "550e8400-e29b-41d4-a716-446655440032",
        "productGroupName": "Grocery",
        "isDangerousGood": false,
        "barcode": "9401234567890",
        "gtin": null
      },
      "batch": "BATCH-001",
      "bestBeforeDate": "2025-06-01T00:00:00Z",
      "expiryDate": null,
      "packagingDate": "2024-01-10T00:00:00Z",
      "productionDate": "2024-01-08T00:00:00Z",
      "sellByDate": null,
      "quantity": 100,
      "volumeM3": 0.5,
      "weightKG": 500,
      "receivedQuantity": 0,
      "receivedVolumeM3": 0,
      "receivedWeightKG": 0,
      "receivedPercent": 0,
      "heldQuantity": 0,
      "heldVolumeM3": 0,
      "heldWeightKG": 0,
      "heldPercent": 0,
      "pickedQuantity": 0,
      "pickedVolumeM3": 0,
      "pickedWeightKG": 0,
      "pickedPercent": 0,
      "dispatchedQuantity": 0,
      "dispatchedVolumeM3": 0,
      "dispatchedWeightKG": 0,
      "dispatchedPercent": 0,
      "consignmentLogisticUnitId": null,
      "externalId": null,
      "attributes": [],
      "items": []
    }
  ],
  "logisticUnits": [],
  "serviceTypes": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440050",
      "code": "EXPRESS",
      "name": "Express Delivery"
    }
  ],
  "jobs": [],
  "consignmentTracking": []
}

Detail Response Fields

Field Type Description
id uuid Consignment ID
client object Client partner (PartnerHeaderModel)
type integer Consignment type (see values below)
status integer Consignment status
isVoid boolean Whether consignment is voided
consignmentNumber string Consignment number
idempotencyKey string Idempotency key
externalId string External system ID
referenceNumber string Reference number
dateEntered date Date entered into system
expectedArrivalDateTime datetime Expected arrival date/time
expectedDispatchDateTime datetime Expected dispatch date/time
expectedDeliveryDateTime datetime Expected delivery date/time
actualDispatchDateTime datetime Actual dispatch date/time
actualReceiveDateTime datetime Actual receive date/time
warehouse object Warehouse (WarehouseHeaderModel)
carrier object Carrier partner (PartnerHeaderModel)
carrierReferenceNumber string Carrier reference number
carrierRunNumber string Carrier run number
carrierRunOrdinal integer Carrier run order
originAddress object Origin address (AddressHeaderModel)
originAddressAttention string Origin address attention
destinationAddress object Destination address (AddressHeaderModel)
destinationAddressAttention string Destination address attention
destinationAuthorityToLeave boolean Authority to leave at destination
defaultDispatchWarehouseLocation object Default dispatch warehouse location
defaultReceiveWarehouseLocation object Default receive warehouse location
containerNumber string Container number
containerSealNumber string Container seal number
containerSize integer Container size (see values below)
containerType integer Container type (see values below)
containerTareWeightKG number Container tare weight in kg
containerGrossWeightKG number Container gross weight in kg
containerStatus integer Container status (see values below)
containerReceivedDate date Container received date
containerReturnedDate date Container returned date
containerYard object Container yard
containerYardReference string Container yard reference
containerVesselName string Container vessel name
containerVoyage string Container voyage
dischargeShippingPort object Discharge shipping port (ShippingPortHeaderModel)
loadShippingPort object Load shipping port (ShippingPortHeaderModel)
deliveryInstructions string Delivery instructions
pickingInstructions string Picking instructions
receiversReference string Receivers reference
sendersReference string Senders reference
poNumber string Purchase order number
soNumber string Sales order number
sourceIntegrationType integer Source integration type
ediStatus integer EDI status for current connection
metrics array Consignment metrics
consumables array Consignment consumables
tasks array Consignment tasks
notes array Consignment notes
pods array Proof of deliveries
products array Consignment products (includes partnerProduct as PartnerProductHeaderModel — see Partner Products for full field reference)
logisticUnits array Logistic units
serviceTypes array Service types
jobs array Associated jobs
consignmentTracking array Tracking records

Consignment Type Values

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

Container Size Values

Value Size
1 TenFoot
2 TwentyFoot
3 FortyFoot
4 FortyFiveFoot

Container Type Values

Value Type
1 GeneralPurpose
2 GeneralPurposeHighCube
3 Refrigerated
4 RefrigeratedHighCube
5 RefrigeratedNotOperating
6 RefrigeratedNotOperatingHighCube
7 OpenTop
8 OpenTopHighCube
9 FlatRack
10 FlatRackHighCube
11 Tank
12 TankHighCube

Container Status Values

Value Status
1 Pending
2 Received
3 Returned

Check if Consignment Exists

Check whether a consignment or consignment import exists.

Endpoint: GET /v1/consignments/{consignmentId}/check-exists

Path Parameters

Parameter Type Required Description
consignmentId uuid Yes The consignment ID to check

Request Example 

curl -X GET "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/check-exists" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response Status Codes

Status Meaning
201 Consignment exists
202 Consignment import exists (pending creation)
404 Not found

Response Example 

{
  "status": "Created",
  "description": "Consignment exists."
}

Update Consignment Status

Update the status of a consignment.

Endpoint: PUT /v1/consignments/{consignmentId}/status

Path Parameters

Parameter Type Required Description
consignmentId uuid Yes The consignment ID

Request Body 

{
  "status": 7,
  "inTransitDispatchDateTime": "2024-01-18T09:00:00Z",
  "closedTransactionDate": null
}
Field Type Required Description
status integer Yes New status value
inTransitDispatchDateTime datetime No Dispatch time (for InTransit status)
closedTransactionDate datetime No Close date (for Closed status)

Note: The inTransitDispatchDateTime and closedTransactionDate fields are optional. If omitted when transitioning to InTransit or Closed, the system will use the current timestamp.

Request Example 

curl -X PUT "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/status" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": 7,
    "inTransitDispatchDateTime": "2024-01-18T09:00:00Z"
  }'

Response

200 OK - Status updated successfully

Error Cases

Status Cause Resolution
400 Invalid status transition Check allowed status transitions
404 Consignment not found Verify consignment ID

Update Consignment Priority

Update the priority of a consignment.

Endpoint: PUT /v1/consignments/{consignmentId}/priority

Request Body 

{
  "priority": 2
}

Priority Values

Value Priority
2 Normal
3 High
4 Urgent

Request Example 

curl -X PUT "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/priority" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"priority": 3}'

Update General Details

Update general details of a consignment.

Endpoint: PUT /v1/consignments/{consignmentId}/general

Request Body 

{
  "referenceNumber": "PO-98765-UPDATED",
  "externalId": "EXT-12345",
  "dateEntered": "2024-01-15",
  "expectedArrivalDateTime": "2024-01-21T14:00:00Z",
  "expectedDispatchDateTime": "2024-01-19T09:00:00Z",
  "expectedDeliveryDateTime": "2024-01-21T16:00:00Z",
  "actualDispatchDateTime": "2024-01-19T09:30:00Z",
  "actualReceiveDateTime": null,
  "pickingInstructions": "Updated picking instructions",
  "receiversReference": "REC-001",
  "sendersReference": "SEND-001",
  "poNumber": "PO-98765",
  "soNumber": "SO-54321"
}

Response

Status Description
200 Updated successfully
304 Not modified (no changes)

Update Route Details

Update route and delivery information.

Endpoint: PUT /v1/consignments/{consignmentId}/route

Request Body 

{
  "carrierId": "550e8400-e29b-41d4-a716-446655440002",
  "carrierReferenceNumber": "FF-12345",
  "carrierRunNumber": "RUN-001",
  "carrierRunOrdinal": 1,
  "originAddressId": "550e8400-e29b-41d4-a716-446655440010",
  "originAttention": "Warehouse Manager",
  "destinationAddressId": "550e8400-e29b-41d4-a716-446655440011",
  "destinationAttention": "Receiving Dept",
  "destinationAuthorityToLeave": true,
  "defaultDispatchWarehouseLocationId": "550e8400-e29b-41d4-a716-446655440012",
  "defaultReceiveWarehouseLocationId": "550e8400-e29b-41d4-a716-446655440013",
  "deliveryInstructions": "Leave at loading dock"
}

Void a Consignment

Mark a consignment as void.

Endpoint: PUT /v1/consignments/{consignmentId}/void

Request Example 

curl -X PUT "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/void" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response

200 OK - Consignment voided successfully

Update EDI Details

Create or update external EDI details for a consignment.

Endpoint: POST /v1/consignments/{consignmentId}/edi-detail

Request Body 

{
  "ediStatus": 1
}

Request Example 

curl -X POST "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/edi-detail" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ediStatus": 1}'

Note: The ediStatus field is specific to the calling API connection. It will not reflect status updates made by other connections.

Update Connection Result

Update the connection action status after processing a webhook export.

Endpoint: PUT /v1/consignments/{consignmentId}/connection-result

Request Body 

{
  "operationId": "EKm9H7omU69Aq5CYOebq1bjVqCDH7p-2T57Ce5X1MqPg9WdlBDzV90iJmKURkpHE2g",
  "result": 1,
  "errorMessage": null
}
Field Type Required Description
operationId string Yes Operation ID from export webhook
result integer Yes 1 = Success, 2 = Failed
errorMessage string No Error message if failed

Deferred Execution: Some actions triggered from Consignly (e.g., exporting to a third-party system when a consignment changes status) can be sent in a deferred state. In this scenario, the export remains in an "Executing" state until a connectionResult is sent marking it as Complete (1) or Failed (2).

Get Consignment Detail PDF

Generate a PDF document with consignment details.

Endpoint: GET /v1/consignments/{consignmentId}/detail-pdf

Query Parameters

Parameter Type Default Description
Orientation integer 0 (Portrait) 0 = Portrait, 1 = Landscape
IncludeShipping boolean true Include shipping information
IncludeMetrics boolean true Include metrics
IncludeNotes boolean true Include notes
IncludePods boolean true Include proof of delivery info
IncludeProductSummary boolean false Include product summary
PrintOption.PrinterId uuid null Printer ID for direct printing

Request Example 

curl -X GET "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/detail-pdf?Orientation=0&IncludeMetrics=true" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  --output consignment-detail.pdf

Print Consignment Detail PDF

Send a consignment detail PDF directly to a printer.

Endpoint: POST /v1/consignments/{consignmentId}/detail-pdf/print

Request Body 

{
  "orientation": 0,
  "includeShipping": true,
  "includeMetrics": true,
  "includeNotes": true,
  "includePods": true,
  "includeProductSummary": false,
  "printOption": {
    "printerId": "550e8400-e29b-41d4-a716-446655440099"
  }
}

Response 

{
  "printJobId": "550e8400-e29b-41d4-a716-446655440099"
}
Field Type Description
printJobId uuid Print job ID to track print job details

Get Product Information

Retrieve detailed product and transaction information for a consignment.

Endpoint: GET /v1/consignments/{consignmentId}/product-information

Request Example 

curl -X GET "https://api.consignlyhq.com/v1/consignments/550e8400-e29b-41d4-a716-446655440000/product-information" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response Example 

{
  "consignmentProducts": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440030",
      "transactions": [
        {
          "type": 1,
          "dateUtc": "2024-01-18T09:00:00Z",
          "inventoryReceiptId": "550e8400-e29b-41d4-a716-446655440060",
          "receivedDate": "2024-01-18",
          "receivedUtc": "2024-01-18T09:00:00Z",
          "quantity": 50,
          "volumeM3": 0.25,
          "weightKG": 25
        }
      ],
      "conversions": [
        {
          "metricResolution": 1,
          "metricResolutionName": "Unit",
          "metrics": [
            {
              "metricType": 1,
              "unitType": "Each",
              "unitTypeId": "550e8400-e29b-41d4-a716-446655440070",
              "value": 100
            }
          ]
        }
      ]
    }
  ]
}

Related Endpoints

Previous
Webhooks
Next
Consignment Charges