Inbound Orders (Purchase Orders)

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

InboundOrderStatus · enum

Status of the inbound order

Enum values:

DRAFT

NOT_YET_RECEIVED

RECEIVED

VERIFIED

ALLOCATED

REJECTED

Example: DRAFT

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

Details specific for the Inbound Order object

InboundItemRequest[]

List of Inbound Item objects

Create a new Inbound Order › Responses

Order successfully created

Default Representation of Inbound Order object

InboundOrder_Default

id

UUID · uuid

CustomerReference

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 · const

Const value: INBOUND

InboundOrderReferences

Fields uniquely identifying Inbound order

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.

object · readOnly

Only returned when the Include request header contains measures.

status

InboundOrderStatus · enum

Status of the inbound order

Enum values:

DRAFT

NOT_YET_RECEIVED

RECEIVED

VERIFIED

ALLOCATED

REJECTED

Example: DRAFT

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

object

Map of timestamp entries for various lifecycle events

version

integer

ExternalMeta

External Metadata by a specific External meta key

Details specific for the Inbound Order object

InboundItem[]

List of Inbound Item objects

POST/tenants/{tenantId}/inbound-orders

curl https://api.cartoncloud.com/tenants/:tenantId/inbound-orders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept-Version: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "type": "INBOUND",
  "status": "DRAFT",
  "references": {
    "customer": "REF-12345"
  },
  "customer": {
    "name": "Alderson'\''s"
  },
  "warehouse": {
    "name": "Default"
  },
  "details": {
    "arrivalDate": "2019-12-15",
    "hasChildren": false,
    "instructions": "work hard",
    "urgent": true
  },
  "properties": {
    "transfer": "hello"
  },
  "items": [
    {
      "properties": {
        "expiryDate": "2020-10-25",
        "batchNumber": "AAAA"
      },
      "details": {
        "product": {
          "references": {
            "code": "JANE_TEST"
          }
        },
        "unitOfMeasure": {
          "type": "CTN"
        }
      },
      "measures": {
        "quantity": 2
      },
      "status": "OK"
    },
    {
      "properties": {
        "expiryDate": "2020-01-22",
        "batchNumber": "BBBB"
      },
      "details": {
        "product": {
          "references": {
            "code": "STLWB/DW"
          }
        },
        "unitOfMeasure": {
          "type": "CTN"
        }
      },
      "measures": {
        "quantity": 2
      },
      "status": "RECEIVED_DAMAGED"
    }
  ]
}'

Example Request Body

{
  "type": "INBOUND",
  "status": "DRAFT",
  "references": {
    "customer": "REF-12345"
  },
  "customer": {
    "name": "Alderson's"
  },
  "warehouse": {
    "name": "Default"
  },
  "details": {
    "arrivalDate": "2019-12-15",
    "hasChildren": false,
    "instructions": "work hard",
    "urgent": true
  },
  "properties": {
    "transfer": "hello"
  },
  "items": [
    {
      "properties": {
        "expiryDate": "2020-10-25",
        "batchNumber": "AAAA"
      },
      "details": {
        "product": {
          "references": {
            "code": "JANE_TEST"
          }
        },
        "unitOfMeasure": {
          "type": "CTN"
        }
      },
      "measures": {
        "quantity": 2
      },
      "status": "OK"
    },
    {
      "properties": {
        "expiryDate": "2020-01-22",
        "batchNumber": "BBBB"
      },
      "details": {
        "product": {
          "references": {
            "code": "STLWB/DW"
          }
        },
        "unitOfMeasure": {
          "type": "CTN"
        }
      },
      "measures": {
        "quantity": 2
      },
      "status": "RECEIVED_DAMAGED"
    }
  ]
}

json

application/json

Example Responses

