OmniChannel: Retrieving Delivery and Pickup Dates via SPI

Use the Point of Sale SPI so merchants can integrate delivery or pickup date retrieval with the Point of Sale app.

The POS app calls the SPI, requesting a list of available dates and including details such as cart products, fulfillment methods, shipping addresses, and addresses for each applicable item. The response provides an array of dates or an error message to be shown in the POS. Delivery and pickup dates can be set at the order level or for individual items in the cart.

Prerequisites

Modern POS App Build: 10.0.1 or greater
Platform Support: iPad & iPhone
Offline Support: No

For details on this SPI, see DateTimeSlot SPI in the Point of Sale reference documentation.

For a comprehensive list of Point of Sale APIs and SPIs, see Point of Sale API, SPI, and Webhook Overview.

Note

Configure Point of Sale CMS for Retrieving Delivery Dates with SPI

Integrate Point of Sale CMS with a date picker using a custom connector and SPI. In CMS, create a custom connector by specifying the endpoint name, API endpoint, integration type, and JSON headers.

In CMS, go to Integrations | Custom Connectors.
Click Create.
For Connector Type, select SPI.
For Endpoint Name, select DATE_PICKER.
For API Endpoint, enter the URL endpoint.
For Integration Type, select HTTP_POST.
Specify any JSON headers that must be passed.
Save your changes.

Example Payload Request & Response

POST/merchant/spi/sample/endpoint/sa/datetime/slots/from/external/system

Request

For single delivery or pickup dates in a cart, the SPI is called when the date picker is tapped in the cart. This call requests a list of available dates and includes details of the cart products, fulfillment methods, shipping addresses (if enabled), and addresses for each applicable item.

1{
2  "address": {
3  "addressLine1": "string",
4  "addressLine2": "string",
5  "city": "string",
6  "countryCode": "string",
7  "emailAddress": "string",
8  "firstName": "string",
9  "lastName": "string",
10  "phone": "string",
11  "postalCode": "string",
12  "state": "string",
13  "storeId": "string"
14  },
15  "datePickerType": "DELIVERY",
16  "products": [
17  {
18  "productId": "string",
19  "gtin": "string",
20  "quantity": 0
21  }
22  ],
23  "shippingMethodId": "string"
24}

Response

For single delivery or pickup dates in a cart, the response includes an array of dates or an error message to be shown in the POS. Times are optional; if none are sent, they aren’t displayed in the app. If only one date is available, it’s automatically selected. Merchants can also specify will-call for items that do not have a date available.

For multiple delivery or pickup dates in a cart, if selecting a date for all items in the cart, the app sends the full cart details to the SPI and return available dates to be applied to all items. Once a date is selected, it applies to all current line items in the cart. If selecting a date for just a single item in the cart, the app sends the full quantity of that item and return available dates that can be selected for that specific item.

1{
2  "availableDate": 0,
3  "dateTimeSlotType": "Delivery",
4  "dateTimeSlots": [
5  {
6  "availableTimeSlots": [
7  "string"
8  ],
9  "selectedTimeSlot": "09:00 - 12:00",
10  "shippingMethodId": "string",
11  "slotDate": 0,
12  "slotId": "string"
13  }
14  ],
15  "error": true,
16  "errorCode": "INTERNAL_ERROR",
17  "errorMessage": "Invalid request. Please check the request and try again.",
18  "willCallDate": {
19  "availableTimeSlots": [
20  "string"
21  ],
22  "selectedTimeSlot": "09:00 - 12:00",
23  "shippingMethodId": "string",
24  "slotDate": 0,
25  "slotId": "string"
26  }
27}