Endpoints related to Consignments.
Create Consignment
Create a new consignment.
path Parameters
tenantIdquery Parameters
applyDefaultsHeaders
Accept-VersionAll 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.
Create Consignment › Request Body
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).
Fields uniquely identifying Consignment
idBilling invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.
typeCustom 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.
statusIdentifies 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.
External Metadata by a specific External meta key
sourceReference to the task (e.g. outbound order) that generated this consignment
areChargesEditableisGrouperrorCounthasChildrencreateDateDate of creation
lastModifiedDate of last modification
eTagCreate Consignment › Responses
Created
idThe 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).
Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.
typeCustom 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
statusIdentifies 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.
External Metadata by a specific External meta key
sourceReference to the task (e.g. outbound order) that generated this consignment
areChargesEditableisGrouperrorCounthasChildrencreateDateDate of creation
lastModifiedDate of last modification
eTagGet consignment
Get a single consignment by ID.
Use Prefer: return=no-items to omit items from the response.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
consignmentIdThe consignment ID
Headers
Accept-VersionAll 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.
External-Meta-KeyThe 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.
Prefer| Value | Description |
|---|---|
| return=no-items | Omit items from the response. |
Get consignment › Responses
Consignment found. When Prefer: return=no-items is applied, items are omitted.
idThe 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).
Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.
typeCustom 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
statusIdentifies 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.
External Metadata by a specific External meta key
sourceReference to the task (e.g. outbound order) that generated this consignment
areChargesEditableisGrouperrorCounthasChildrencreateDateDate of creation
lastModifiedDate of last modification
eTagUpdate an existing 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.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
consignmentIdThe consignment ID
Headers
Accept-VersionAll 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.
External-Meta-KeyThe 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-MatchThe 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
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = array | |
| type = object |
List of patch operations following the JSON Patch specification. See RFC 6902 - JSON Patch for the official documentation. (add, replace, remove operations are supported)
Update an existing Consignment › Responses
Consignment updated successfully
idThe 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).
Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.
typeCustom 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
statusIdentifies 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.
External Metadata by a specific External meta key
sourceReference to the task (e.g. outbound order) that generated this consignment
areChargesEditableisGrouperrorCounthasChildrencreateDateDate of creation
lastModifiedDate of last modification
eTagGet carrier provider rates
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.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
consignmentIdHeaders
Accept-VersionAll 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.
Get carrier provider rates › Request Body optional
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.
Active providers with quoted rates or error status.
Additional details regarding the rates request or response.
selectedRateIdSet 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.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
consignmentIdUUID for the consignment.
query Parameters
forceWhen true, replaces charges even if they are already finalised.
Headers
Accept-VersionAll 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.
Set consignment charges › Request Body
idUUID for the persisted charge. Present in responses after charges are written.
Fee category for a consignment charge line.
descriptionA description of the charge.
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.
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
idUUID for the persisted charge. Present in responses after charges are written.
Fee category for a consignment charge line.
descriptionA description of the charge.
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.
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.
Retrieves paginated item confirmations for a specific consignment. Item confirmations represent proof of delivery confirmations for individual consignment items.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
consignmentIdThe consignment ID
query Parameters
pageThe page number to return results for
sizeThe number of elements per page. Default value may vary between endpoints
Headers
Accept-VersionAll 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.
Get item confirmations for a consignment. › Request Body
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = object · type="AndCondition" · requires: conditions | |
| type = object · type="OrCondition" · requires: conditions |
typeGet item confirmations for a consignment. › Responses
Success. Returns paginated item confirmations.
idtenantIdtaskIdThe consignment ID
methodConfirmation method
valueConfirmation value
schemaVersionconfirmedAtTimestamp when the confirmation was made
Download consignment labels.
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.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
Headers
Accept-VersionAll 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.
Download consignment labels. › Request Body
labelCountMap of consignment uuid to label count
returnTypeReturn type. url returns a URL to the generated labels; download returns raw PDF content.
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'').
urlURL to the generated labels
Print consignment labels.
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.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
Headers
Accept-VersionAll 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.
Print consignment labels. › Request Body
labelCountMap of consignment uuid to label count
Print consignment labels. › Responses
Quote consignment charges
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.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
Headers
Accept-VersionAll 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.
Quote consignment charges › Request Body
idThe 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).
Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.
typeCustom 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
statusIdentifies 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.
External Metadata by a specific External meta key
sourceReference to the task (e.g. outbound order) that generated this consignment
areChargesEditableisGrouperrorCounthasChildrencreateDateDate of creation
lastModifiedDate of last modification
eTagQuote consignment charges › Responses
Success. Charge description strings may include currency symbols formatted using the
consignment warehouse effective currency (see Money in common schemas).
Rate card used for the quote.
Rate matched for the quote.
List of produced charges.
Zone used for the collect address when quoting.
Zone used for the deliver address when quoting.
Service type used when matching the rate.
Search for consignments.
Search for consignments based on supported search criteria.
Condition Fields
Supported JsonField Conditions
| Pointer | Description |
|---|---|
/references/customer | Customer reference |
/references/tracking | Consignment tracking reference |
/customer/id | Customer ID |
/details/runsheet/id | Run sheet ID |
/details/runsheet/date | Run sheet date (from the consignment) |
/user/id | Driver ID (from the consignment) |
/details/deliveryRun/id | Delivery run ID (from the consignment) |
/generatedFromTask/id | Sale order ID that generated this consignment |
/details/type | Consignment type (e.g. DELIVERY, PICKUP) |
/items/references/barcode | Barcode on any consignment item or sub-item |
/items/references/label | Label 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.
path Parameters
tenantIdTenant ID. Can be found in organisation settings
Headers
Accept-VersionAll 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.
PreferWhen Prefer is applied, the Preference-Applied response header is returned.
| Value | Description |
|---|---|
| return=minimal | Switch the response into minimal representation (id only). |
Search for consignments. › Request Body
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
Decision Table
| Variant | Matching Criteria |
|---|---|
| type = array | |
| type = array |
idThe 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).
Billing invoice this entity is assigned to. Only present when the entity has an assigned invoice and the user has VIEW_CHARGES permission.
typeCustom 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
statusIdentifies 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.
External Metadata by a specific External meta key
sourceReference to the task (e.g. outbound order) that generated this consignment
areChargesEditableisGrouperrorCounthasChildrencreateDateDate of creation
lastModifiedDate of last modification
eTag