CartonCloud
CartonCloud API
CartonCloud API

Consignments

Endpoints related to Consignments.

Create Consignment

POST
https://api.cartoncloud.com
/tenants/{tenantId}/consignments
required permission: EDIT_CONSIGNMENT

Create a new consignment.

Create Consignment › path Parameters

tenantId
​UUID · uuid · required

Create Consignment › query Parameters

applyDefaults
​boolean

Create Consignment › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8

Create Consignment › Request Body

Request payload for creating a consignment.
ConsignmentCreateRequest
​CustomerReference · required

The customer that this entity is associated with. null for tenant data not associated with a specific customer. A user's access maybe restricted to specific customers. Also null for multi-customer groups. Pick To Tote as example (although each individual group member has its own customer reference).

​ConsignmentReferences · required

Fields uniquely identifying Consignment

id
​UUID · uuid
​object · readOnly

Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.

type
​string · enum
Enum values:
CONSIGNMENT
​object · readOnly

Carrier bill this consignment is assigned to. Only present when the consignment has an assigned bill and the caller has VIEW_CHARGES permission.

​Properties

Custom and other property values keyed by name.

Custom fields may exist or may be requested by the tenant.

  • For Address, Shipment, Container, Consignment Data, Consignment Item, Vehicle, Customer, Driver, Sale Order, Purchase Order, or Transport Product, use the name in Mapped Field from the tenant.
  • For Sale Order Product (SOP) custom fields, use sop_custom_field_1, sop_custom_field_2, and so on.
  • For other entities such as Purchase Order Product and Product, use custom_field_1, custom_field_2, and so on.
status
​ConsignmentStatus · enum
Enum values:
AWAITING_PICKUP
AWAITING_POINT_TO_POINT_PICKUP
AWAITING_SALE_ORDER_PACKING
AWAITING_DROPOFF
IN_TRANSIT_PICKUP_WAREHOUSE
IN_WAREHOUSE
WITH_ON_FORWARDER
IN_TRANSIT_WAREHOUSE_DELIVERY
Example: DELIVERED
​WarehouseReference

Identifies a warehouse. When both id and name are supplied, id is used first. name must match the warehouse name in CartonCloud exactly.

Identifies a user by id and display name.

​ExternalMeta

External Metadata by a specific External meta key

source
​ConsignmentSource · enum
Enum values:
EMAIL
FTP
API
WEB_UPLOAD
UNKNOWN
AUTOMATED_UNKNOWN_SOURCE
MANUAL_ADMIN
MANUAL_CUSTOMER
​TypedTaskReference · readOnly

Reference to the task (e.g. outbound order) that generated this consignment

​TaskLifecycleState
​object
areChargesEditable
​boolean
isGroup
​boolean
errorCount
​integer
hasChildren
​boolean
createDate
​string · date

Date of creation

lastModified
​string · date-time

Date of last modification

eTag
​string · readOnly

Create Consignment › Responses

Created

Common base properties shared by all task entity types (inbound orders, consignments, outbound orders, manifests).
Consignment
id
​UUID · uuid

The customer that this entity is associated with. null for tenant data not associated with a specific customer. A user's access maybe restricted to specific customers. Also null for multi-customer groups. Pick To Tote as example (although each individual group member has its own customer reference).

​object · readOnly

Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.

type
​string · enum
Enum values:
CONSIGNMENT
​object · readOnly

Carrier bill this consignment is assigned to. Only present when the consignment has an assigned bill and the caller has VIEW_CHARGES permission.

​Properties

Custom and other property values keyed by name.

Custom fields may exist or may be requested by the tenant.

  • For Address, Shipment, Container, Consignment Data, Consignment Item, Vehicle, Customer, Driver, Sale Order, Purchase Order, or Transport Product, use the name in Mapped Field from the tenant.
  • For Sale Order Product (SOP) custom fields, use sop_custom_field_1, sop_custom_field_2, and so on.
  • For other entities such as Purchase Order Product and Product, use custom_field_1, custom_field_2, and so on.

