Retrieving Delivery Groups via SPI

Use Point of Sale Delivery Groups SPI to retrieve shipping charges for potential shipping groupings of products in the shopping cart.

  • Modern POS App Build: 10.3.1 or greater
  • Platform Support: iPad and iPhone
  • Offline Support: no
  • Technical: turn on these Omnichannel settings
    • Enable Order Delivery Grouping
    • Allow Multiple Shipments Per Cart/Order
    • Allow Multiple Delivery and Pickup Dates Per Order
    • Allow Multiple Shipping Addresses Per Order

For details on this SPI, see Delivery Group 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.

Configure the Delivery Group Service Provider Interface (SPI) in Custom Connectors to retrieve delivery groups.

  1. In CMS, go to Integrations > Custom Connectors and select Create in the upper right.
  2. Under Connector Type, select SPI.
  3. Under Endpoint Name, select DELIVERY_GROUP.
  4. Under API Endpoint, provide the external endpoint to retrieve delivery groups.
  5. Under Integration Type, select HTTP_POST.
  6. Under JSON Headers, provide headers to be passed.
  7. Configure the rest of the fields as needed.
  8. Save your changes.

Endpoint:

The request payload includes all items in the cart. Each item has important details, such as the chosen delivery type, shipping method, number of items, price, discounts, and address information (including city, state, zip, and country). In the request, items are grouped by delivery group. A delivery group shares the same unique values for fulfillment type, address, shipping method, and delivery date.

If available, the delivery date is also included in the request. A new request is sent to update the shipping methods whenever a retail associate changes the cart. Cart changes include adding or removing items for delivery, switching the fulfillment type to “Ship to Home,” updating the recipient’s address, changing the delivery date, applying a price override, or adjusting quantities and prices.

You can also send additional attributes with the request, including information mapped to Point of Sale’s product custom fields in CMS using the Store Setting field tLogCustomProductAttributes.

For complete request and response payload examples, see the Delivery Group SPI reference documentation.

For POS app builds 10.7.1 or later, the Delivery Group SPI includes enhanced support for delivery date functionality with inventory reservation.

These enhancements introduce three new fields in the SPI response:

FieldDescription
availableDateTimeSlotListThis field is populated from the SPI response and passed to the app for display if it contains any available slots.
deliveryDatePickerOptionPossible values: DISABLED, ENABLED, or null

DISABLED: Skips both the date picker UI and the API request, regardless of whether there are available date/time slots. If no slot is selected in the app, users can continue with checkout without issues, and an empty value is sent to Point of Sale’s backend.

ENABLED or null: If the availableDateTimeSlotList is empty, the date picker API is called as usual. If there are available slots in the availableDateTimeSlotList, the date picker API is skipped, and the available slots are displayed to the user.
slotIdEach available date/time slot is assigned a unique slotId, which is passed from SPI to Point of Sale’s backend and then to the app. If a user selects a slot, the app sends the corresponding slotId back to the backend as part of the update request.

For items that support delivery date selection, the SPI response includes:

  • A flag, deliveryDatePickerOption, under deliveryGroupList with the value ENABLED
  • The availableDateTimeSlotList under deliveryGroupList
  • A slotId for each dateTimeSlot in the availableDateTimeSlotList

If eligible items are added to the cart and an address is entered, available delivery dates are fetched from the SPI based on the address provided. The selected date appears on the receipt and in the order history.

For items that don’t support delivery date selection, the SPI response includes:

  • The deliveryDatePickerOption flag under deliveryGroupList with the value DISABLED