CartonCloud
CartonCloud API
CartonCloud API

Outbound Orders (Sale Orders)

Endpoints related to Outbound Orders.

Run an action on an outbound order

POST
https://api.cartoncloud.com
/tenants/{tenantId}/activities/{taskId}/actions
required permission: EDIT_OUTBOUND_ORDER_ACTION

Runs an action on an outbound order. Set the activityType query parameter to OUTBOUND.

The action is the request body. type selects the action, for example ASSIGN or START. The response returns the updated outbound order.

Requires EDIT_OUTBOUND_ORDER_ACTION. Outbound actions change the order lifecycle.

Run an action on an outbound order › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

taskId
​string · uuid · required

Outbound order id the action runs against.

Run an action on an outbound order › query Parameters

activityType
​string · required

Selects which actions this call can run.

Run an action on an outbound order › 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

Run an action on an outbound order › Request Body

oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object
Properties for OutboundActions (OUTBOUND):
oneOf
Exactly one variant must match.

Decision Table

VariantMatching Criteria
type = object · requires: type
type = object · requires: type
type = object · requires: type
type = object · requires: type
type = object · requires: type
type = object · requires: type
type = object · requires: type, details
type = object · requires: type
type = object · requires: type
type = object · requires: type
type = object · requires: type
Properties for AssignAction:
Action to assign a user to a task
AssignAction
type
​string · enum · required
Enum values:
ASSIGN
​object

Run an action on an outbound order › Responses

Updated outbound order, plus references to any related records the action changed.

Object returned in response of any successful action call
​

Add Outbound order

POST
https://api.cartoncloud.com
/tenants/{tenantId}/outbound-orders
required permission: EDIT_OUTBOUND_ORDER

Create a new outbound order (sale order).

This endpoint is rate limited to 30 requests per minute per user (no more than 1 request every 2 seconds).

Add Outbound order › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

Add Outbound order › 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.

Add Outbound order › Request Body

Request payload for creating an Outbound Order
OutboundOrderRequest
​object · required

Fields uniquely identifying Outbound order

​CustomerReference · required

Identifies a customer. When more than one identifying property is supplied, they are checked in this order: id, references.code, then name.

type
​string · enum
Enum values:
OUTBOUND
Default: OUTBOUND
​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.
measures
​object
status
​OutboundStatus · enum
Enum values:
DRAFT
AWAITING_STOCK
AWAITING_PICK_AND_PACK
PACKING_IN_PROGRESS
PICKED
PACKED
DISPATCHED
REJECTED
Example: PACKING_IN_PROGRESS
​WarehouseReference

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

​ExternalMeta

External Metadata by a specific External meta key

source
​Source

Source information for the entity

​TaskReference

Reference to the Parent Order that this Outbound Order belongs to. Parent Orders are not yet implemented and are only stored as UUIDs.

Details specific for the Outbound Task object

Add Outbound order › Responses

Order successfully added

Default Representation of Outbound object
OutboundOrder_Default
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:
OUTBOUND
Default: OUTBOUND

Fields uniquely identifying Outbound order

​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.

Contains information about size of the order.

status
​OutboundStatus · enum
Enum values:
DRAFT
AWAITING_STOCK
AWAITING_PICK_AND_PACK
PACKING_IN_PROGRESS
PICKED
PACKED
DISPATCHED
REJECTED
Example: PACKING_IN_PROGRESS
​WarehouseReference

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

version
​integer
​ExternalMeta

External Metadata by a specific External meta key

source
​Source

Source information for the entity

​object

Map of timestamp entries for various lifecycle events

​TaskReference

Reference to the Parent Order that this Outbound Order belongs to. Parent Orders are not yet implemented and are only stored as UUIDs.

Details specific for the Outbound Task object

Queue an outbound order

POST
https://api.cartoncloud.com
/tenants/{tenantId}/outbound-orders/queue-add
required permission: EDIT_OUTBOUND_ORDER

Validates the outbound order and queues a background job to create it.

A successful request returns 202 Accepted with a confirmation message. The order is created by the job, not in this response.

Queue an outbound order › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

Queue an outbound order › query Parameters

createRejected
​boolean

Defaults to true. When true, an item product that cannot be resolved does not fail this request. When false, that product check returns 422 and the order is not queued.

Default: true

Queue an outbound order › 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.

Queue an outbound order › Request Body

Request payload for creating an Outbound Order
OutboundOrderRequest
​object · required

Fields uniquely identifying Outbound order

​CustomerReference · required

Identifies a customer. When more than one identifying property is supplied, they are checked in this order: id, references.code, then name.