Fields uniquely identifying Consignment

status
​ConsignmentStatus · enum
Enum values:
AWAITING_PICKUP
AWAITING_POINT_TO_POINT_PICKUP
AWAITING_SALE_ORDER_PACKING
AWAITING_DROPOFF
IN_TRANSIT_PICKUP_WAREHOUSE
IN_WAREHOUSE
WITH_ON_FORWARDER
IN_TRANSIT_WAREHOUSE_DELIVERY
Example: DELIVERED
​WarehouseReference

Identifies a warehouse. When both id and name are supplied, id is used first. name must match the warehouse name in CartonCloud exactly.

Identifies a user by id and display name.

​ExternalMeta

External Metadata by a specific External meta key

source
​ConsignmentSource · enum
Enum values:
EMAIL
FTP
API
WEB_UPLOAD
UNKNOWN
AUTOMATED_UNKNOWN_SOURCE
MANUAL_ADMIN
MANUAL_CUSTOMER
​TypedTaskReference · readOnly

Reference to the task (e.g. outbound order) that generated this consignment

​TaskLifecycleState
​object
areChargesEditable
​boolean
isGroup
​boolean
errorCount
​integer
hasChildren
​boolean
createDate
​string · date

Date of creation

lastModified
​string · date-time

Date of last modification

eTag
​string · readOnly

Get consignment

GET
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/{consignmentId}
required permission: VIEW_CONSIGNMENT

Get a single consignment by ID.

Use Prefer: return=no-items to omit items from the response.

Get consignment › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

consignmentId
​UUID · uuid · required

The consignment ID

Example: 38756e85-d15c-45d9-84fd-1b3e50b73527

Get consignment › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8
External-Meta-Key
​string

The External-Meta-Key header allows to specify the desired external meta key and only data associated with the specified key will be returned. If no key is specified or the key does not contain data, then externalMeta will not be returned.

Users with VIEW_ALL_EXTERNAL_META permission can specify * to return all available external meta. Data in externalMeta will be keyed by the external meta key.

Include
​string[] · style: simple

Additional fields to include in the response. Use address.zones to return zones on addresses when provided. Income zones require the VIEW_CHARGES permission.

Enum values:
address.zones
Prefer
​string · enum
ValueDescription
return=no-itemsOmit items from the response.
Enum values:
return=no-items

Get consignment › Responses

Consignment found. When Prefer: return=no-items is applied, items are omitted.

Common base properties shared by all task entity types (inbound orders, consignments, outbound orders, manifests).
Consignment
id
​UUID · uuid

The customer that this entity is associated with. null for tenant data not associated with a specific customer. A user's access maybe restricted to specific customers. Also null for multi-customer groups. Pick To Tote as example (although each individual group member has its own customer reference).

​object · readOnly

Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.

type
​string · enum
Enum values:
CONSIGNMENT
​object · readOnly

Carrier bill this consignment is assigned to. Only present when the consignment has an assigned bill and the caller has VIEW_CHARGES permission.

​Properties

Custom and other property values keyed by name.

Custom fields may exist or may be requested by the tenant.

  • For Address, Shipment, Container, Consignment Data, Consignment Item, Vehicle, Customer, Driver, Sale Order, Purchase Order, or Transport Product, use the name in Mapped Field from the tenant.
  • For Sale Order Product (SOP) custom fields, use sop_custom_field_1, sop_custom_field_2, and so on.
  • For other entities such as Purchase Order Product and Product, use custom_field_1, custom_field_2, and so on.

Fields uniquely identifying Consignment

status
​ConsignmentStatus · enum
Enum values:
AWAITING_PICKUP
AWAITING_POINT_TO_POINT_PICKUP
AWAITING_SALE_ORDER_PACKING
AWAITING_DROPOFF
IN_TRANSIT_PICKUP_WAREHOUSE
IN_WAREHOUSE
WITH_ON_FORWARDER
IN_TRANSIT_WAREHOUSE_DELIVERY
Example: DELIVERED
​WarehouseReference

