Shipments v3

Get Shipments

get /shipments

Get list of shipments. The returned list is sorted by created_at in descending order. Response size is limited to 1MB (compressed). If limit is exeeded a 502 error response is returned instead.

PARAMETERS
shipment_state
array (string)
query

Filter on shipment state. Use comma as separator for multiple values. Not allowed to filter on both active states and end states (closed, closed-incomplete and cancelled).

ShipmentState
Example: /shipments?shipment_state=in-transit,arrived
origin_warehouse_id
array (integer)
query

Filter on origin_warehouse_id. Use comma as separator for multiple values.

destination_warehouse_id
array (integer)
query

Filter on destination_warehouse_id. Use comma as separator for multiple values.

warehouse_filter_mode
string
query

Mode for operating on origin warehouse and/or destination warehouse filter.

Default: "and"
next
string
query

The next cursor from previous request to continue pagination.

num
integer
query

Number of items to return.

Default: 10
include_packages
boolean
query

Filter for including packages for shipments.

Default: false
include_items_undeclared
boolean
query

Filter for including undeclared received items for shipments.

Default: false
Returns

Successful. Returns an envelope containing a list of shipments.

gethttps://shipments.sitooapis.com/v3/shipments?shipment_state=new
RESPONSE JSON
{
"items": [
{
"id": "733d0d9c-2be5-4e39-b6f7-ae80980ca239",
"version": 0,
"created_at": 0,
"modified_at": 0,
"state": "new",
"info": {
"reference_number": "string",
"barcode": "string",
"currency": "string",
"note": "string",
"origin": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"origin_warehouse_id": 1,
"destination": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"destination_warehouse_id": 2,
"carrier": {
"name": "string",
"service": "string",
"reference": "string",
"tracking_url": "string",
"tracking_url_title": "string",
"estimated_pickup_at": 0,
"estimated_delivery_at": 0
},
"additional_data": {
"special_tax_number": "ABC123"
}
},
"packages": [
{
"id": "string",
"description": "string",
"barcode": "string",
"weight": {
"weight": 12000,
"unit": "kg"
},
"dimensions": {
"width": 125000,
"height": 125000,
"length": 125000,
"unit": "cm"
},
"value": 12300,
"items": [
{
"id": "string",
"sku": "string",
"product_name": "string",
"unit_price": 12300,
"quantity": 0,
"batch": "string",
"batch_expires": 0,
"barcode": "string",
"serial_numbers": [
{
"serial_number": "string",
"barcode": "string",
"additional_data": {
"special_tax_number": "ABC123"
},
"received": true
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"quantity_received": 0
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"arrived_at": 0,
"total_quantity": 0,
"total_quantity_received": 0
}
],
"items_undeclared": [],
"all_packages_arrived": true,
"all_items_received": true,
"total_package_count": 1,
"total_item_quantity": 10,
"total_item_undeclared_quantity": 0
}
],
"next": "dwISDRHDuBTS0UVgUla8HQ=="
}
HTTP Status Code Summary
200Successful. Returns an envelope containing a list of shipments.
400Invalid request. Data sent from client is invalid.
401Missing or bad authentication.
403User is not authorized to perform operation.
500Internal Server Error.
502Bad Gateway.

Add Shipment

post /shipments
REQUEST BODY
object
REQUIRED

Shipment

Shipment
Returns

Successful. Returns a shipment.

posthttps://shipments.sitooapis.com/v3/shipments
{
"created_by": "string",
"info": {
"reference_number": "string",
"barcode": "string",
"currency": "string",
"note": "string",
"origin": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"origin_warehouse_id": 1,
"destination": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"destination_warehouse_id": 2,
"carrier": {
"name": "string",
"service": "string",
"reference": "string",
"tracking_url": "string",
"tracking_url_title": "string",
"estimated_pickup_at": 0,
"estimated_delivery_at": 0
},
"additional_data": {
"special_tax_number": "ABC123"
}
},
"packages": [
{
"description": "string",
"barcode": "string",
"weight": {
"weight": 12000,
"unit": "kg"
},
"dimensions": {
"width": 125000,
"height": 125000,
"length": 125000,
"unit": "cm"
},
"value": 12300,
"items": [
{
"sku": "string",
"product_name": "string",
"unit_price": 12300,
"quantity": 0,
"batch": "string",
"batch_expires": 0,
"barcode": "string",
"serial_numbers": [
{
"serial_number": "string",
"barcode": "string",
"additional_data": {
"special_tax_number": "ABC123"
}
}
],
"additional_data": {
"special_tax_number": "ABC123"
}
}
],
"additional_data": {
"special_tax_number": "ABC123"
}
}
]
}
RESPONSE JSON
{
"id": "733d0d9c-2be5-4e39-b6f7-ae80980ca239",
"version": 0,
"created_at": 0,
"modified_at": 0,
"state": "new",
"info": {
"reference_number": "string",
"barcode": "string",
"currency": "string",
"note": "string",
"origin": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"origin_warehouse_id": 1,
"destination": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"destination_warehouse_id": 2,
"carrier": {
"name": "string",
"service": "string",
"reference": "string",
"tracking_url": "string",
"tracking_url_title": "string",
"estimated_pickup_at": 0,
"estimated_delivery_at": 0
},
"additional_data": {
"special_tax_number": "ABC123"
}
},
"packages": [
{
"id": "string",
"description": "string",
"barcode": "string",
"weight": {
"weight": 12000,
"unit": "kg"
},
"dimensions": {
"width": 125000,
"height": 125000,
"length": 125000,
"unit": "cm"
},
"value": 12300,
"items": [
{
"id": "string",
"sku": "string",
"product_name": "string",
"unit_price": 12300,
"quantity": 0,
"batch": "string",
"batch_expires": 0,
"barcode": "string",
"serial_numbers": [
{
"serial_number": "string",
"barcode": "string",
"additional_data": {
"special_tax_number": "ABC123"
},
"received": true
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"quantity_received": 0
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"arrived_at": 0,
"total_quantity": 0,
"total_quantity_received": 0
}
],
"items_undeclared": [],
"all_packages_arrived": true,
"all_items_received": true,
"total_package_count": 1,
"total_item_quantity": 10,
"total_item_undeclared_quantity": 0
}
HTTP Status Code Summary
201Successful. Returns a shipment.
400Invalid request. Data sent from client is invalid.
401Missing or bad authentication.
403User is not authorized to perform operation.
500Internal Server Error.

Get Shipment

get /shipments/{shipment_id}
PARAMETERS
shipment_id
string
path
REQUIRED

Shipment ID

Returns

Successful. Returns a shipment.

gethttps://shipments.sitooapis.com/v3/shipments/733d0d9c-2be5-4e39-b6f7-ae80980ca239
RESPONSE JSON
{
"id": "733d0d9c-2be5-4e39-b6f7-ae80980ca239",
"version": 0,
"created_at": 0,
"modified_at": 0,
"state": "new",
"info": {
"reference_number": "string",
"barcode": "string",
"currency": "string",
"note": "string",
"origin": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"origin_warehouse_id": 1,
"destination": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"destination_warehouse_id": 2,
"carrier": {
"name": "string",
"service": "string",
"reference": "string",
"tracking_url": "string",
"tracking_url_title": "string",
"estimated_pickup_at": 0,
"estimated_delivery_at": 0
},
"additional_data": {
"special_tax_number": "ABC123"
}
},
"packages": [
{
"id": "string",
"description": "string",
"barcode": "string",
"weight": {
"weight": 12000,
"unit": "kg"
},
"dimensions": {
"width": 125000,
"height": 125000,
"length": 125000,
"unit": "cm"
},
"value": 12300,
"items": [
{
"id": "string",
"sku": "string",
"product_name": "string",
"unit_price": 12300,
"quantity": 0,
"batch": "string",
"batch_expires": 0,
"barcode": "string",
"serial_numbers": [
{
"serial_number": "string",
"barcode": "string",
"additional_data": {
"special_tax_number": "ABC123"
},
"received": true
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"quantity_received": 0
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"arrived_at": 0,
"total_quantity": 0,
"total_quantity_received": 0
}
],
"items_undeclared": [],
"all_packages_arrived": true,
"all_items_received": true,
"total_package_count": 1,
"total_item_quantity": 10,
"total_item_undeclared_quantity": 0
}
HTTP Status Code Summary
200Successful. Returns a shipment.
400Invalid request. Data sent from client is invalid.
401Missing or bad authentication.
403User is not authorized to perform operation.
404The specified resource was not found.
500Internal Server Error.

Delete Shipment

delete /shipments/{shipment_id}

Typically a shipment should be set to state cancelled instead.

PARAMETERS
shipment_id
string
path
REQUIRED

Shipment ID

deletehttps://shipments.sitooapis.com/v3/shipments/733d0d9c-2be5-4e39-b6f7-ae80980ca239
HTTP Status Code Summary
200Successful. Deleted the shipment.
400Invalid request. Data sent from client is invalid.
401Missing or bad authentication.
403User is not authorized to perform operation.
404The specified resource was not found.
500Internal Server Error.

Get Shipment Actions

get /shipments/{shipment_id}/actions

Get list of actions for a shipment, sorted in chronological order.

PARAMETERS
next
string
query

The next cursor from previous request to continue pagination.

num
integer
query

Number of items to return.

Default: 100
shipment_id
string
path
REQUIRED

Shipment ID

Returns

Successful. Returns an envelope containing a list of shipment actions.

gethttps://shipments.sitooapis.com/v3/shipments/733d0d9c-2be5-4e39-b6f7-ae80980ca239/actions
RESPONSE JSON
{
"items": [
{
"created_at": 0,
"created_by": "string",
"shipment_version": 0,
"action": "set-state",
"state": "new",
"info": {
"reference_number": "string",
"barcode": "string",
"currency": "string",
"note": "string",
"origin": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"origin_warehouse_id": 1,
"destination": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"destination_warehouse_id": 2,
"carrier": {
"name": "string",
"service": "string",
"reference": "string",
"tracking_url": "string",
"tracking_url_title": "string",
"estimated_pickup_at": 0,
"estimated_delivery_at": 0
},
"additional_data": {
"special_tax_number": "ABC123"
}
},
"package_id": "string",
"package": {
"id": "string",
"description": "string",
"barcode": "string",
"weight": {
"weight": 12000,
"unit": "kg"
},
"dimensions": {
"width": 125000,
"height": 125000,
"length": 125000,
"unit": "cm"
},
"value": 12300,
"items": [
{
"id": "string",
"sku": "string",
"product_name": "string",
"unit_price": 12300,
"quantity": 0,
"batch": "string",
"batch_expires": 0,
"barcode": "string",
"serial_numbers": [
{
"serial_number": "string",
"barcode": "string",
"additional_data": {
"special_tax_number": "ABC123"
},
"received": true
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"quantity_received": 0
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"arrived_at": 0,
"total_quantity": 0,
"total_quantity_received": 0
},
"package_id_list": [
"1",
"2"
],
"received_items": {
"reason_code": "string",
"note": "string",
"items": [
{
"item_id": "string",
"note": "string",
"serial_numbers": [
"string"
],
"quantity": 0
}
],
"warehouse_id": 1,
"warehouse_transaction_id": 0
}
}
],
"next": "dwISDRHDuBTS0UVgUla8HQ=="
}
HTTP Status Code Summary
200Successful. Returns an envelope containing a list of shipment actions.
400Invalid request. Data sent from client is invalid.
401Missing or bad authentication.
403User is not authorized to perform operation.
404The specified resource was not found.
500Internal Server Error.

Add Shipment Action

post /shipments/{shipment_id}/actions

Change the shipment using an action. A HTTP response code of 412 means that the shipment_version provided is incompatible with the current shipment.

PARAMETERS
shipment_id
string
path
REQUIRED

Shipment ID

REQUEST BODY
object
REQUIRED

Action to perform.

ShipmentAction
Returns

Successful. Returns a shipment action.

posthttps://shipments.sitooapis.com/v3/shipments/733d0d9c-2be5-4e39-b6f7-ae80980ca239/actions
{
"created_by": "string",
"shipment_version": 0,
"action": "set-state",
"state": "new",
"info": {
"reference_number": "string",
"barcode": "string",
"currency": "string",
"note": "string",
"origin": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"origin_warehouse_id": 1,
"destination": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"destination_warehouse_id": 2,
"carrier": {
"name": "string",
"service": "string",
"reference": "string",
"tracking_url": "string",
"tracking_url_title": "string",
"estimated_pickup_at": 0,
"estimated_delivery_at": 0
},
"additional_data": {
"special_tax_number": "ABC123"
}
},
"package_id": "string",
"package": {
"description": "string",
"barcode": "string",
"weight": {
"weight": 12000,
"unit": "kg"
},
"dimensions": {
"width": 125000,
"height": 125000,
"length": 125000,
"unit": "cm"
},
"value": 12300,
"items": [
{
"sku": "string",
"product_name": "string",
"unit_price": 12300,
"quantity": 0,
"batch": "string",
"batch_expires": 0,
"barcode": "string",
"serial_numbers": [
{
"serial_number": "string",
"barcode": "string",
"additional_data": {
"special_tax_number": "ABC123"
}
}
],
"additional_data": {
"special_tax_number": "ABC123"
}
}
],
"additional_data": {
"special_tax_number": "ABC123"
}
},
"package_id_list": [
"1",
"2"
],
"received_items": {
"reason_code": "string",
"note": "string",
"items": [
{
"item_id": "string",
"note": "string",
"serial_numbers": [
"string"
],
"quantity": 0
}
],
"warehouse_id": 1
}
}
RESPONSE JSON
{
"created_at": 0,
"created_by": "string",
"shipment_version": 0,
"action": "set-state",
"state": "new",
"info": {
"reference_number": "string",
"barcode": "string",
"currency": "string",
"note": "string",
"origin": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"origin_warehouse_id": 1,
"destination": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"destination_warehouse_id": 2,
"carrier": {
"name": "string",
"service": "string",
"reference": "string",
"tracking_url": "string",
"tracking_url_title": "string",
"estimated_pickup_at": 0,
"estimated_delivery_at": 0
},
"additional_data": {
"special_tax_number": "ABC123"
}
},
"package_id": "string",
"package": {
"id": "string",
"description": "string",
"barcode": "string",
"weight": {
"weight": 12000,
"unit": "kg"
},
"dimensions": {
"width": 125000,
"height": 125000,
"length": 125000,
"unit": "cm"
},
"value": 12300,
"items": [
{
"id": "string",
"sku": "string",
"product_name": "string",
"unit_price": 12300,
"quantity": 0,
"batch": "string",
"batch_expires": 0,
"barcode": "string",
"serial_numbers": [
{
"serial_number": "string",
"barcode": "string",
"additional_data": {
"special_tax_number": "ABC123"
},
"received": true
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"quantity_received": 0
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"arrived_at": 0,
"total_quantity": 0,
"total_quantity_received": 0
},
"package_id_list": [
"1",
"2"
],
"received_items": {
"reason_code": "string",
"note": "string",
"items": [
{
"item_id": "string",
"note": "string",
"serial_numbers": [
"string"
],
"quantity": 0
}
],
"warehouse_id": 1,
"warehouse_transaction_id": 0
},
"initial_shipment": {
"id": "733d0d9c-2be5-4e39-b6f7-ae80980ca239",
"version": 0,
"created_at": 0,
"modified_at": 0,
"state": "new",
"info": {
"reference_number": "string",
"barcode": "string",
"currency": "string",
"note": "string",
"origin": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"origin_warehouse_id": 1,
"destination": {
"contact": {
"title": "Mr",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane.doe@example.com",
"mobile": "+46850009300",
"note": "string"
},
"address": {
"name": "Example Inc.",
"address": "1445 1st Avenue",
"address2": "",
"city": "New York",
"zip": "10021",
"state": "NY",
"country_id": "US"
}
},
"destination_warehouse_id": 2,
"carrier": {
"name": "string",
"service": "string",
"reference": "string",
"tracking_url": "string",
"tracking_url_title": "string",
"estimated_pickup_at": 0,
"estimated_delivery_at": 0
},
"additional_data": {
"special_tax_number": "ABC123"
}
},
"packages": [
{
"id": "string",
"description": "string",
"barcode": "string",
"weight": {
"weight": 12000,
"unit": "kg"
},
"dimensions": {
"width": 125000,
"height": 125000,
"length": 125000,
"unit": "cm"
},
"value": 12300,
"items": [
{
"id": "string",
"sku": "string",
"product_name": "string",
"unit_price": 12300,
"quantity": 0,
"batch": "string",
"batch_expires": 0,
"barcode": "string",
"serial_numbers": [
{
"serial_number": "string",
"barcode": "string",
"additional_data": {
"special_tax_number": "ABC123"
},
"received": true
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"quantity_received": 0
}
],
"additional_data": {
"special_tax_number": "ABC123"
},
"arrived_at": 0,
"total_quantity": 0,
"total_quantity_received": 0
}
],
"items_undeclared": [],
"all_packages_arrived": true,
"all_items_received": true,
"total_package_count": 1,
"total_item_quantity": 10,
"total_item_undeclared_quantity": 0
}
}
HTTP Status Code Summary
201Successful. Returns a shipment action.
400Invalid request. Data sent from client is invalid.
401Missing or bad authentication.
403User is not authorized to perform operation.
404The specified resource was not found.
412Precondition Failed.
500Internal Server Error.

Objects

ActionType
string

  • create. This action is added when the shipment is created and cannot be added afterwards, initial_shipment property is set with the data from the POST request.
  • set-state. Set new state of the shipment. state is required.
  • set-info. Update the shipment info.
  • add-package. Add a package, requires the package property. Only allowed in state new.
  • update-package. Partial update of a package, requires the package_id and package properties. Only allowed in state new, packed, transport-ordered and ready-for-pickup.
  • delete-package. Delete a package, requires the package_id property. Only allowed in state new.
  • remove-stock. Optionally remove stock from warehouse and set state to packed.
  • add-arrived-packages. Set packages as arrived. Only allowed from state in-transit, arrived or received. If state is in-transit, the shipment will transition to state arrived.
  • add-received-items. Set items in the shipment as received (usually counted). Only allowed from state arrived or received If state is arrived, the shipment will transition to state received.
  • add-received-items-undeclared. Add items that were not declared in the shipment and set them as received (usually counted). Only allowed from state arrived or received If state is arrived, the shipment will transition to state received.
Example: "set-state"

ErrorCode
string

Error codes and additional info in error_data:

Error codeAdditional info
field-missingfield
field-unknownfield
field-readonlyfield
field-typefield
field-validationfield
version-invalidnone
condition-failednone
othernone

Example: "field-missing"

ErrorMessage
object

Error object returned when a request is not successful.

PROPERTIES
request_id
string
REQUIRED

ID of request

error_code
REQUIRED
error_data
object
REQUIRED

More data depending on the error code.

<*>
string

Address
object

Address

PROPERTIES
name
string

Name for address.

address
string

Address

address2
string

Address 2

city
string

City

zip
string

Zip

state
string

State

country_id
string
(iso-3166)

Country Code (ISO 3166, Alpha-2 uppercased)

Contact
object

Contact

PROPERTIES
title
string

Prefix to name.

first_name
string

First name

last_name
string

Last name

email
string
(email)

Email

mobile
string
(E.164)

Mobile phone number (E.164).

note
string

Note (e.g. instructions).

ContactAddress
object

Contact and Address.

PROPERTIES
contact
address

Carrier
object

Carrier information.

PROPERTIES
name
string

Name of the carrier.

service
string

Name of the carrier's service.

reference
string

Carrier's reference number.

tracking_url
string
(url)

Tracking URL

tracking_url_title
string

Tracking URL title. If set then this will be displayed in UI instead of the URL.

estimated_pickup_at
integer
(int64)

Timestamp. Estimated time for pickup.

estimated_delivery_at
integer
(int64)

Timestamp. Estimated time for delivery.

Dimensions
object

Dimensions

PROPERTIES
width
integer
(int64)
REQUIRED

Width in 1/1000 of the unit.

Minimum: 0
height
integer
(int64)
REQUIRED

Height in 1/1000 of the unit.

Minimum: 0
length
integer
(int64)
REQUIRED

Length in 1/1000 of the unit.

Minimum: 0
unit
string
REQUIRED

Unit of a dimension.

VALUES
cm
in

Weight
object

Weight

PROPERTIES
weight
integer
(int64)
REQUIRED

Weight in 1/1000 of unit.

Minimum: 0
unit
string
REQUIRED

Unit of a weight.

VALUES
kg
lb
oz

ShipmentState
string

The state of the Shipment. All states except for cancelled can only be set from the previous state.

  • new New shipment has been created.
  • packed Shipment is packed. Setting this state will perform a warehouse transaction, removing items from origin_warehouse_id if it is set.
  • transport-ordered Transport has been ordered from carrier. Carrier info typically updated.
  • ready-for-pickup Shipment is ready for pickup. Labels and transport documents have been added.
  • in-transit Shipment has been picked up by carrier.
  • arrived At least one package has arrived.
  • received At least one item has been received.
  • closed The shipment has been closed. See all_packages_arrived and all_items_received flags for success state.
  • closed-incomplete The shipment has been closed and marked as incomplete. See optional reason code for reason.
  • cancelled Shipment has been cancelled. Any warehouse transactions have been reverted.

ShipmentReceivedItem
object

Received Items

PROPERTIES
item_id
string
REQUIRED

Reference to the shipment item ID.

note
string

Note about the received item.

serial_numbers
array
(string)

List of serial numbers (length must match quantity if provided).

quantity
integer
(int64)
REQUIRED

Quantity of items received (must match with serial_numbers length if present).

Minimum: 1

ShipmentReceivedItems
object

A batch of received (i.e. counted) items.

PROPERTIES
reason_code
string

Optional reason code for this batch of items.

note
string

Note about the received items.

items
REQUIRED
warehouse_id
integer
(int64)

The ID of the warehouse in Sitoo that received the items.

Minimum: 1
warehouse_transaction_id
integer
(int64)
READ ONLY

The ID of the warehouse transaction in Sitoo.

ShipmentReceivedItemsUndeclared
object

A batch of undeclared, received (i.e. counted) items that were in the shipment.

PROPERTIES
reason_code
string

Optional reason code for this batch of items.

note
string

Note about the received items.

items
REQUIRED
warehouse_id
integer
(int64)

The ID of the warehouse in Sitoo that received the items.

Minimum: 1
warehouse_transaction_id
integer
(int64)
READ ONLY

The ID of the warehouse transaction in Sitoo.

ShipmentAction

Shipment action. Some actions require fields to be supplied.

PROPERTIES
created_at
integer
(int64)
READ ONLY
REQUIRED

Timestamp. When the action was created.

created_by
string
REQUIRED

Who made this action. Sitoo clients will use the external ID of the user.

shipment_version
integer
(int64)
REQUIRED

Version of the shipment.

Minimum: 0
action
REQUIRED

The type of action

Parameter for action set-state. The new shipment state.

Parameter for action set-info. The updated shipment info.

reference_number
string

Custom number for the shipment.

barcode
string

Barcode identifying the shipment.

currency
string
(iso-4217)

The currency for amounts specified in the shipment (ISO 4217, Alpha-3 uppercased).

note
string

Note for the shipment

The origin where the shipment was sent from.

origin_warehouse_id
integer
(int64)

The ID of the origin warehouse in Sitoo. Note! Sitoo clients will use this to perform a warehouse transaction when moving to state packed, removing items from the specified warehouse (using the action remove-stock instead of set-state).

destination

The destination for the shipment.

destination_warehouse_id
integer
(int64)

The ID of the destination warehouse in Sitoo.

carrier

Carrier references and tracking URL.

additional_data
object

Custom properties (<String, String> map).

package_id
string

Parameter for action update-package and delete-package used to identify the package.

Parameter for action add-package and update-package. The package and it's contents. NOTE: Update will completely replace nested attributes, partial update is only for attributes on the root level. Total shipment size is limited to 400KB after a package is added or updated, if it exceeds 400KB an error is returned.

id
string
REQUIRED

ID of the package.

description
string

Description of the package.

barcode
string

Barcode to identify the package.

weight

The weight of the package.

dimensions

The dimensions of the package.

value
integer
(int64)

Amount in cents (1/100th of the currency). Total purchase price for all items in the package.

items
array

Items in the package. Total shipment size is not allowed to exceed 400KB.

additional_data
object

Custom properties (<String, String> map).

arrived_at
integer
(int64)

Timestamp when the package arrived. Set by action add-arrived-packages.

total_quantity
integer
(int64)
REQUIRED

Total quantity of all items in package.

total_quantity_received
integer
(int64)
REQUIRED

Total quantity received of all items in package.

package_id_list
array
(string)

Parameter for state add-arrived-packages. List of ID:s for packages that have arrived Note! The state will be changed to arrived if currently in in-transit.

state_reason_code
string

Parameter for action set-state. The reason for the state change.

received_items

Parameter for action add-received-items. List of items that have been received. Note! The state will be changed to received if currently in arrived.

reason_code
string

Optional reason code for this batch of items.

note
string

Note about the received items.

items
array
REQUIRED
warehouse_id
integer
(int64)

The ID of the warehouse in Sitoo that received the items.

warehouse_transaction_id
integer
(int64)

The ID of the warehouse transaction in Sitoo.

received_items_undeclared

Parameter for action add-received-items-undeclared. List of items that have been received, but were not declared in the shipment. Note! The state will be changed to received if currently in arrived.

reason_code
string

Optional reason code for this batch of items.

note
string

Note about the received items.

items
array
REQUIRED
warehouse_id
integer
(int64)

The ID of the warehouse in Sitoo that received the items.

warehouse_transaction_id
integer
(int64)

The ID of the warehouse transaction in Sitoo.

warehouse_values
object
READ ONLY

Values taken from a warehouse transaction in a remove-stock action if update_unit_prices parameter was set to true. The key for a value is the SKU.

<*>
integer
Price in cents (1/100 of the currency).
update_unit_prices
boolean

Parameter for action remove-stock that decides if the value of the shipment should be updated from the warehouse transaction.

Default: false
warehouse_id
integer
(int64)

Parameter for action remove-stock. ID for the Sitoo warehouse where the stock should be removed from.

Minimum: 1
initial_shipment

Parameter for action create. The initial shipment after it was created.

id
string
REQUIRED

Unique ID of the shipment. If ID is passed as empty string when creating a shipment, one will be generated.

created_by
string
REQUIRED

ID for who initialised the shipment. Sitoo clients will use the externalid of the user in Sitoo.

version
integer
(int64)
REQUIRED

Version of the shipment. Every time an action is applied, this version is incremented.

created_at
integer
(int64)
REQUIRED

Timestamp when the shipment was created.

modified_at
integer
(int64)
REQUIRED

Timestamp when the shipment was last modified. Updates when an action is added.

state
REQUIRED

State of shipment. Default state is new.

Origin, destination and carrier info about the shipment.

packages
array
REQUIRED

The packages in this shipment. An array of packages.

items_undeclared
array
REQUIRED

Undeclared items that are received for the shipment.

all_packages_arrived
boolean
REQUIRED

All packages have arrived.

all_items_received
boolean
REQUIRED

All items have been received.

closed_state_reason_code
string

Shipment action set-state reason code when state was set to closed, closed-incomplete or cancelled.

total_package_count
integer
(int64)
REQUIRED

Total number of packages in the shipment

total_item_quantity
integer
(int64)
REQUIRED

Total quantity of all items in all packages in the shipment

total_item_undeclared_quantity
integer
(int64)
REQUIRED

Total quantity of all undeclared items in the shipment

ShipmentInfo
object

Shipment Info

PROPERTIES
reference_number
string

Custom number for the shipment.

barcode
string

Barcode identifying the shipment.

currency
string
(iso-4217)

The currency for amounts specified in the shipment (ISO 4217, Alpha-3 uppercased).

note
string

Note for the shipment

The origin where the shipment was sent from.

contact
address
origin_warehouse_id
integer
(int64)

The ID of the origin warehouse in Sitoo. Note! Sitoo clients will use this to perform a warehouse transaction when moving to state packed, removing items from the specified warehouse (using the action remove-stock instead of set-state).

Minimum: 1
destination

The destination for the shipment.

contact
address
destination_warehouse_id
integer
(int64)

The ID of the destination warehouse in Sitoo.

Minimum: 1
carrier

Carrier references and tracking URL.

name
string

Name of the carrier.

service
string

Name of the carrier's service.

reference
string

Carrier's reference number.

tracking_url
string
(url)

Tracking URL

tracking_url_title
string

Tracking URL title. If set then this will be displayed in UI instead of the URL.

estimated_pickup_at
integer
(int64)

Timestamp. Estimated time for pickup.

estimated_delivery_at
integer
(int64)

Timestamp. Estimated time for delivery.

additional_data
object

Custom properties (<String, String> map).

Example: """{ "special_tax_number": "ABC123" }"""
<*>
string

ShipmentPackage
object

Shipment Package

PROPERTIES
id
string
READ ONLY
REQUIRED

ID of the package.

description
string

Description of the package.

barcode
string

Barcode to identify the package.

weight

The weight of the package.

weight
integer
(int64)
REQUIRED

Weight in 1/1000 of unit.

unit
string
REQUIRED

Unit of a weight.

dimensions

The dimensions of the package.

width
integer
(int64)
REQUIRED

Width in 1/1000 of the unit.

height
integer
(int64)
REQUIRED

Height in 1/1000 of the unit.

length
integer
(int64)
REQUIRED

Length in 1/1000 of the unit.

unit
string
REQUIRED

Unit of a dimension.

value
integer
(int64)
READ ONLY

Amount in cents (1/100th of the currency). Total purchase price for all items in the package.

items

Items in the package. Total shipment size is not allowed to exceed 400KB.

additional_data
object

Custom properties (<String, String> map).

Example: ""{ "special_tax_number": "ABC123" }""
<*>
string
arrived_at
integer
(int64)
READ ONLY

Timestamp when the package arrived. Set by action add-arrived-packages.

total_quantity
integer
(int64)
READ ONLY
REQUIRED

Total quantity of all items in package.

Minimum: 0
total_quantity_received
integer
(int64)
READ ONLY
REQUIRED

Total quantity received of all items in package.

Minimum: 0

ShipmentItem
object

Shipment Item

PROPERTIES
id
string
READ ONLY
REQUIRED

Unique ID of the item in the shipment (generated every time items for a shipment_package is set).

sku
string
REQUIRED

The SKU for this shipment item.

Pattern: ^[^\x00-\x1F\x7F\s]{1,2}$|^[^\x00-\x1F\x7F\s][^\x00-\x1F\x7F]{1,126}[^\x00-\x1F\x7F\s]$
Max Length: 128
Min Length: 1
product_name
string
REQUIRED

The name of the product in this shipment item.

unit_price
integer
(int64)

Amount in cents (1/100th of the currency). The net purchase price per unit for this shipment item. If entered it can be used for the warehouse stock transaction resulting from the shipment.

Minimum: 0
quantity
integer
(int64)
REQUIRED

The quantity of this item.

Minimum: 1
batch
string

Batch number.

batch_expires
integer
(int64)

Timestamp when the batch expires.

barcode
string

The barcode which identifies this item.

serial_numbers

If serial numbers are provided, then the quantity much match this array length. Note that by adding serial numbers you will be able to have significantly less items in a shipment before 400KB shipment limit is reached.

additional_data
object

Custom properties (<String, String> map). Note that by adding additional_data you will be able to have significantly less items in a shipment before 400KB shipment limit is reached.

Example: "{ "special_tax_number": "ABC123" }"
<*>
string
quantity_received
integer
(int64)
READ ONLY
REQUIRED

Quantity that has been received.

Minimum: 0

ShipmentItemSerialNumber
object

PROPERTIES
serial_number
string
REQUIRED

The serial number of the item instance.

barcode
string

Identifies the item instance.

additional_data
object

Custom properties (<String, String> map). Note that by adding additional_data you will be able to have significantly less items in a shipment before 400KB shipment limit is reached.

Example: "{ "special_tax_number": "ABC123" }"
<*>
string
received
boolean
READ ONLY
REQUIRED

Indicates if this item has been received.

Shipment
object

Shipment. Total size of a shipment is limited to 400KB.

PROPERTIES
id
string
REQUIRED

Unique ID of the shipment. If ID is passed as empty string when creating a shipment, one will be generated.

Pattern: ^[A-Za-z0-9\._-]{0,64}$
created_by
string
REQUIRED

ID for who initialised the shipment. Sitoo clients will use the externalid of the user in Sitoo.

version
integer
(int64)
READ ONLY
REQUIRED

Version of the shipment. Every time an action is applied, this version is incremented.

created_at
integer
(int64)
READ ONLY
REQUIRED

Timestamp when the shipment was created.

modified_at
integer
(int64)
READ ONLY
REQUIRED

Timestamp when the shipment was last modified. Updates when an action is added.

state
READ ONLY
REQUIRED

State of shipment. Default state is new.

Origin, destination and carrier info about the shipment.

reference_number
string

Custom number for the shipment.

barcode
string

Barcode identifying the shipment.

currency
string
(iso-4217)

The currency for amounts specified in the shipment (ISO 4217, Alpha-3 uppercased).

note
string

Note for the shipment

The origin where the shipment was sent from.

origin_warehouse_id
integer
(int64)

The ID of the origin warehouse in Sitoo. Note! Sitoo clients will use this to perform a warehouse transaction when moving to state packed, removing items from the specified warehouse (using the action remove-stock instead of set-state).

destination

The destination for the shipment.

destination_warehouse_id
integer
(int64)

The ID of the destination warehouse in Sitoo.

carrier

Carrier references and tracking URL.

additional_data
object

Custom properties (<String, String> map).

packages
REQUIRED

The packages in this shipment. An array of packages.

items_undeclared
READ ONLY
REQUIRED

Undeclared items that are received for the shipment.

all_packages_arrived
boolean
READ ONLY
REQUIRED

All packages have arrived.

all_items_received
boolean
READ ONLY
REQUIRED

All items have been received.

closed_state_reason_code
string
READ ONLY

Shipment action set-state reason code when state was set to closed, closed-incomplete or cancelled.

total_package_count
integer
(int64)
READ ONLY
REQUIRED

Total number of packages in the shipment

total_item_quantity
integer
(int64)
READ ONLY
REQUIRED

Total quantity of all items in all packages in the shipment

total_item_undeclared_quantity
integer
(int64)
READ ONLY
REQUIRED

Total quantity of all undeclared items in the shipment

ShipmentEnvelope
object

Envelope for shipment get list operations.

PROPERTIES
items
array
REQUIRED

Returned items.

next
string
REQUIRED

Next cursor, used to continue pagination. Empty string will be returned if all data has been delivered.

ShipmentActionEnvelope
object

Envelope for shipment action get list operations.

PROPERTIES
items
REQUIRED

Returned items

next
string
REQUIRED

Next cursor, used to continue pagination. Empty string will be returned if all data has been delivered.