Shipments v3

Get Shipments

get /shipments

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

shipment_state

array (string)

query

Filter on shipment state. Use a 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 a comma as separator for multiple values.

destination_warehouse_id

array (integer)

query

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

warehouse_filter_mode

string

query

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

Available values:

Default: "and"

estimated_delivery_from

integer

query

Filter shipments with estimated delivery at or after this timestamp (Unix timestamp in seconds). Only includes shipments that have an estimated delivery date set.

Example: /shipments?estimated_delivery_from=1640995200

estimated_delivery_to

integer

query

Filter shipments with estimated delivery at or before this timestamp (Unix timestamp in seconds). Only includes shipments that have an estimated delivery date set.

Example: /shipments?estimated_delivery_to=1672531200

sort

string

query

Sort shipments by the specified field. Use minus prefix for descending order. Note: When sorting by estimated_delivery_at, only shipments with estimated delivery date set will be included.

ShipmentSortOption

string

query

The next cursor from the previous request to continue pagination.

num

integer

query

Number of items to return.

Default: 10

include_packages

boolean

query

Whether to include packages in shipments.

Default: false

include_items_undeclared

boolean

query

Whether to include undeclared received items in shipments.

Default: false

Successful. Returns an envelope containing a list of shipments.

ShipmentEnvelope

{
  "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
200	Successful. Returns an envelope containing a list of shipments.
400	Invalid request. Data sent from the client is invalid.
401	Missing or invalid authentication.
403	User is not authorized to perform this operation.
500	Internal Server Error.
502	Bad Gateway.

Add Shipment

post /shipments

object

REQUIRED

Shipment

Successful. Returns a shipment.

Shipment

{
  "id": "DH73264839L",
  "created_by": "jane.doe@example.com",
  "info": {
    "reference_number": "REFNBR6739286432",
    "barcode": "123456789123456789",
    "currency": "USD",
    "note": "New spring collection",
    "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": "Carrier name",
      "service": "Express delivery",
      "reference": "CAR123456789",
      "tracking_url": "https://example.com",
      "tracking_url_title": "Track delivery",
      "estimated_pickup_at": 1740728198,
      "estimated_delivery_at": 1741761398
    },
    "additional_data": {
      "special_tax_number": "TAX123"
    }
  },
  "packages": [
    {
      "description": "Children",
      "barcode": "1234567891",
      "weight": {
        "weight": 12000,
        "unit": "kg"
      },
      "dimensions": {
        "width": 125000,
        "height": 125000,
        "length": 125000,
        "unit": "cm"
      },
      "items": [
        {
          "sku": "SKU123456",
          "product_name": "T-Shirt",
          "unit_price": 12300,
          "quantity": 20,
          "barcode": "1231234561",
          "additional_data": {
            "special_tax_number": "ABC123"
          }
        }
      ],
      "additional_data": {
        "special_tax_number": "ABC123"
      }
    }
  ]
}

