Tutorials

Fulfillments

Suggest Edits

Fulfillments

Sales in Lightspeed Retail (X-Series) can now be marked for fulfillment later. This tutorial will describe how you can achieve the following omni-channel workflows:

At the moment, fulfillments are created at the sale level only - ie. the same fulfillment status applies to an entire sale. We will be making enhancements in future to support more granular line item and even item level fulfillments so watch this space!

See also, the fulfillments API specification.

Workflow overview

The click and collect and delivery workflows usually proceed as follows:

  1. Customer places an order on retailer's e-commerce site
  2. Customer selects either the 'pick up in store' or 'delivery' option
  3. Retailer receives the order and picks and packs the inventory for the customer
  4. The customer either comes to the store to collect their order or the retailer ships the order to them
  5. The order is now completed

Steps 1-2 are performed on the e-commerce site. This tutorial will cover how you can use Lightspeed Retail (X-Series)'s API to perform steps 3-5 so that click and collect and delivery sales made using the e-commerce site can be sent to Lightspeed Retail (X-Series) and picked and packed using Lightspeed Retail (X-Series).

Note that this workflow can be applied to any e-commerce provider that can integrate with Lightspeed Retail (X-Series), or any ERP provider. The key things to note are as follows:

  • You should ensure you are either managing the inventory solely using Lightspeed Retail (X-Series) or Lightspeed Retail (X-Series)'s inventory levels are synchronised if you are managing the inventory externally (eg. using an ERP)
  • Your e-commerce provider/ERP needs to be able to support the concept of multiple locations for inventory and these locations should be able to be mapped to the outlets you'd like to offer for click and collect/delivery.

API workflow - Click and Collect

Create a sale with the following fields:

  • "status": "AWAITING_PICKUP"
  • "register_id": the id of a register at the outlet specified above. For example, a retailer might have a specific 'online' register that is used for online orders.
  • "fulfillment_details": the details or notes for this fulfillment sale. This cannot be modified after the fulfillment is created. Optional.
  • For each product in "register_sale_products":
    • "product_id": the id of the product being sold in this line item.
    • "fulfillment_type": the method of fulfillment for this line item. Use "PICKUP" if this item is to be picked up later. Otherwise, omit this field if the item is to be taken immediately.

POST https://<<domain_prefix>>.retail.lightspeed.app/api/register_sales

{
	"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
	"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
	"status": "AWAITING_PICKUP",
	"fulfillment_details": [{
        "type": "PICKUP",
        "note": "here is my pickup fulfillment note"
    }],
	...
	"register_sale_products": [{
		"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
		"quantity": 1,
		"price": 12,
		"tax": 1.8,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		"fulfillment_type": "PICKUP",
		...
	}]
}

When the customer comes to the store to collect the order, the item can be marked as picked up using Lightspeed Retail (X-Series), or you can mark the sale as fulfilled (PICKED_UP), by creating a fulfillment with the fulfillments API.

POST https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/sales/:sale_id/fulfill

{
	"fulfillment_type": "PICKED_UP"
}

This will return a response with status PICKED_UP along with the line items that are picked up.

{
  "data": {
    "status": "PICKED_UP",
	...
    "line_items": [
      {
        "id": "1869056896111226880",
        "product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
        "quantity": "1"
      }
    ]
  }
}

The sale will be marked as "PICKED_UP_CLOSED". This can be confirmed by looking up the sale.

GET https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/sales/:sale_id

{

	"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
	"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
	"outlet_id": "02e60bb7-8d62-11e9-f4c2-b314f6a052d1",
	"status": "PICKED_UP_CLOSED",
	...
	"line_items": [{
		"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
		"quantity": 1,
		"price": 12,
		"tax": 1.8,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		...
	}]
}

API Workflow - Delivery

Create a sale with the following fields:

  • "status": "AWAITING_DISPATCH"
  • "register_id": the id of a register at the outlet specified above. For example, the retailer might have a specific 'online' register that is used for delivery orders.
  • "fulfillment_details": the details or notes for this fulfillment sale. This cannot be modified after the fulfillment is created. Optional.
  • For each product in "register_sale_products":
    • "product_id": the id of the product being sold in this line item.
    • "fulfillment_type": the method of fulfillment for this line item. Use "DISPATCH" if this item is to be delivered up later. Otherwise, omit this field if the item is to be taken immediately.

POST https://<<domain_prefix>>.retail.lightspeed.app/api/register_sales

{
	"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
	"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
	"outlet_id": "02e60bb7-8d62-11e9-f4c2-b314f6a052d1",
	"status": "AWAITING_DISPATCH",
	"fulfillment_details": [{
        "type": "DISPATCH",
        "note": "here is my delivery fulfillment note"
    }],
	...
	"register_sale_products": [{
		"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
		"quantity": 1,
		"price": 12,
		"tax": 1.8,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		"fulfillment_type": "DISPATCH",
		...
	}]
}

Once the order has been picked and sent for delivery, the item can be marked as picked up using Lightspeed Retail (X-Series), or you can mark the sale as fulfilled (SHIPPED), by creating a fulfillment with the fulfillments API.

POST https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/sales/:sale_id/fulfill

{
	"fulfillment_type": "SHIPPED"
}

This will return a response with status SHIPPED along with the line items that are shipped.

{
  "data": {
	"status": "SHIPPED",
	...
    "line_items": [
      {
        "id": "1869054268111335424",
        "product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
        "quantity": "1"
      }
    ]
  }
}

The sale will be marked as "DISPATCHED_CLOSED". This can be confirmed by looking up the sale.

GET https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/sales/:sale_id

{

	"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
	"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
	"outlet_id": "02e60bb7-8d62-11e9-f4c2-b314f6a052d1",
	"status": "DISPATCHED_CLOSED",
	...
	"line_items": [{
		"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
		"quantity": 1,
		"price": 12,
		"tax": 1.8,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		...
	}]
}

Retrieving fulfillments

You can also fetch fulfillments by sale id (if needed):

GET https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/sales/:sale_id/fulfillments

Updated about 9 hours ago