Guides

Standard Elements

Shared types used across the public API. Descriptions and examples come from the OpenAPI schemas; field lists are on each schema in the API Reference.

References

External or alternate identifiers for a resource, in addition to id (always a UUID).

Values may or may not be unique, depending on tenant and customer configuration. Tenants can define additional reference types beyond the common keys below.

Code
{
  "customer": "REF-1234",
  "tracking": "123-456-EXT",
  "alternateReference": "ALT-REF-5678"
}

References

Customer

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

Code
{
  "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "name": "Customer A",
  "references": {
    "code": "C123456"
  }
}

CustomerReference

Warehouse

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

Code
{
  "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "name": "Example Warehouse"
}

WarehouseReference

Address

Postal address. companyName or contactName is required. address1, city, and country are required for a complete address.

Code
{
  "companyName": "Company A",
  "contactName": "Mr Smith",
  "address1": "1 Main Street",
  "address2": "Unit 2, Corporate Tower",
  "suburb": "Springfield",
  "city": "Metropolis",
  "postcode": "4000",
  "phone": "07 5512 3456",
  "email": "info@company.com"
}

Address_Core

State

State, region, or prefecture. When both code and name are supplied, code is used first.

Validation is country-dependent. CartonCloud maintains a per-country list of valid zones (address_zones).

When the resolved country has no configured zones (for example New Zealand), any state value in the request is ignored and the address is not rejected for an unknown state code (draft is not set for state alone).

When zones exist (for example Australia, United States), state.code or state.name must match a configured zone or the request returns 422 (Invalid reference value at /state/code or /state/name).

Code
{
  "code": "QLD",
  "name": "Queensland"
}

State

Country

Identifies a country by iso2Code, iso3Code, or name (ISO 3166).

If multiple properties are provided, they are checked in that order. Lookup succeeds only if the first provided property is a valid country. Remaining properties are not used as a fallback.

Code
{
  "name": "Australia",
  "iso2Code": "AU",
  "iso3Code": "AUS"
}

Country

Delivery method

How items are transferred to a customer.

SHIPPING — delivery using a shipping carrier (default)
PICKUP — the customer collects from a warehouse or other location

requestedService is the requested carrier service (for example Standard, Express, Overnight).

Code
{
  "type": "SHIPPING",
  "requestedService": "Standard"
}

TransportMethod

Product

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

Code
{
  "id": "c3706e8c-7526-11e8-adc0-fa7ae01b3ebc",
  "name": "Product Name",
  "references": {
    "code": "SKU123",
    "barcode": "00123246586"
  }
}

Product

Unit of measure

Product unit of measure. type is the unit-of-measure code used to identify the UOM.

Code
{
  "type": "CARTON"
}

UnitOfMeasure

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.

Code
{
  "amount": 1000,
  "currency": "AUD"
}

Money

Delivery run

Identifies a delivery run by id and optional name. May include the associated warehouse.

Code
{
  "id": "7b34abb4-e186-11e8-8b31-0260123835bc",
  "name": "Delivery Run Name",
  "warehouse": {
    "id": "93d12a9a-cb7d-11e8-8b31-0260123835bc",
    "name": "Default"
  }
}

DeliveryRunReference

Run sheet

Identifies a run sheet by id, optional name, and optional date.

Code
{
  "id": "93d12a9a-cb7d-11e8-8b31-0260123835bc",
  "name": "Run Sheet Name",
  "date": "2020-08-04"
}

RunsheetReference

Manifest

Identifies a manifest by id.

Code
{
  "id": "c3706e8c-7526-11e8-adc0-fa7ae01b3ebc"
}

ManifestReference

User

Identifies a user by id and display name.

Code
{
  "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "name": "John Smith"
}

UserReference

Timestamp

A timestamp. time is an ISO 8601 date-time.

Code
{
  "time": "2025-05-30T14:14:16+10:00"
}

TimestampObject

Error reference

Item-level error on an outbound order (for example a product that could not be allocated).

Code
{
  "message": "Ice Cream (IC-123) x 2 CTN - Product not found",
  "isResolved": false,
  "errorType": 10449
}

OutboundError

Custom fields

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.

Code
{
  "custom_field_1": "Priority customer",
  "sop_custom_field_1": "Gift wrap"
}

Properties

Search request

Search request body. The condition tree is the value of condition. condition.type is AndCondition or OrCondition.

Code
{
  "condition": {
    "type": "AndCondition",
    "conditions": []
  }
}

SearchRequest

Search (text)

Text field comparison. method is one of EQUAL_TO, NOT_EQUAL_TO, CONTAINS, DOES_NOT_CONTAIN, STARTS_WITH. Prefer JsonField for field over deprecated ValueField.

Code
{
  "type": "TextComparisonCondition",
  "method": "EQUAL_TO",
  "field": {
    "type": "JsonField",
    "pointer": "/group/id"
  },
  "value": {
    "type": "ValueField",
    "value": "b5c83bc7-fa18-4e03-8cc2-11400ce6e03b"
  }
}

TextComparisonCondition

Search (boolean)

Boolean field comparison. Prefer JsonField for field over deprecated ValueField.

Code
{
  "type": "BooleanComparisonCondition",
  "field": {
    "type": "JsonField",
    "pointer": "/details/urgent"
  },
  "value": {
    "type": "ValueField",
    "value": true
  }
}

BooleanComparisonCondition

Search (numeric)

Numeric field comparison. operator is one of EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL. Prefer JsonField for field over deprecated ValueField.

Code
{
  "type": "NumericComparisonCondition",
  "operator": "GREATER_THAN",
  "field": {
    "type": "JsonField",
    "pointer": "/measures/quantity"
  },
  "value": {
    "type": "ValueField",
    "value": 100
  }
}

NumericComparisonCondition

Search (date)

Date field comparison. operator is one of EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL. Prefer JsonField for field over deprecated ValueField.

Code
{
  "type": "DateComparisonCondition",
  "operator": "GREATER_THAN",
  "field": {
    "type": "JsonField",
    "pointer": "/properties/expiryDate"
  },
  "value": {
    "type": "ValueField",
    "value": "2025-10-25"
  }
}

DateComparisonCondition

Search (date-time)

Date-time field comparison. operator is one of EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL. Prefer JsonField for field over deprecated ValueField.

Code
{
  "type": "DateTimeComparisonCondition",
  "operator": "GREATER_THAN",
  "field": {
    "type": "JsonField",
    "pointer": "/timestamps/created/time"
  },
  "value": {
    "type": "ValueField",
    "value": "2025-10-25T10:30:00Z"
  }
}

DateTimeComparisonCondition

Search field

Recommended field selector. pointer is a JSON Pointer path (for example /group/id).

JsonPointerField

Search field (deprecated)

Deprecated field selector (type: ValueField). Prefer JsonField with a JSON Pointer when both options are available.

AliasField

Last modified on November 10, 2026

General Webhooks