Tutorials

Creating Stock Orders

Suggest Edits

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

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

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

NOTE: 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 than count.

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 be SENT or DISPATCHED."

Updated 8 months ago