Identifies a warehouse. When both id and name are supplied, id is used first. name must match the warehouse name in CartonCloud exactly.

Identifies a user by id and display name.

​ExternalMeta

External Metadata by a specific External meta key

source
​ConsignmentSource · enum
Enum values:
EMAIL
FTP
API
WEB_UPLOAD
UNKNOWN
AUTOMATED_UNKNOWN_SOURCE
MANUAL_ADMIN
MANUAL_CUSTOMER
​TypedTaskReference · readOnly

Reference to the task (e.g. outbound order) that generated this consignment

​TaskLifecycleState
​object
areChargesEditable
​boolean
isGroup
​boolean
errorCount
​integer
hasChildren
​boolean
createDate
​string · date

Date of creation

lastModified
​string · date-time

Date of last modification

eTag
​string · readOnly

Update an existing Consignment

PATCH
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/{consignmentId}
required permission: EDIT_CONSIGNMENT

Supports JSON Merge Patch and JSON Patch request formats for consignment updates. Tracking fields can be updated via details.tracking.companyName, details.tracking.url, and references.tracking.

Update an existing Consignment › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

consignmentId
​UUID · uuid · required

The consignment ID

Example: 38756e85-d15c-45d9-84fd-1b3e50b73527

Update an existing Consignment › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8
External-Meta-Key
​string

The External-Meta-Key header allows to specify the desired external meta key and only data associated with the specified key will be returned. If no key is specified or the key does not contain data, then externalMeta will not be returned.

Users with VIEW_ALL_EXTERNAL_META permission can specify * to return all available external meta. Data in externalMeta will be keyed by the external meta key.

If-Match
​string

The If-Match header is used for optimistic concurrency control. It should contain the ETag value of the resource being updated. If the ETag doesn't match the current resource state, the request will be rejected.

Update an existing Consignment › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = array
type = object
Properties for JSON Patch (array of operations):

List of patch operations following the JSON Patch specification. See RFC 6902 - JSON Patch for the official documentation. (add, replace, remove operations are supported)

Individual patch operation entity following the JSON Patch specification. See [RFC 6902 - JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) for the official documentation.
PatchOperationEntity
op
​string · enum · required
Enum values:
add
replace
remove
path
​string · required
​

Update an existing Consignment › Responses

Consignment updated successfully

Common base properties shared by all task entity types (inbound orders, consignments, outbound orders, manifests).
Consignment
id
​UUID · uuid

The customer that this entity is associated with. null for tenant data not associated with a specific customer. A user's access maybe restricted to specific customers. Also null for multi-customer groups. Pick To Tote as example (although each individual group member has its own customer reference).

​object · readOnly

Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.

type
​string · enum
Enum values:
CONSIGNMENT
​object · readOnly

Carrier bill this consignment is assigned to. Only present when the consignment has an assigned bill and the caller has VIEW_CHARGES permission.

​Properties

Custom and other property values keyed by name.

Custom fields may exist or may be requested by the tenant.

  • For Address, Shipment, Container, Consignment Data, Consignment Item, Vehicle, Customer, Driver, Sale Order, Purchase Order, or Transport Product, use the name in Mapped Field from the tenant.
  • For Sale Order Product (SOP) custom fields, use sop_custom_field_1, sop_custom_field_2, and so on.
  • For other entities such as Purchase Order Product and Product, use custom_field_1, custom_field_2, and so on.

Fields uniquely identifying Consignment

status
​ConsignmentStatus · enum
Enum values:
AWAITING_PICKUP
AWAITING_POINT_TO_POINT_PICKUP
AWAITING_SALE_ORDER_PACKING
AWAITING_DROPOFF
IN_TRANSIT_PICKUP_WAREHOUSE
IN_WAREHOUSE
WITH_ON_FORWARDER
IN_TRANSIT_WAREHOUSE_DELIVERY
Example: DELIVERED
​WarehouseReference

