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:

Click and Collect
Deliver from Store

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:

Customer places an order on retailer's e-commerce site
Customer selects either the 'pick up in store' or 'delivery' option
Retailer receives the order and picks and packs the inventory for the customer
The customer either comes to the store to collect their order or the retailer ships the order to them
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",
		...
	}]
}

Identifying sales with fulfillments

When retrieving sales using the List Sales endpoint and when retrieving a sale by ID using the Get a single sale endpoint, sales with associated fulfillments have the pickup or delivery attribute in the attributes array.

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

Get a single sale: GET https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/sales/:sale_id

Retrieving fulfillments

To retrieve completed (i.e. fulfilled) fulfillments for a sale, use the List Sale Fulfillments endpoint:

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

To retrieve unfulfilled fulfillments for a sale, use the List Sale Pick Lists endpoint:

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

You can correlate the items returned by List Sale Pick Lists endpoints to the sale line items using the line_items.sale_line_item_id field. Any line items that appear in the sale but not in the sale pick lists were taken by the customer at the time of sale.