type
​string · enum
Enum values:
OUTBOUND
Default: OUTBOUND
​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.
measures
​object
status
​OutboundStatus · enum
Enum values:
DRAFT
AWAITING_STOCK
AWAITING_PICK_AND_PACK
PACKING_IN_PROGRESS
PICKED
PACKED
DISPATCHED
REJECTED
Example: PACKING_IN_PROGRESS
​WarehouseReference

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

​ExternalMeta

External Metadata by a specific External meta key

source
​Source

Source information for the entity

​TaskReference

Reference to the Parent Order that this Outbound Order belongs to. Parent Orders are not yet implemented and are only stored as UUIDs.

Details specific for the Outbound Task object

Queue an outbound order › Responses

Accepted

message
​string

Search Outbound Orders

POST
https://api.cartoncloud.com
/tenants/{tenantId}/outbound-orders/search
required permission: VIEW_OUTBOUND_ORDER

Search for previously created outbound orders (sale order).

Condition Fields

Prefer JsonField pointers. ValueField aliases remain supported but are deprecated where a JsonField pointer exists.

Custom property pointers (/properties/{name}) may also be searchable. /invoice/id is available when the caller has VIEW_CHARGES, or Hide charging information is off.

Supported JsonField pointers

PointerDescription
/assignee/idAssignee ID
/assignee/task/idWave pick / assignee task ID
/customer/idCustomer ID
/customer/nameCustomer name
/details/collect/requiredDateRequired collection date
/details/deliver/address/address1Delivery address line 1
/details/deliver/address/cityDelivery address city
/details/deliver/address/companyNameDelivery address company name
/details/deliver/address/contactNameDelivery address contact name
/details/deliver/address/postcodeDelivery address postcode
/details/deliver/address/suburbDelivery address suburb
/details/expectedShipDateExpected ship date
/details/tote/references/barcodeTote barcode
/details/urgentIs urgent order
/group/idPick To Tote task id (not the order group for split orders)
/idOrder ID
/references/customerCustomer reference
/references/numericIdNumeric ID
/statusStatus enum (e.g. DRAFT)
/timestamps/created/timeCreated (ISO 8601)
/timestamps/dispatched/timeDispatched (ISO 8601)
/timestamps/modified/timeModified (ISO 8601)
/timestamps/packed/timePacked (ISO 8601)
/warehouse/idWarehouse ID

ValueField aliases (deprecated)

ValueFieldJsonField pointer
createdDate/timestamps/created/time
customerId/customer/id
customerName/customer/name
reference/references/customer
references.numericId/references/numericId

Search Outbound Orders › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

Search Outbound Orders › 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

sort
​string

Field name and sort order separated by a comma. {dot separated field name},{asc/desc}

nullHandling
​string · enum
Enum values:
NULLS_FIRST
NULLS_LAST

Search Outbound Orders › 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
Prefer
​string · enum

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

ValueDescription
return=minimalSwitch the response into minimal representation (id only).
return=lifecycleSwitch the response into lifecycle representation.
return=search-representationSwitch the response into search representation.
Enum values:
return=lifecycle
return=minimal
return=search-representation

Search Outbound Orders › 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 Outbound Orders › Responses

Success

anyOf
At least one variant must match. Multiple variants may match simultaneously.

Decision Table

VariantMatching Criteria
type = array
type = array
type = array
type = array
Properties for OutboundOrder_Lifecycle list (Prefer: return=lifecycle):
Representation of Outbound object when Prefer:return=lifecycle request header is provided
OutboundOrder_Lifecycle
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:
OUTBOUND
Default: OUTBOUND

Fields uniquely identifying Outbound order

​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.

Contains information about size of the order.

status
​OutboundStatus · enum
Enum values:
DRAFT
AWAITING_STOCK
AWAITING_PICK_AND_PACK
PACKING_IN_PROGRESS
PICKED
PACKED
DISPATCHED
REJECTED
Example: PACKING_IN_PROGRESS
​WarehouseReference

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

version
​integer
​ExternalMeta

External Metadata by a specific External meta key

source
​Source

Source information for the entity

​object

Map of timestamp entries for various lifecycle events

If Outbound is part of Pick To Tote task, it's reference will be provided here

Details specific for the Outbound Task object

​LifecycleReference
​OutboundLifecycleState
​TypedTaskReference[]

View Outbound Order

GET
https://api.cartoncloud.com
/tenants/{tenantId}/outbound-orders/{orderId}
required permission: VIEW_OUTBOUND_ORDER

