Order Shipping API¶
One key feature of Shopware ERP is shipping orders out of a warehouse, which refers to the process of clearing the physical stock which is being sent from the warehouse to the customer.
There are two endpoints for this:
PUT /api/orders/{id}/ship
is a high-level API which fully clears the stock for a single order from a warehouse using the default strategy.PUT /api/orderDetails/ship/{idempotencyKey}
is a fine-grained, batch-focused, idempotent API which can fully or partially clear stock for any number of order positions (order details) from any number of orders.
-
PUT
/api/orders/{id}/ship
¶ Ship the given order. Shipping an order entails the following steps:
- For each order detail, physical stock equal to the remaining quantity to ship (equal to
quantity - shipped
will be cleared from the given warehouse, - the shipped quantity of each order detail will be increased to the ordered quantity,
- the order details’ statuses will be set to “Completed”,
- the order’s status will be set to “Completely delivered”, and
- if configured, a status update email will be sent to the customer unless the
suppressStatusMail
parameter is passed.
Shipping an order which is already fully shipped has no effect. This means that this endpoint is naturally idempotent, which is why no idempotency key is required.
Parameters: - id (integer|string) – the database ID or the order number of the of the order to ship
Query Parameters: - useNumberAsId (boolean) – if
true
, interpretid
is an order number instead of as a database ID
Request JSON Object: - warehouse (object) – a warehouse from which to clear the stock required to fill the order
- warehouse.id (integer) – the database ID of the warehouse. Either this or the warehouses’s shorthand code must be specified.
- warehouse.code (string) – the shorthand code of the warehouse. Either this or the warehouse’s shorthand code must be specified.
- suppressStatusMail (boolean) – optional, if
true
, no status update email will be sent to the customer
Response JSON Object: - success (boolean) –
true
if shipping the order was successful,false
otherwise
Example request:
http
PUT /api/orders/21400/ship?useNumberAsId=true HTTP/1.1 Content-Type: application/json Host: localhost { "warehouse": { "id": 1 }, "suppressStatusMail": true }
curl
curl -i -X PUT 'https://localhost/api/orders/21400/ship?useNumberAsId=true' -H 'Content-Type: application/json' --data-raw '{"suppressStatusMail": true, "warehouse": {"id": 1}}'
wget
wget -S -O- --method=PUT 'https://localhost/api/orders/21400/ship?useNumberAsId=true' --header='Content-Type: application/json' --body-data='{"suppressStatusMail": true, "warehouse": {"id": 1}}'
httpie
echo '{ "suppressStatusMail": true, "warehouse": { "id": 1 } }' | http PUT 'https://localhost/api/orders/21400/ship?useNumberAsId=true' Content-Type:application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "success": true }
- For each order detail, physical stock equal to the remaining quantity to ship (equal to
-
PUT
/api/orderDetails/ship/{idempotencyKey}
¶ For a batch of order details, clear the specified quantity of stock for the order detail from a specified stock location and increase the order detail’s shipped quantity accordingly.
This takes a list of independent operations which are executed in order. When doing mass updates, we recommend sending large batches for optimum performance. The maximum allowed batch size is 1000.
For each operation, either a warehouse or a bin location from which to clear the stock must be specified. Warehouses are specified by their database ID or their code. Bin locations can either be specified by their database ID, or by their code and the warehouse code or the database ID of the warehouse (since the bin location code is unique on a per-warehouse basis).
This endpoint requires an arbitrary, unique idempotency key to be specified as a path component of the request URL. This idempotency key must be reused when retrying the same batch of operations after a server or network failure. It must not be reused when sending a new batch of operations. See Idempotency for further details on this.
Examples of valid bin location specifications:
"binLocation": { "id": 9 }
"binLocation": { "code": "a1", "warehouseId": "2" }
"binLocation": { "code": "a1", "warehouseCode": "MW" }
Examples of valid warehouse specifications:
"warehouse": { "id": 9 }
"warehouse": { "code": "MW" }
Parameters: - idempotencyKey (string) – the idempotency key for the request
Request JSON Object: - [*] (object) – an individual operation of the batch
- [*].orderDetailId (integer) – the order detail to ship
- [*].quantity (integer) – the quantity of stock to ship. This must be less than or equal to the remaining quantity to ship, which is the difference between the ordered quantity and the shipped quantity.
- [*].warehouse (object) – a warehouse from which to clear the stock for the order detail
- [*].warehouse.id (integer) – the database ID of the warehouse. Either this or the warehouse’s shorthand code must be specified
- [*].warehouse.code (string) – the shorthand code of the warehouse. Either this or the warehouse’s database ID must be specified.
- [*].binLocation (object) – a bin location from which to clear the stock for the order detail
- [*].binLocation.id (integer) – the database ID of the bin location. Either this or a valid combination of bin location code and a valid warehouse identifier must be specified.
- [*].binLocation.code (string) – the shorthand code of the bin location. If this is used to identify the bin location, the warehouse must also be specified by its database ID or its shorthand code.
- [*].binLocation.warehouseId (integer) – the database ID of the warehouse containing the bin location
- [*].binLocation.warehouseCode (string) – the shorthand code of the warehouse containing the bin location
Response JSON Object: - success (boolean) –
true
if all operations of the batch were executed successfully,false
otherwise - message (string) – an explanatory message which is present when there was at least one unsuccessful operation in the batch
- idempotencyKey (string) – the idempotency key of the batch
- createdAt (timestamp) – the point in time when all operations in the batch were completed
- results[*].operationId (any) – the value of the
id
property of the operation, if it was present in the request - results[*].success (boolean) –
true
if the operation was completed successfully,false
otherwise. Note that retrying the batch with the same idempotency key will not change the result for this operation. - results[*].message (string) – an explanation of what went wrong which is only present when the operation was not successful
Example request:
http
PUT /api/orderDetails/ship/b09788d8-fda3-4a5f-b4ec-4b876e71dc76 HTTP/1.1 Content-Type: application/json Host: localhost [ { "orderDetailId": 3011, "quantity": 2, "binLocation": { "id": 9 } }, { "orderDetailId": 3012, "quantity": 5, "warehouse": { "id": 1 } } ]
curl
curl -i -X PUT https://localhost/api/orderDetails/ship/b09788d8-fda3-4a5f-b4ec-4b876e71dc76 -H 'Content-Type: application/json' --data-raw '[{"orderDetailId": 3011, "quantity": 2, "binLocation": {"id": 9}}, {"orderDetailId": 3012, "quantity": 5, "warehouse": {"id": 1}}]'
wget
wget -S -O- --method=PUT https://localhost/api/orderDetails/ship/b09788d8-fda3-4a5f-b4ec-4b876e71dc76 --header='Content-Type: application/json' --body-data='[{"orderDetailId": 3011, "quantity": 2, "binLocation": {"id": 9}}, {"orderDetailId": 3012, "quantity": 5, "warehouse": {"id": 1}}]'
httpie
echo '[ { "binLocation": { "id": 9 }, "orderDetailId": 3011, "quantity": 2 }, { "orderDetailId": 3012, "quantity": 5, "warehouse": { "id": 1 } } ]' | http PUT https://localhost/api/orderDetails/ship/b09788d8-fda3-4a5f-b4ec-4b876e71dc76 Content-Type:application/json
Example response:
HTTP/1.1 200 OK Content-Type: application/json { "success": true, "idempotencyKey": "b09788d8-fda3-4a5f-b4ec-4b876e71dc76", "createdAt": "2019-07-22T13:35:12+0200", "results": [ { "success": true }, { "success": true } ] }