Identifies a warehouse. When both id and name are supplied, id is used first. name must match the warehouse name in CartonCloud exactly.

Identifies a user by id and display name.

​ExternalMeta

External Metadata by a specific External meta key

source
​ConsignmentSource · enum
Enum values:
EMAIL
FTP
API
WEB_UPLOAD
UNKNOWN
AUTOMATED_UNKNOWN_SOURCE
MANUAL_ADMIN
MANUAL_CUSTOMER
​TypedTaskReference · readOnly

Reference to the task (e.g. outbound order) that generated this consignment

​TaskLifecycleState
​object
areChargesEditable
​boolean
isGroup
​boolean
errorCount
​integer
hasChildren
​boolean
createDate
​string · date

Date of creation

lastModified
​string · date-time

Date of last modification

eTag
​string · readOnly

Get carrier provider rates

POST
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/{consignmentId}/carrier-provider-rates
required permission: VIEW_CONSIGNMENT

Returns a list of all active carrier providers with quoted rates for the consignment, the identifier of the rate selected by the rules engine, and optional additional details.

Get carrier provider rates › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

consignmentId
​UUID · uuid · required

Get carrier provider rates › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8

Get carrier provider rates › Request Body optional

Optional body when requesting carrier provider rate quotes for a consignment. **`packedStock`** carries a client-side packed-stock snapshot (for example in-memory pack-screen stock moves). Omit the field to fall back to persisted stock; send **`[]`** for an explicit empty packed-stock snapshot.
ConsignmentCarrierProviderRatesRequest

Packed quantities per Transport Item on the consignment in the path. May be [].

Get carrier provider rates › Responses

Success. Returns providers with status SUCCESS (and rates) or ERROR (and error details), optional selected rate, and optional details.

Quoted carrier provider rates for a consignment, with optional details and selected rate.
ConsignmentCarrierProviderRatesResponse
​array · required

Active providers with quoted rates or error status.

Additional details regarding the rates request or response.

selectedRateId
​UUID · uuid

Set consignment charges

POST
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/{consignmentId}/charges
required permission: EDIT_CONSIGNMENT_CHARGES

Replaces charges on a consignment and marks them as finalised.

Rejects the request when the consignment invoice is already approved, or when charges are already finalised unless force=true is supplied.

Set consignment charges › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

consignmentId
​UUID · uuid · required

UUID for the consignment.

Example: 38756e85-d15c-45d9-84fd-1b3e50b73527

Set consignment charges › query Parameters

force
​boolean

When true, replaces charges even if they are already finalised.

Set consignment charges › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8

Set consignment charges › Request Body

A charge line when setting consignment charges.
ConsignmentChargeInput
id
​UUID · uuid · readOnly

UUID for the persisted charge. Present in responses after charges are written.

Example: 38756e85-d15c-45d9-84fd-1b3e50b73527

Fee category for a consignment charge line.

description
​string

A description of the charge.

​Money

Represents a monetary value with amount and currency. For most API fields, currency is the tenant organisation default currency (defaultCurrency on the tenant), unless the value is tied to a warehouse that has its own currency override configured. In that case, currency reflects the effective currency for that warehouse (warehouse override, otherwise organisation default). Some fields (for example outbound order invoiceValue) may accept or return an explicit currency code supplied by the client and are not limited to the organisation default alone.

​Money

The fee after any modifiers have been applied.

Charge modifiers (for example fuel levy). Usually omitted when setting charges manually.

Set consignment charges › Responses

Created

A charge line when setting consignment charges.
ConsignmentChargeInput
id
​UUID · uuid · readOnly

UUID for the persisted charge. Present in responses after charges are written.

Example: 38756e85-d15c-45d9-84fd-1b3e50b73527

Fee category for a consignment charge line.

description
​string

A description of the charge.

​Money