Retrieves a previously created outbound order (sale order).

View Outbound Order › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

orderId
​string · uuid · required

Outbound Order Id

Example: 41597723-b4fb-443f-bc98-5457783d97f0

View Outbound Order › 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
Prefer
​string · enum

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

ValueDescription
return=minimalSwitch the response into minimal representation (id only).
return=lifecycleSwitch the response into lifecycle representation.
return=search-representationSwitch the response into search representation.
Enum values:
return=lifecycle
return=minimal
return=search-representation
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.

View Outbound Order › Responses

Success. Response body depends on the Prefer request header (see parameter outboundPreferHeader): - Prefer: return=search-representation → OutboundOrder_SearchResult - Prefer: return=lifecycle → OutboundOrder_Lifecycle - Prefer: return=minimal → OutboundOrder_Reference - Prefer header omitted → OutboundOrder_Default

anyOf
At least one variant must match. Multiple variants may match simultaneously.

Decision Table

VariantMatching Criteria
type = object
type = object
type = object
type = object
Properties for OutboundOrder_Lifecycle (Prefer: return=lifecycle):
Representation of Outbound object when Prefer:return=lifecycle request header is provided
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:
OUTBOUND
Default: OUTBOUND

Fields uniquely identifying Outbound order

​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.

Contains information about size of the order.

status
​OutboundStatus · enum
Enum values:
DRAFT
AWAITING_STOCK
AWAITING_PICK_AND_PACK
PACKING_IN_PROGRESS
PICKED
PACKED
DISPATCHED
REJECTED
Example: PACKING_IN_PROGRESS
​WarehouseReference

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

version
​integer
​ExternalMeta

External Metadata by a specific External meta key

source
​Source

Source information for the entity

​object

Map of timestamp entries for various lifecycle events

If Outbound is part of Pick To Tote task, it's reference will be provided here

Details specific for the Outbound Task object

​LifecycleReference
​OutboundLifecycleState
​TypedTaskReference[]

Update an existing Outbound Order

PATCH
https://api.cartoncloud.com
/tenants/{tenantId}/outbound-orders/{orderId}
required permission: EDIT_OUTBOUND_ORDER

Update an existing outbound order (sale order).

The endpoint supports both JSON Merge Patch and JSON Patch operations requests.

⚠️ Current Limitations:

  1. Only /externalMeta.* updates are currently enabled for this endpoint. Other fields cannot be patched.
  2. JSON Merge Patch skips removal of a field that is not present.
  3. Individual array items update is not available - arrays should be replaced entirely.

Note: When patching externalMeta fields, the External-Meta-Key header must be provided to specify which external meta key to operate on.

Update an existing Outbound Order › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

orderId
​string · uuid · required

Outbound Order Id

Example: 41597723-b4fb-443f-bc98-5457783d97f0

Update an existing Outbound Order › 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.

Update an existing Outbound Order › 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 Outbound Order › Responses

Outbound order updated successfully

Default Representation of Outbound object
OutboundOrder_Default
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:
OUTBOUND
Default: OUTBOUND

Fields uniquely identifying Outbound order

​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.

Contains information about size of the order.

status
​OutboundStatus · enum
Enum values:
DRAFT
AWAITING_STOCK
AWAITING_PICK_AND_PACK
PACKING_IN_PROGRESS
PICKED
PACKED
DISPATCHED
REJECTED
Example: PACKING_IN_PROGRESS
​WarehouseReference

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

version
​integer
​ExternalMeta

External Metadata by a specific External meta key

source
​Source

Source information for the entity

​object

Map of timestamp entries for various lifecycle events

​TaskReference

Reference to the Parent Order that this Outbound Order belongs to. Parent Orders are not yet implemented and are only stored as UUIDs.

Details specific for the Outbound Task object

Delete an existing Outbound Order

DELETE
https://api.cartoncloud.com
/tenants/{tenantId}/outbound-orders/{orderId}
required permission: DELETE_OUTBOUND_ORDER

Deletes an outbound order (sale order).

Deletion is only allowed for certain Sale Order statuses, configurable via the organisation setting for Sale Order allowed edit/delete.

Delete an existing Outbound Order › path Parameters

tenantId
​string · uuid · required

Tenant ID. Can be found in organisation settings

orderId
​string · uuid · required

Outbound Order Id

Example: 41597723-b4fb-443f-bc98-5457783d97f0

Delete an existing Outbound Order › 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

Delete an existing Outbound Order › Responses

Outbound order has been deleted

No data returned
Outbound Order Packing SlipsReports