# Standard Elements

<!-- Generated from OpenAPI `x-standard-element`. Edit the schemas, not this file. -->

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.

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

<a href="/api-reference/~schemas#references">References</a>

## Customer

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

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

<a href="/api-reference/~schemas#customerreference">CustomerReference</a>

## Warehouse

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

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

<a href="/api-reference/~schemas#warehousereference">WarehouseReference</a>

## Address

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

```json
{
  "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"
}
```

<a href="/api-reference/~schemas#address-core">Address_Core</a>

## 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`).

```json
{
  "code": "QLD",
  "name": "Queensland"
}
```

<a href="/api-reference/~schemas#state">State</a>

## Country

Identifies a country by `iso2Code`, `iso3Code`, or `name`
([ISO 3166](https://www.iso.org/obp/ui/#search)).

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.

```json
{
  "name": "Australia",
  "iso2Code": "AU",
  "iso3Code": "AUS"
}
```

<a href="/api-reference/~schemas#country">Country</a>

## 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`).

```json
{
  "type": "SHIPPING",
  "requestedService": "Standard"
}
```

<a href="/api-reference/~schemas#transportmethod">TransportMethod</a>

## 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`.

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

<a href="/api-reference/~schemas#product">Product</a>

## Unit of measure

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

```json
{
  "type": "CARTON"
}
```

<a href="/api-reference/~schemas#unitofmeasure">UnitOfMeasure</a>

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

```json
{
  "amount": 1000,
  "currency": "AUD"
}
```

<a href="/api-reference/~schemas#money">Money</a>

## Delivery run

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

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

<a href="/api-reference/~schemas#deliveryrunreference">DeliveryRunReference</a>

## Run sheet

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

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

<a href="/api-reference/~schemas#runsheetreference">RunsheetReference</a>

## Manifest

Identifies a manifest by `id`.

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

<a href="/api-reference/~schemas#manifestreference">ManifestReference</a>

## User

Identifies a user by `id` and display `name`.

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

<a href="/api-reference/~schemas#userreference">UserReference</a>

## Timestamp

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

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

<a href="/api-reference/~schemas#timestampobject">TimestampObject</a>

## Error reference

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

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

<a href="/api-reference/~schemas#outbounderror">OutboundError</a>

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

```json
{
  "custom_field_1": "Priority customer",
  "sop_custom_field_1": "Gift wrap"
}
```

<a href="/api-reference/~schemas#properties">Properties</a>

## 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`.

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

<a href="/api-reference/~schemas#textcomparisoncondition">TextComparisonCondition</a>

## Search (boolean)

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

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

<a href="/api-reference/~schemas#booleancomparisoncondition">BooleanComparisonCondition</a>

## 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`.

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

<a href="/api-reference/~schemas#numericcomparisoncondition">NumericComparisonCondition</a>

## 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`.

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

<a href="/api-reference/~schemas#datecomparisoncondition">DateComparisonCondition</a>

## 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`.

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

<a href="/api-reference/~schemas#datetimecomparisoncondition">DateTimeComparisonCondition</a>

## Search field

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

<a href="/api-reference/~schemas#jsonpointerfield">JsonPointerField</a>

## Search field (deprecated)

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

<a href="/api-reference/~schemas#aliasfield">AliasField</a>