Represents a monetary value with amount and currency. For most API fields, currency is the tenant organisation default currency (defaultCurrency on the tenant), unless the value is tied to a warehouse that has its own currency override configured. In that case, currency reflects the effective currency for that warehouse (warehouse override, otherwise organisation default). Some fields (for example outbound order invoiceValue) may accept or return an explicit currency code supplied by the client and are not limited to the organisation default alone.

​Money

The fee after any modifiers have been applied.

Charge modifiers (for example fuel levy). Usually omitted when setting charges manually.

Get item confirmations for a consignment.

POST
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/{consignmentId}/item-confirmations
required permission: VIEW_CONSIGNMENT

Retrieves paginated item confirmations for a specific consignment. Item confirmations represent proof of delivery confirmations for individual consignment items.

Get item confirmations for a consignment. › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

consignmentId
​UUID · uuid · required

The consignment ID

Example: 38756e85-d15c-45d9-84fd-1b3e50b73527

Get item confirmations for a consignment. › query Parameters

page
​integer

The page number to return results for

size
​integer

The number of elements per page. Default value may vary between endpoints

Get item confirmations for a consignment. › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8

Get item confirmations for a consignment. › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · type="AndCondition" · requires: conditions
type = object · type="OrCondition" · requires: conditions
Properties for AndCondition:
type
​string · const · required
Const value: AndCondition
​Condition[] · required

Get item confirmations for a consignment. › Responses

Success. Returns paginated item confirmations.

ItemConfirmation
id
​UUID · uuid
tenantId
​UUID · uuid
​object
taskId
​UUID · uuid

The consignment ID

Example: 38756e85-d15c-45d9-84fd-1b3e50b73527
​object
method
​string · enum

Confirmation method

Enum values:
MANUAL
SCAN
value
​string

Confirmation value

schemaVersion
​integer
confirmedAt
​string · date-time

Timestamp when the confirmation was made

Download consignment labels.

POST
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/download-labels
required permission: VIEW_CONSIGNMENT_ITEM

Downloads labels for one or many consignments based on the provided payload. labelCount is a map of consignment uuid to label count. returnType defaults to download if not provided.

Download consignment labels. › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

Download consignment labels. › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8

Download consignment labels. › Request Body

DownloadLabels
labelCount
​object

Map of consignment uuid to label count

Example: {"38756e85-d15c-45d9-84fd-1b3e50b73527":2,"99d57338-1925-4a31-ac26-6703e8bc4107":53}
returnType
​string · enum

Return type. url returns a URL to the generated labels; download returns raw PDF content.

Enum values:
download
url
Default: download

Download consignment labels. › Responses

Success. Returns either a URL to the generated labels (if returnType is ''url''), or raw PDF content (if returnType is ''download'').

url
​string

URL to the generated labels

Print consignment labels.

POST
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/print-labels
required permission: TRANSPORT_PRINT_LABEL

Prints labels for one or many consignments based on the provided payload. labelCount is a map of consignment uuid to label count. Labels are sent to the tenant's configured label printers when present. With none configured, no print job is sent.

Print consignment labels. › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

Print consignment labels. › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8

Print consignment labels. › Request Body

PrintLabels
labelCount
​object

Map of consignment uuid to label count

Example: {"38756e85-d15c-45d9-84fd-1b3e50b73527":2,"99d57338-1925-4a31-ac26-6703e8bc4107":53}

Print consignment labels. › Responses

Success. Empty JSON array. Printer configuration does not change this body.

array · maxItems: 0

Quote consignment charges

POST
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/quote
required permission: EDIT_CONSIGNMENT

Get a quote for a consignment without persisting it.

Returns 422 Unprocessable Entity with error messages when no matching rate is found or charges cannot be produced. Common messages include:

  • No matching rate found. — review from/to zones, service type, and effective dates on the rate.
  • Warning, you may be undercharging your customers, please review the charges for this consignment. — a matching rate was found but produced no charges.
  • You may be under-charging this consignment please check all items have been entered correctly. — a matching rate was found but not all items produced a charge.