{
  "id": "38756e85-d15c-45d9-84fd-1b3e50b73527",
  "customer": {
    "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "name": "Customer A",
    "references": {
      "code": "C123456"
    }
  },
  "invoice": {
    "id": "38756e85-d15c-45d9-84fd-1b3e50b73527"
  },
  "type": "INBOUND",
  "references": {
    "numericId": 123,
    "customer": "REF-12345"
  },
  "properties": {
    "custom_field_1": "Priority customer",
    "sop_custom_field_1": "Gift wrap"
  },
  "measures": {
    "quantity": 0,
    "quantityOnHand": 0,
    "quantityFree": 0,
    "uniqueProducts": 0
  },
  "status": "DRAFT",
  "warehouse": {
    "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "name": "Example Warehouse"
  },
  "timestamps": {
    "created": {
      "time": "2025-05-30T14:14:16+10:00"
    },
    "modified": {
      "time": "2025-05-30T14:14:16+10:00"
    },
    "verified": {
      "time": "2025-05-30T14:14:16+10:00"
    },
    "allocated": {
      "time": "2025-05-30T14:14:16+10:00"
    }
  },
  "version": 52,
  "externalMeta": {
    "orderId": "1234",
    "fulfilmentId": "45646"
  },
  "details": {
    "arrivalDate": "2019-12-15",
    "errors": [
      {
        "errorType": 0,
        "message": "message",
        "isResolved": true
      }
    ],
    "hasChildren": true,
    "isAdjustment": true,
    "instructions": "work hard",
    "parentId": "parentId",
    "urgent": true,
    "urgency": "NONE"
  },
  "items": [
    {
      "id": "38756e85-d15c-45d9-84fd-1b3e50b73527",
      "references": {
        "numericId": 123,
        "customer": "ITEM-001"
      },
      "properties": {
        "custom_field_1": "Priority customer",
        "sop_custom_field_1": "Gift wrap"
      },
      "measures": {
        "quantity": 0
      },
      "type": "ITEM",
      "status": "OK",
      "details": {
        "product": {
          "id": "38756e85-d15c-45d9-84fd-1b3e50b73527",
          "references": {
            "code": "JANE_TEST"
          }
        },
        "unitOfMeasure": {
          "type": "CTN"
        }
      }
    }
  ]
}

json

application/json

Bulk Delete Inbound Orders

POST

https://api.cartoncloud.com

/tenants/{tenantId}/inbound-orders/bulk-delete

required permission: DELETE_INBOUND_ORDER

Deletes inbound orders matching filter.condition. The condition is mandatory; omitting filter or filter.condition, or sending an empty condition, returns 422 Unprocessable Entity and no orders are deleted.

Bulk Delete Inbound Orders › path Parameters

tenantId

string · uuid · required

Tenant ID. Can be found in organisation settings

Bulk Delete Inbound 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:

Bulk Delete Inbound Orders › Request Body

Bulk delete entities matching a search filter. A non-empty `filter.condition` is required; requests without a condition are rejected and no entities are deleted. To delete specific entities by UUID, use `filter.condition` with a ListComparisonCondition on `/id` and method EXISTS_IN.

BulkDeleteEntityRequest

object · required

Search filter selecting entities to delete. condition is required.

Bulk Delete Inbound Orders › Responses

Success - Returns per-entity success and failure results

Response from a bulk delete operation with per-entity success and failure results.

BulkDeleteResponse

BulkDeleteFailure[]

BulkDeleteSuccess[]

POST/tenants/{tenantId}/inbound-orders/bulk-delete

curl https://api.cartoncloud.com/tenants/:tenantId/inbound-orders/bulk-delete \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept-Version: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "filter": {
    "condition": {
      "type": "AndCondition",
      "conditions": [
        {
          "type": "AndCondition",
          "conditions": [
            null
          ]
        }
      ]
    }
  }
}'

Example Request Body

{
  "filter": {
    "condition": {
      "type": "AndCondition",
      "conditions": [
        {
          "type": "AndCondition",
          "conditions": [
            null
          ]
        }
      ]
    }
  }
}

json

Example Responses

