Fulfillments

Sales in Vend 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 Vend’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 Vend and picked and packed using Vend.

Note that this workflow can be applied to any e-commerce provider that can integrate with Vend, or any ERP provider. The key things to note are as follows:

  • You should ensure you are either managing the inventory solely using Vend or Vend’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"
  • "outlet_id": the id of the outlet which the click and collect order will be collected from.
  • "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.

POST https://{domain_prefix}.vendhq.com/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_PICKUP",
	...
	"register_sale_products": [{
		"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
		"quantity": 1,
		"price": 12,
		"tax": 1.8,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		...
	}]
}

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

POST https://{domain_prefix}.vendhq.com/api/2.0/sales/:sale_id/fulfill

{
	"fulfillment_type": "PICKED_UP"
}

This will then mark the sale itself as PICKED_UP_CLOSED

{
		
	"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",
	...
	"register_sale_products": [{
		"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"
  • "outlet_id": the id of the outlet which the delivery order will be collected from.
  • "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.

POST https://{domain_prefix}.vendhq.com/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",
	...
	"register_sale_products": [{
		"product_id": "b1d87b58-f019-11e3-a0f5-b8ca3a64f8f4",
		"quantity": 1,
		"price": 12,
		"tax": 1.8,
		"tax_id": "b1d192bc-f019-11e3-a0f5-b8ca3a64f8f4",
		...
	}]
}

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

POST https://{domain_prefix}.vendhq.com/api/2.0/sales/:sale_id/fulfill

{
	"fulfillment_type": "SHIPPED"
}

This will then mark the sale itself as DISPATCHED_CLOSED

{
		
	"register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
	"user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
	"outlet_id": "02e60bb7-8d62-11e9-f4c2-b314f6a052d1",
	"status": "DISPATCHED_CLOSED",
	...
	"register_sale_products": [{
		"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}.vendhq.com/api/2.0/sales/:sale_id/fulfillments

Future Enhancements

We’ll be making a number of enhancements to this API in future that will allow for even more omni-channel workflows as well as allowing for different fulfillment types per line item and even per item. These will enable workflows and allow you to build features on top of Vend such as endless aisle and more.