Quote consignment charges › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

Quote consignment charges › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8

Quote consignment charges › Request Body

Common base properties shared by all task entity types (inbound orders, consignments, outbound orders, manifests).
Consignment
id
​UUID · uuid

The customer that this entity is associated with. null for tenant data not associated with a specific customer. A user's access maybe restricted to specific customers. Also null for multi-customer groups. Pick To Tote as example (although each individual group member has its own customer reference).

​object · readOnly

Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.

type
​string · enum
Enum values:
CONSIGNMENT
​object · readOnly

Carrier bill this consignment is assigned to. Only present when the consignment has an assigned bill and the caller has VIEW_CHARGES permission.

​Properties

Custom and other property values keyed by name.

Custom fields may exist or may be requested by the tenant.

  • For Address, Shipment, Container, Consignment Data, Consignment Item, Vehicle, Customer, Driver, Sale Order, Purchase Order, or Transport Product, use the name in Mapped Field from the tenant.
  • For Sale Order Product (SOP) custom fields, use sop_custom_field_1, sop_custom_field_2, and so on.
  • For other entities such as Purchase Order Product and Product, use custom_field_1, custom_field_2, and so on.

Fields uniquely identifying Consignment

status
​ConsignmentStatus · enum
Enum values:
AWAITING_PICKUP
AWAITING_POINT_TO_POINT_PICKUP
AWAITING_SALE_ORDER_PACKING
AWAITING_DROPOFF
IN_TRANSIT_PICKUP_WAREHOUSE
IN_WAREHOUSE
WITH_ON_FORWARDER
IN_TRANSIT_WAREHOUSE_DELIVERY
Example: DELIVERED
​WarehouseReference

Identifies a warehouse. When both id and name are supplied, id is used first. name must match the warehouse name in CartonCloud exactly.

Identifies a user by id and display name.

​ExternalMeta

External Metadata by a specific External meta key

source
​ConsignmentSource · enum
Enum values:
EMAIL
FTP
API
WEB_UPLOAD
UNKNOWN
AUTOMATED_UNKNOWN_SOURCE
MANUAL_ADMIN
MANUAL_CUSTOMER
​TypedTaskReference · readOnly

Reference to the task (e.g. outbound order) that generated this consignment

​TaskLifecycleState
​object
areChargesEditable
​boolean
isGroup
​boolean
errorCount
​integer
hasChildren
​boolean
createDate
​string · date

Date of creation

lastModified
​string · date-time

Date of last modification

eTag
​string · readOnly

Quote consignment charges › Responses

Success. Charge description strings may include currency symbols formatted using the consignment warehouse effective currency (see Money in common schemas).

Quote for consignment charges, including matched rate card, rate, and produced charges.
ConsignmentQuoteResponse

Rate card used for the quote.

Rate matched for the quote.

List of produced charges.

​NamedReference

Zone used for the collect address when quoting.

​NamedReference

Zone used for the deliver address when quoting.

​NamedReference

Service type used when matching the rate.

Search for consignments.

POST
https://api.cartoncloud.com
/tenants/{tenantId}/consignments/search
required permission: VIEW_CONSIGNMENT

Search for consignments based on supported search criteria.

Condition Fields

Supported JsonField Conditions

PointerDescription
/references/customerCustomer reference
/references/trackingConsignment tracking reference
/customer/idCustomer ID
/details/runsheet/idRun sheet ID
/details/runsheet/dateRun sheet date (from the consignment)
/user/idDriver ID (from the consignment)
/details/deliveryRun/idDelivery run ID (from the consignment)
/generatedFromTask/idSale order ID that generated this consignment
/details/typeConsignment type (e.g. DELIVERY, PICKUP)
/items/references/barcodeBarcode on any consignment item or sub-item
/items/references/labelLabel reference on any consignment item or sub-item

For /items/references/barcode and /items/references/label, use TextComparisonCondition with method EQUAL_TO only. These fields match any consignment item (TRANSPORT_ITEM) or nested sub-item (TRANSPORT_SUB_ITEM); callers do not need to distinguish between those levels.

