Shipments v3 (BETA)

Sitoo Shipments API is used for tracking shipments and moving inventory to and from stores. It is recommended to read the Sitoo API introduction before reading this document.

Version 3 of the Sitoo Shipment service is currently in beta.

What's new in version 3

  • Enforces shipment state flows to allow for a more defined way of working with shipments. Also gives a more precise use of event callbacks
  • Allows receiving items in batches, which helps to partially move items into stock in the stores while the shipment is open
  • Handles serial- and batch numbers for shipment items
  • Integration with Sitoo Warehouse, performing warehouse transactions for specific actions
  • Changes to shipments are always done using actions. The list of actions that have been performed can be retrieved for each shipment
  • Monetary values are handled using the integer data type, representing 1/100th of the value. E.g. $123.50 = 12350


The shipment service is available at the base URL To access the API you combine the base URL and the endpoint URL. Example for adding a new shipment:



Authentication is done with the HTTP basic authentication mechanism over a secure connection. The API ID and password can be found in the Backoffice under settings/Sitoo REST API (Requires administrator privileges).

Using the API ID and password, add an extra header to the request for authentication:

"Authorization: Basic " + base64_encode("{API ID}" + ":" + "{password}");

Example header (API ID "10020-140" and password "buNxoOx2o5kM2JMc3VhBX20k4Gik4qKXyKfg332A"):

Authorization: Basic MTAwMjAtMTQwOmJ1TnhvT3gybzVrTTJKTWMzVmhCWDIwazRHaWs0cUtYeUtmZzMzMkE=)

Data Types


Boolean values are represented as either true or false, all other values are not considered boolean values.

Example for query parameter


  • A shipment is the base object that contains one or more packages
  • A package contains in itself one or more items
  • An item is an entity with a quantity, name and sku.
  • A parameter that is read-only is only part of the response of the API. If it is required and read-only then it is always part of the response.

Shipment States & Actions

A shipment is always in one of the states listed below. To progress the state of a shipment, you use actions. Each time an action is applied to a shipment the version of the shipment is incremented. Each action tracks to which version of the shipment it was applied to. All the actions are stored for the shipment object and can be retrieved and used as a log for the shipment history. All actions that are applied to a shipment must send in the last seen version of the shipment to assure that the client has the latest version. If attempting to perform an action on an outdated version of the shipment, an HTTP response code of 412 will be returned.

You can only proceed one state at a time and cannot skip any step listed in order below with the exception of cancelled. To transition from one state to another, use the set-state action. However, notice that some other actions implicitly change the state of the shipment

Shipment States

newA shipment is in the new state when it is first created. To create a new shipment you start by using the Add Shipment endpoint.
packedShipment is packed. At least 1 package with 1 item in it, is required when going to state packed. When the shipment has reached state packed, the package items can no longer be changed. Note: To remove stock from a warehouse when going to state packed, the action remove-stock should be used instead of set-state.
transport-orderedTransport has been ordered from carrier. Carrier info will typically be updated when moving to this state.
ready-for-pickupShipment is ready for pickup. Labels and transport documents have been added.
in-transitShipment has been picked up by carrier and should be in transit to the destination.
arrivedWhen the first package is noted as arrived with the add-arrived-packages action, the state of the shipment will implicitly be moved to the arrived state
receivedWhen the first item in the shipment is set as received using the add-received-items or add-received-items-undeclared action, the state of the shipment will implicitly be moved to received
closedThe shipment has been closed. See all_packages_arrived and all_items_received properties to determine if all packages arrived and all items were received
closed-incompleteThe shipment has been closed. The property state_reason_code can be used when moving to this state to have a record of the reason for it being incomplete. This reason code will also be available in the property closed_state_reason_code on the shipment object.
cancelledShipment has been cancelled. If you want to cancel a shipment for any reason, you can use the set-state action with the cancelled state. This will revert any warehouse transactions that have been done by this shipment and set the state cancelled. No further actions can be taken on a cancelled shipment.

Shipment Actions

createIs set when you create a shipment by using the POST /shipments-endpoint. You never need to use this action yourself, it is stored together with the initial_shipment property in the action history for tracking purposes.
set-stateIs used for transitioning the shipment to the following states: packed, transport-ordered, ready-for-pickup, in-transit, closed, closed-incomplete and cancelled.
set-infoIs used to set info on the shipment.
add-packageIs used in the new state to add a package to the shipment.
update-packageIs used in the new, packed, transport-ordered and ready-for-pickup state to partially update a package already existing in the shipment. Items in a package can only be updated in state new.
delete-packageIs used in the new state to delete a package from the shipment.
remove-stockIs used in the new state to go to state packed with an option to remove stock from an origin warehouse and to optionally update the shipment unit prices with values from the warehouse transaction.
add-arrived-packagesIs used in any of the three states in-transit, arrived or received to note a package as arrived at the target destination. An add-arrived-packages action will transition a shipment in state in-transit to state arrived.
add-received-itemsIs used in either the arrived state or the received state. An add-received-items action will transition a shipment in state arrived to state received.
add-received-items-undeclaredIs used in either the arrived state or the received state. An add-received-items-undeclared action will transition a shipment in state arrived to state received.
You can continue to add arrived packages and received items when the shipment is in the `received` state. When done with the shipment you can close it by the action `set-state` and setting the state to `closed` or `closed-incomplete`.

Sitoo Warehouse Integration

If either the warehouse origin or destination IDs are set, then the following types of actions will integrate with the warehouse.

  • Remove stock - When shipment is in state new, the action remove-stock will result in transition to state packed and a warehouse transaction if a warehouse ID is specified in the action object.
  • Add Received Items - Adding received items will result in a warehouse transaction where the items are transferred into a warehouse if the warehouse_id property of the ShipmentReceivedItems object is set.
  • Add Received Items Undeclared - Adding undeclared received items will result in a warehouse transaction where the items are transferred into a warehouse if the warehouse_id property of the ShipmentReceivedItemsNotDelivered object is set.
  • Set State Cancelled - When cancelling a shipment, any previous warehouse transactions performed by this shipment will be reverted.
Shipment ID
You can choose to create the shipment using an ID from another system to help with integration issues. The ID provided must be unique. If no ID is provided for the shipment upon creation, one will be generated.


To use events for integration with the shipment service see the SPI Events documentation. Register the shipment-v3 event type to receive the events for a shipment. The object sent for a shipment event is the ShipmentV3Data object type that is described in the SPI Events documentation.


When receiving a response code that is not in the 200 range, most shipment endpoints will return an error message. It contains an error code, a request ID and an error data object with one or more key-values that describes the error. The object returned will look like this:

"error_code": "version-invalid",
"error_data": {
"message": "Wrong shipment version, current version is 1 but got 2"
"request_id": "1e42b374-67d6-49b9-af19-48116aa36363"
"error_code": "field-type",
"error_data": {
"field": "info.origin_warehouse_id",
"message": "Wrong type string for value '1' on field 'info.origin_warehouse_id' expected type int64"
"request_id": "1f238fde-a4a1-411a-8d9a-825038b5e6f4"

Use cases

Update package with barcode

Update barcode on a package with package_id 0ba7de5f-a109-450a-9106-a056317a7be8 in shipment with shipment_id 123


"created_by": "john",
"version": 1,
"action": "update-package",
"package_id": "0ba7de5f-a109-450a-9106-a056317a7be8",
"package": {
"barcode": "111"