Creating Stock Orders
Creating Stock Orders
Creating stock orders via the API requires a few steps to be completed successfully.
This article presents those steps along with API endpoints and payload that need to be used.
A corresponding article describing the same process from retailers perspective can be found here: How to order and receive stock.
New consignment
Step 1. Create a new consignment
A POST
request to the /api/2.0/consignments
endpoint.
The following consignment types can be used:
-
The SUPPLIER workflow is used for stock or purchase orders
-
The OUTLET workflow is used for transfers between Lightspeed Retail (X-Series) outlets and supports the following statuses: OPEN -> SENT -> RECEIVED (can be CANCELLED at any time after OPEN)
-
The RETURN workflow is used for supplier returns and supports the following statuses: OPEN -> SENT or CANCELLED
-
The STOCKTAKE workflow is used for stocktakes (see guide)
Request payload:
{
"name": "Test Consignment",
"outlet_id": "0242ac12-0002-11e9-e8c4-659494e196e3",
"type": "SUPPLIER",
"status": "OPEN",
}
Response payload:
{
"id": "0242ac17-002c-11eb-e6f7-1319c1cddfc9",
"outlet_id": "0242ac12-0002-11e9-e8c4-659494e196e3",
"name": "Test Consignment",
"due_at": null,
"type": "SUPPLIER",
"status": "OPEN",
"supplier_id": null,
"source_outlet_id": null,
"consignment_date": "2020-10-20T21:18:11+00:00",
"received_at": null,
"show_inactive": true,
"supplier_invoice": null,
"reference": null,
"total_count_gain": null,
"total_cost_gain": null,
"total_count_loss": null,
"total_cost_loss": null,
"created_at": "2020-10-20T21:18:11+00:00",
"updated_at": "2020-10-20T21:18:11+00:00",
"deleted_at": null,
"product_count": null,
"version": 153463,
"filters": []
}
Step 2. Add products to the consignment
A POST
request to the /api/2.0/consignments/:id/products
endpoint for each product that you want to add. The status of each product will be set to PENDING
.
Request payload:
{
"product_id": "0242ac12-0002-11e9-e8c4-659494e33119",
"count": 10
}
Response payload:
{
"product_id": "0242ac12-0002-11e9-e8c4-659494e33119",
"product_sku": null,
"count": "10.00000",
"received": null,
"cost": "10.00000",
"is_included": false,
"status": "PENDING",
"created_at": "2020-10-20T21:38:08+00:00",
"updated_at": "2020-10-20T21:38:08+00:00",
"deleted_at": null,
"version": 153464
}
At this point, it should be possible to check what products are added to the consignment
by making a GET
request to /api/2.0/consignments/:id/products
endpoint.
{
"data": [
{
"product_id": "0242ac12-0002-11e9-e8c4-659494e33119",
"product_sku": null,
"count": "10.00000",
"received": null,
"cost": "10.00000",
"is_included": false,
"status": "PENDING",
"created_at": "2020-10-20T21:38:08+00:00",
"updated_at": "2020-10-20T21:38:08+00:00",
"deleted_at": null,
"version": 153464
}
],
"version": {
"max": 153464,
"min": 153464
}
}
Consignment sent
Step 3. Mark consignment as SENT
SENT
NOTE: This action marks the stock order notification as 'Sent' and usually mirrors the action of a retailer sending an order to a supplier. It does not create stock movements. If you require an in transit movement to be created, ie. when the products have been sent from the supplier to the retailer, see the dispatched step. The SENT step is optional, it is acceptable to go from the 'PENDING' state straight to the 'DISPATCHED' state.
A PUT
request to the /api/2.0/consignments/:id
endpoint.
Request payload:
{
"outlet_id": "0242ac12-0002-11e9-e8c4-659494e196e3",
"name": "Test Consignment",
"type": "SUPPLIER",
"status": "SENT"
}
Response payload:
{
"id": "0242ac17-002c-11eb-e6f7-1319c1cddfc9",
"outlet_id": "0242ac12-0002-11e9-e8c4-659494e196e3",
"name": "Test Consignment",
"due_at": null,
"type": "SUPPLIER",
"status": "SENT",
"supplier_id": null,
"source_outlet_id": null,
"consignment_date": "2020-10-20T21:18:11+00:00",
"received_at": null,
"show_inactive": true,
"supplier_invoice": null,
"reference": null,
"total_count_gain": null,
"total_cost_gain": null,
"total_count_loss": null,
"total_cost_loss": null,
"created_at": "2020-10-20T21:18:11+00:00",
"updated_at": "2020-10-20T21:44:18+00:00",
"deleted_at": null,
"product_count": 1,
"version": 153465,
"filters": []
}
Step 4. Mark consignment as DISPATCHED
DISPATCHED
NOTE: This step will create an 'IN_TRANSIT' stock movement when completed.
A PUT
request to the /api/2.0/consignments/:id
endpoint. If you know when the stock is due to arrive at the retailer, you can provide a due_at
date which will be displayed to outlets so they know when stock will arrive.
Request payload:
{
"outlet_id": "0242ac12-0002-11e9-e8c4-659494e196e3",
"name": "Test Consignment",
"type": "SUPPLIER",
"status": "DISPATCHED"
}
Response payload:
{
"id": "0242ac17-002c-11eb-e6f7-1319c1cddfc9",
"outlet_id": "0242ac12-0002-11e9-e8c4-659494e196e3",
"name": "Test Consignment",
"due_at": null,
"type": "SUPPLIER",
"status": "DISPATCHED",
"supplier_id": null,
"source_outlet_id": null,
"consignment_date": "2020-10-20T21:18:11+00:00",
"received_at": null,
"show_inactive": true,
"supplier_invoice": null,
"reference": null,
"total_count_gain": null,
"total_cost_gain": null,
"total_count_loss": null,
"total_cost_loss": null,
"created_at": "2020-10-20T21:18:11+00:00",
"updated_at": "2020-10-20T22:05:49+00:00",
"deleted_at": null,
"product_count": 1,
"version": 153471,
"filters": []
}
Consignment received
Step 5. Set the received
quantity
received
quantityNOTE: This step can be skipped if all the steps are performed in quick succession. If that's the case the
received
attribute should be populated in step 2 when the product is added to the consignment.This step is only required if the time between marking the consignment as SENT and receiving it is substantial and the current state of the consignment needs to be correctly represented in the UI.
A PUT
request to the /api/2.0/consignments/:id/products/:productID
endpoint.
Request payload:
{
"count": 10,
"received": 12
}
NOTE: Notice that the
received
attribute may be different thancount
.
Response payload:
{
"id": "06bf537b-c783-11e6-f6b9-31d0cf5797c4",
"consignment_id": "06bf537b-c783-11e6-f6b9-31cfaa5dcde8",
"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
"count": 10,
"received": 12,
"cost": 1,
"sequence_number": 0
}
Step 6. Mark the consignment as received
A PUT
request to the /api/2.0/consignments/:id
endpoint.
Note: Once the consignment is marked as received you cannot change the received quantities.
Request payload:
{
"outlet_id": "0242ac12-0002-11e9-e8c4-659494e196e3",
"name": "Test Consignment",
"type": "SUPPLIER",
"status": "RECEIVED"
}
Response payload:
{
"id": "6f66e625-8752-4183-80f0-20a738fe0f39",
"outlet_id": "0242ac12-0002-11e9-e8c4-659494e196e3",
"name": "",
"due_at": null,
"type": "SUPPLIER",
"status": "RECEIVED",
"supplier_id": "0242ac11-0002-11eb-e54f-12a12aefe5fb",
"source_outlet_id": null,
"consignment_date": "2020-10-20T21:59:37+00:00",
"received_at": "2020-10-20T22:31:02+00:00",
"show_inactive": null,
"supplier_invoice": null,
"reference": "MyTestOrder",
"total_count_gain": null,
"total_cost_gain": null,
"total_count_loss": null,
"total_cost_loss": null,
"created_at": "2020-10-20T21:59:37+00:00",
"updated_at": "2020-10-20T22:31:02+00:00",
"deleted_at": null,
"product_count": 1,
"version": 153472,
"filters": []
}
NOTE: Please, note that this status change triggers a background job which processes all the consignment products included in the consignment and in case of large consignments it can take even a few minutes to complete.
If a
GET
request is made to the/api/2.0/consignments/:id
endpoint before the background job completes, the status on in that payload may still beSENT
orDISPATCHED
."
Updated 8 months ago