{
  "success": [],
  "failed": [
    {
      "entity": {
        "id": "41597723-b4fb-443f-bc98-5457783d97f0",
        "type": "INBOUND",
        "references": {
          "customer": "PO-12345",
          "numericId": 9876
        }
      },
      "errors": [
        {
          "type": "INBOUND_ORDER_ITEM_ALREADY_PACKED",
          "message": "Purchase Order contains Products which have been Packed",
          "field": null,
          "details": {
            "outboundOrders": [
              {
                "id": "38756e85-d15c-45d9-84fd-1b3e50b73527",
                "type": "OUTBOUND",
                "references": {
                  "customer": "Packed SO Ref",
                  "numericId": 12345
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

json

application/json

Search Inbound Orders

POST

https://api.cartoncloud.com

/tenants/{tenantId}/inbound-orders/search

required permission: VIEW_INBOUND_ORDER

Search for previously created inbound orders (purchase orders).

To perform this action, the API Client needs to have the “WMS Create Job” role.

Condition Fields

Use JsonField pointers for search conditions.

Custom property pointers (/properties/{name}) may also be searchable.

Supported JsonField pointers

Pointer	Description
`/customer/id`	Customer ID
`/customer/name`	Customer name
`/details/arrivalDate`	Arrival date
`/details/instructions`	Special instructions
`/details/isAdjustment`	Is stock adjustment
`/details/parentId`	Parent inbound order ID
`/details/urgency`	Urgency enum (`NONE`, `CUSTOMER_REQUESTED`, `URGENT`)
`/details/urgent`	Is urgent order
`/id`	Order ID
`/invoice/id`	Invoice ID (when the caller has VIEW_CHARGES, or Hide charging information is off)
`/references/customer`	Customer reference
`/references/numericId`	Numeric ID
`/status`	Status enum (e.g. `DRAFT`)
`/timestamps/allocated/time`	Allocated (ISO 8601)
`/timestamps/created/time`	Created (ISO 8601)
`/timestamps/modified/time`	Modified (ISO 8601)
`/timestamps/verified/time`	Verified (ISO 8601)
`/warehouse/id`	Warehouse ID

Product line search (`productId`)

Use a ValueField named productId (not a JsonField pointer). It matches inbound orders that have at least one line item for the given warehouse product UUID.

Condition type	Methods
`TextComparisonCondition`	`EQUAL_TO`, `NOT_EQUAL_TO`
`ListComparisonCondition`	`EXISTS_IN`, `NOT_EXISTS_IN`

For ListComparisonCondition, the value is an array of product UUIDs. EXISTS_IN matches orders that contain any listed product; NOT_EXISTS_IN excludes orders that contain any listed product.

Search Inbound Orders › path Parameters

tenantId

string · uuid · required

Tenant ID. Can be found in organisation settings

Search Inbound 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:

Include

string[] · style: simple

Comma-separated list of additional fields to include in the response.

Enum values:

measures

Prefer

string · enum

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

Value	Description
return=minimal	Switch the response into minimal representation (id only).

Enum values:

return=minimal

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

Success

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = array
	type = array

Properties for InboundOrder_Default list (Prefer omitted):

InboundOrder_Default[]

Default Representation of Inbound Order object

InboundOrder_Default

id

UUID · uuid

CustomerReference

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 · const

Const value: INBOUND

InboundOrderReferences

Fields uniquely identifying Inbound order

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.

object · readOnly

Only returned when the Include request header contains measures.

status

InboundOrderStatus · enum

Status of the inbound order

Enum values:

DRAFT

NOT_YET_RECEIVED

RECEIVED

VERIFIED

ALLOCATED

REJECTED

Example: DRAFT

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

object

Map of timestamp entries for various lifecycle events

version

integer

ExternalMeta

External Metadata by a specific External meta key

Details specific for the Inbound Order object

InboundItem[]

List of Inbound Item objects

POST/tenants/{tenantId}/inbound-orders/search

curl https://api.cartoncloud.com/tenants/:tenantId/inbound-orders/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Accept-Version: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "condition": {
    "type": "AndCondition",
    "conditions": [
      {
        "type": "AndCondition",
        "conditions": [
          null
        ]
      }
    ]
  }
}'

Example Request Body

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

json

Example Responses

[
  {
    "id": "38756e85-d15c-45d9-84fd-1b3e50b73527",
    "customer": {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "name": "Customer A",
      "references": {
        "code": "C123456"
      }
    },
    "invoice": {
      "id": "38756e85-d15c-45d9-84fd-1b3e50b73527"
    },
    "type": "INBOUND",
    "references": {
      "numericId": 123,
      "customer": "REF-12345"
    },
    "properties": {
      "custom_field_1": "Priority customer",
      "sop_custom_field_1": "Gift wrap"
    },
    "measures": {
      "quantity": 0,
      "quantityOnHand": 0,
      "quantityFree": 0,
      "uniqueProducts": 0
    },
    "status": "DRAFT",
    "warehouse": {
      "id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "name": "Example Warehouse"
    },
    "timestamps": {
      "created": {
        "time": "2025-05-30T14:14:16+10:00"
      },
      "modified": {
        "time": "2025-05-30T14:14:16+10:00"
      },
      "verified": {
        "time": "2025-05-30T14:14:16+10:00"
      },
      "allocated": {
        "time": "2025-05-30T14:14:16+10:00"
      }
    },
    "version": 52,
    "externalMeta": {
      "orderId": "1234",
      "fulfilmentId": "45646"
    },
    "details": {
      "arrivalDate": "2019-12-15",
      "errors": [
        {
          "errorType": 0,
          "message": "message",
          "isResolved": true
        }
      ],
      "hasChildren": true,
      "isAdjustment": true,
      "instructions": "work hard",
      "parentId": "parentId",
      "urgent": true,
      "urgency": "NONE"
    },
    "items": [
      {
        "id": "38756e85-d15c-45d9-84fd-1b3e50b73527",
        "references": {
          "numericId": 123,
          "customer": "ITEM-001"
        },
        "properties": {
          "custom_field_1": "Priority customer",
          "sop_custom_field_1": "Gift wrap"
        },
        "measures": {
          "quantity": 0
        },
        "type": "ITEM",
        "status": "OK",
        "details": {
          "product": {
            "id": "38756e85-d15c-45d9-84fd-1b3e50b73527",
            "references": {
              "code": "JANE_TEST"
            }
          },
          "unitOfMeasure": {
            "type": "CTN"
          }
        }
      }
    ]
  }
]

json

application/json

View Inbound Order

GET

https://api.cartoncloud.com

/tenants/{tenantId}/inbound-orders/{orderId}

required permission: VIEW_INBOUND_ORDER

Retrieves a previously created inbound order (purchase order).

Response shape matches Create Inbound Order. Use Prefer: return=no-items to omit items. Use the Include header to add measures.

View Inbound Order › path Parameters

tenantId

string · uuid · required

Tenant ID. Can be found in organisation settings

orderId

string · uuid · required

Inbound Order ID

View Inbound 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:

External-Meta-Key

string

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

Comma-separated list of additional fields to include in the response.

Enum values:

measures

Prefer

string · enum

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

Value	Description
return=no-items	Omit items from the response.

Enum values:

return=no-items

View Inbound Order › Responses

Success. Response body depends on the Prefer request header: - Prefer: return=no-items → InboundOrder_NoItems - Prefer header omitted → InboundOrder_Default

oneOf

Exactly one variant must match.

Decision Table

Variant	Matching Criteria
	type = object
	type = object

Properties for InboundOrder_Default (Prefer header omitted):

Default Representation of Inbound Order object

id

UUID · uuid

CustomerReference

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 · const

Const value: INBOUND

InboundOrderReferences

Fields uniquely identifying Inbound order

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.

object · readOnly

Only returned when the Include request header contains measures.

status

InboundOrderStatus · enum

Status of the inbound order

Enum values:

DRAFT

NOT_YET_RECEIVED

RECEIVED

VERIFIED

ALLOCATED

REJECTED

Example: DRAFT

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

object

Map of timestamp entries for various lifecycle events

version

integer

ExternalMeta

External Metadata by a specific External meta key