{
  "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
201	Successful. Returns a shipment.
400	Invalid request. Data sent from the client is invalid.
401	Missing or invalid authentication.
403	User is not authorized to perform this operation.
500	Internal Server Error.

Get Shipment

get /shipments/{shipment_id}

shipment_id

string

path

REQUIRED

Shipment ID

Successful. Returns a shipment.

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
200	Successful. Returns a shipment.
400	Invalid request. Data sent from the client is invalid.
401	Missing or invalid authentication.
403	User is not authorized to perform this operation.
404	The specified resource was not found.
500	Internal Server Error.

Delete Shipment

delete /shipments/{shipment_id}

Typically, a shipment should be set to the cancelled state instead.

shipment_id

string

path

REQUIRED

Shipment ID

HTTP Status Code Summary
200	Successful. Deleted the shipment.
400	Invalid request. Data sent from the client is invalid.
401	Missing or invalid authentication.
403	User is not authorized to perform this operation.
404	The specified resource was not found.
500	Internal Server Error.

Get Shipment Actions

get /shipments/{shipment_id}/actions

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

string

query

The next cursor from the previous request to continue pagination.

num

integer

query

Number of items to return.

Default: 100

shipment_id

string

path

REQUIRED

Shipment ID

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

ShipmentActionEnvelope

{
  "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
200	Successful. Returns an envelope containing a list of shipment actions.
400	Invalid request. Data sent from the client is invalid.
401	Missing or invalid authentication.
403	User is not authorized to perform this operation.
404	The specified resource was not found.
500	Internal Server Error.

Add Shipment Action

post /shipments/{shipment_id}/actions

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

shipment_id

string

path

REQUIRED

Shipment ID

object

REQUIRED

Action to perform.

ShipmentAction

Successful. Returns a shipment action.

ShipmentAction

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

{
  "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
201	Successful. Returns a shipment action.
400	Invalid request. Data sent from the client is invalid.
401	Missing or invalid authentication.
403	User is not authorized to perform this operation.
404	The specified resource was not found.
412	Precondition Failed.
500	Internal Server Error.

Objects

ActionType
string

create - This action is added when the shipment is created and cannot be added afterwards. The initial_shipment property is set with the data from the POST request.
set-state - Set a new state for the shipment. The state parameter 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 states 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 states 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 states 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 states 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 code	Additional info
field-missing	field
field-unknown	field
field-readonly	field
field-type	field
field-validation	field
version-invalid	none
condition-failed	none
other	none

Example: "field-missing"

ErrorMessage
object

Error object returned when a request is not successful.

request_id

string

REQUIRED

ID of request

Example: ""123e4567-e89b-12d3-a456-426614174000""

error_code

ErrorCode

REQUIRED

error_data

object

REQUIRED

More data depending on the error code.

<*>

string

Address
object

Address

name

string

Name for address.

Example: ""Example Inc.""

address

string

Address

Example: ""1445 1st Avenue""

address2

string

Address 2

Example: """"

city

string

City

Example: ""New York""

zip

string

Zip

Example: ""10021""

state

string

State

Example: ""NY""

country_id

string

(iso-3166)

Country Code (ISO 3166, Alpha-2 uppercased)

Example: ""US""

Contact
object

Contact

title

string

Prefix to name.

Example: ""Mr""

first_name

string

First name

Example: ""Jane""

last_name

string

Last name

Example: ""Doe""

string

(email)

Example: ""jane.doe@example.com""

mobile

string

(E.164)

Mobile phone number (E.164).

Example: ""+46850009300""

note

string

Note (e.g. instructions).

ContactAddress
object

Contact and Address.

contact

Contact

address

Address

Carrier
object

Carrier information.

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

width

integer

(int64)

REQUIRED

Width in 1/1000 of the unit.

Example: "125000"

Minimum: 0

height

integer

(int64)

REQUIRED

Height in 1/1000 of the unit.

Example: "125000"

Minimum: 0

length

integer

(int64)

REQUIRED

Length in 1/1000 of the unit.

Example: "125000"

Minimum: 0

unit

string

REQUIRED

Unit of a dimension.

Example: ""cm""

VALUES
cm
in

Weight
object

Weight

weight

integer

(int64)

REQUIRED

Weight in 1/1000 of unit.

Example: "12000"

Minimum: 0

unit

string

REQUIRED

Unit of a weight.

Example: ""kg""

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 the carrier. Carrier info is 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 the carrier.
arrived - At least one package has arrived.
received - At least one item has been received.
closed - The shipment has been closed. See the all_packages_arrived and all_items_received flags for success state.
closed-incomplete - The shipment has been closed and marked as incomplete. See the optional reason code for the reason.
cancelled - Shipment has been cancelled. Any warehouse transactions have been reverted.

ShipmentReceiveMethod
string

The method used to receive the items in the shipment.

default - Default method. Items in shipment can be either manually received (by scanning or manually setting the received quantity for each item) or the user can also "Accept all", where all items in the package will be automatically received.
manual-count - Manual counting of items, where all items in the shipment must be received. Counting is done either by using a scanner or by manually setting items to be received. It will not be possible to "Accept all" items; this menu option will not be available.
auto-accept - Automatic acceptance of items, where the client automatically receives all the items in the received package. The status is automatically changed when the package is confirmed as arrived. It is possible to change the received items manually, for example, by reducing the quantity if an item is damaged or missing, or by adding an undeclared item.

ShipmentSortOption
string

Sorting options for shipments. Uses field names with optional minus prefix for descending order.

estimated-delivery-at - Sort by estimated delivery date (ascending)
-estimated-delivery-at - Sort by estimated delivery date (descending)

Example: "estimated-delivery-at"

ShipmentReceivedItem
object

Received Items

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 serial_numbers length if present.

Minimum: 1

ShipmentReceivedItems
object

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

reason_code

string

Optional reason code for this batch of items.

note

string

Note about the received items.

items

array

(ShipmentReceivedItem)

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.

reason_code

string

Optional reason code for this batch of items.

note

string

Note about the received items.

items

array

(ShipmentItem)

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.

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

ActionType

REQUIRED

The type of action

state

ShipmentState

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

info

ShipmentInfo

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

package_id

string

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

package

ShipmentPackage

Parameter for actions add-package and update-package. The package and its 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.

package_id_list

array

(string)

Parameter for action add-arrived-packages. List of IDs 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

ShipmentReceivedItems

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.

received_items_undeclared

ShipmentReceivedItemsUndeclared

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.

warehouse_values

object

READ ONLY

Values taken from a warehouse transaction in a remove-stock action if the 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 determines whether 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 from which the stock should be removed.

Minimum: 1

initial_shipment

Shipment

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

ShipmentInfo
object

Shipment information

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

receive_method

ShipmentReceiveMethod

The method used to receive the items in the shipment.

note

string

Note for the shipment.

origin

ContactAddress

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

Example: """1"""

Minimum: 1

destination

ContactAddress

The destination for the shipment.

destination_warehouse_id

integer

(int64)

The ID of the destination warehouse in Sitoo.

Example: """2"""

Minimum: 1

carrier

Carrier

Carrier references and tracking URL.

additional_data

object

Custom properties (<String, String> map).

Example: """{ "special_tax_number": "ABC123" }"""

<*>

string

Example: """{ "special_tax_number": "ABC123" }"""

ShipmentPackage
object

Shipment Package

string

READ ONLY

REQUIRED

ID of the package.

description

string

Description of the package.

barcode

string

Barcode to identify the package.

weight

Weight

The weight of the package.

dimensions

Dimensions

The dimensions of the package.

value

integer

(int64)

READ ONLY

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

Example: ""12300""

items

array

(ShipmentItem)

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

Example: ""{ "special_tax_number": "ABC123" }""

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

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.

Example: "12300"

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

array

(ShipmentItemSerialNumber)

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

Example: "{ "special_tax_number": "ABC123" }"

quantity_received

integer

(int64)

READ ONLY

REQUIRED

Quantity that has been received.

Minimum: 0

ShipmentItemSerialNumber
object

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

Example: "{ "special_tax_number": "ABC123" }"

received

boolean

READ ONLY

REQUIRED

Indicates if this item has been received.

Shipment
object

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

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}$

Example: """733d0d9c-2be5-4e39-b6f7-ae80980ca239"""

created_by

string

WRITE ONLY

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

ShipmentState

READ ONLY

REQUIRED

State of shipment. Default state is new.

info

ShipmentInfo

Origin, destination and carrier info about the shipment.

packages

array

(ShipmentPackage)

REQUIRED

The packages in this shipment. An array of packages.

items_undeclared

array

(ShipmentItem)

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.

items

array

(Shipment)

REQUIRED

Returned items.

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.

items

array

(ShipmentAction)

REQUIRED

Returned items

string

REQUIRED

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

Shipments v3

Get Shipments

Add Shipment

Get Shipment

Delete Shipment

Get Shipment Actions

Add Shipment Action

Objects

ActionTypestring

ErrorCodestring

ErrorMessageobject

Addressobject

Contactobject

ContactAddressobject

Carrierobject

Dimensionsobject

Weightobject

ShipmentStatestring

ShipmentReceiveMethodstring

ShipmentSortOptionstring

ShipmentReceivedItemobject

ShipmentReceivedItemsobject

ShipmentReceivedItemsUndeclaredobject

ShipmentAction

ShipmentInfoobject

ShipmentPackageobject

ShipmentItemobject

ShipmentItemSerialNumberobject

Shipmentobject

ShipmentEnvelopeobject

ShipmentActionEnvelopeobject

ActionType
string

ErrorCode
string

ErrorMessage
object

Address
object

Contact
object

ContactAddress
object

Carrier
object

Dimensions
object

Weight
object

ShipmentState
string

ShipmentReceiveMethod
string

ShipmentSortOption
string

ShipmentReceivedItem
object

ShipmentReceivedItems
object

ShipmentReceivedItemsUndeclared
object

ShipmentInfo
object

ShipmentPackage
object

ShipmentItem
object

ShipmentItemSerialNumber
object

Shipment
object

ShipmentEnvelope
object

ShipmentActionEnvelope
object