ValueField aliases (for example reference, customerId, customerName, runSheetStatus, driverName) remain supported but are deprecated for fields that have a JsonField pointer. Prefer JsonField pointers that match consignment-owned response fields. Related-entity display fields such as customer name and run sheet status remain ValueField-only.

Search for consignments. › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

Search for consignments. › Headers

Accept-Version
​string · enum · required

All API end points require Accept-Version in the request header.

Failure to provide the header will return a status code of 400, however, an invalid version can return a 404, 406 or 400.

Enum values:
8
Include
​string[] · style: simple

Additional fields to include in the response. Use address.zones to return zones on addresses when provided. Income zones require the VIEW_CHARGES permission.

Enum values:
address.zones
Prefer
​string · enum

When Prefer is applied, the Preference-Applied response header is returned.

ValueDescription
return=minimalSwitch the response into minimal representation (id only).
Enum values:
return=minimal

Search for consignments. › Request Body

Search request body. The condition tree is the value of `condition`. `condition.type` is `AndCondition` or `OrCondition`.
SearchRequest
​WrapperCondition · required

And and Or conditions must be accompanied with internal conditions property that provides all the fields level conditions that the wrapper must be applied to. Note: The FreeTextSearch condition cannot be combined with other fields level conditions.

Search for consignments. › Responses

Search results matching provided search criteria

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = array
type = array
Properties for Consignment list (Prefer omitted):
Common base properties shared by all task entity types (inbound orders, consignments, outbound orders, manifests).
Consignment
id
​UUID · uuid

The customer that this entity is associated with. null for tenant data not associated with a specific customer. A user's access maybe restricted to specific customers. Also null for multi-customer groups. Pick To Tote as example (although each individual group member has its own customer reference).

​object · readOnly

Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.

type
​string · enum
Enum values:
CONSIGNMENT
​object · readOnly

Carrier bill this consignment is assigned to. Only present when the consignment has an assigned bill and the caller has VIEW_CHARGES permission.

​Properties

Custom and other property values keyed by name.

Custom fields may exist or may be requested by the tenant.

  • For Address, Shipment, Container, Consignment Data, Consignment Item, Vehicle, Customer, Driver, Sale Order, Purchase Order, or Transport Product, use the name in Mapped Field from the tenant.
  • For Sale Order Product (SOP) custom fields, use sop_custom_field_1, sop_custom_field_2, and so on.
  • For other entities such as Purchase Order Product and Product, use custom_field_1, custom_field_2, and so on.

Fields uniquely identifying Consignment

status
​ConsignmentStatus · enum
Enum values:
AWAITING_PICKUP
AWAITING_POINT_TO_POINT_PICKUP
AWAITING_SALE_ORDER_PACKING
AWAITING_DROPOFF
IN_TRANSIT_PICKUP_WAREHOUSE
IN_WAREHOUSE
WITH_ON_FORWARDER
IN_TRANSIT_WAREHOUSE_DELIVERY
Example: DELIVERED
​WarehouseReference

Identifies a warehouse. When both id and name are supplied, id is used first. name must match the warehouse name in CartonCloud exactly.

Identifies a user by id and display name.

​ExternalMeta

External Metadata by a specific External meta key

source
​ConsignmentSource · enum
Enum values:
EMAIL
FTP
API
WEB_UPLOAD
UNKNOWN
AUTOMATED_UNKNOWN_SOURCE
MANUAL_ADMIN
MANUAL_CUSTOMER
​TypedTaskReference · readOnly

Reference to the task (e.g. outbound order) that generated this consignment

​TaskLifecycleState
​object
areChargesEditable
​boolean
isGroup
​boolean
errorCount
​integer
hasChildren
​boolean
createDate
​string · date

Date of creation

lastModified
​string · date-time

Date of last modification

eTag
​string · readOnly
Consignment ItemsCustomers