Explore APIs and data feeds powering the Buy Online Pickup in Store (BOPIS) experience.
The APIs and data feeds that connect to deliver Buy Online Pickup in Store experience.
Discover HotWax Commerce's BOPIS PDP experience enabling customers to browse all pickup store options for desired products on Shopify's PDP.
To show available pickup facilities near the customer, the latitude and longitude coordinates of the customer are required. There are two ways to obtain these coordinates:
If the customer inputs their postal code,
Use the postcodeLookup API to convert the postal code into latitude and longitude coordinates
If the customer allows access to their system location,
Obtain the latitude and longitude coordinates directly from their device
Method: POST
Request
Response
Using the latitude and longitude coordinates, call the storeLookup API to fetch all the facilities within a given distance that allow BOPIS. Note: The distance parameter is configurable to narrow down the search results. You can allow customers to input their preferred distance or set a default value.
Method: POST
Request
Response
For each store that allows BOPIS, use the checkBOPISInventory API to check the available to promise (ATP) inventory for the desired product. Display all the facilities with non-zero inventory numbers on the product detail page (PDP) for customers to select and place a BOPIS order.
Note: If a facility has 0 inventory for the product, you can still display it for the Ship-to-store PDP experience.
Method: POST
Request
Response
In case the customer's location is not available, you can display all the available store pickup locations for the product using the storeLookup API and checkInventory API. Here's how to handle this scenario:
Step 1: Call the storeLookup API without passing latitude and longitude coordinates to retrieve all facilities allowing BOPIS
Step 2: Use the facility IDs returned in the response of the storeLookup API with the checkInventory API to get the facilities having inventory for the product
Step 3: Display all the locations with non-zero inventory on the PDP
Request
Identifying In-Store Pickup Orders:
When customers add qualifying items for in-store pickup, HotWax OMS will require the order to have the line item property _pickupstore prefilled with the pickup store location.
Note: The line item property can be added by the merchant development team.
Order Download Process:
BOPIS orders placed on Shopify are downloaded into HotWax Commerce alongside regular orders via the 'New Import' job. HotWax Commerce checks the line item property and sends the order to the customer's selected pickup location without brokering. Store associates access BOPIS orders through their BOPIS fulfillment app, preparing orders for customer pickup.
{
"json": {
"query": "postcode: 10007"
}
}{
"responseHeader": {
"status": 0,
"QTime": 2,
"params": {
"json": "{\"query\":\"postcode:10007\"}"
}
},
"response": {
"numFound": 1,
"start": 0,
"numFoundExact": true,
"docs": [
{
"postcode": "10007",
"latitude": "40.713858",
"longitude": "-74.007777",
"country": "USA",
"country-code-id": "10007-USA",
"location": "40.713858,-74.007777",
"_version_": 1752733529047826432
}
]
}
}{
"viewSize": 40,
"filters": ["storeType: RETAIL_STORE"],
"point": "40.713858,-74.007777",
"distance": 50
}
{
"responseHeader": {
"status": 0,
"QTime": 5,
"params": {
"d": "50",
"pt": "40.713858,-74.007777",
"fl": "*,dist:geodist()",
"start": "0",
"json": "{\"filter\":[\"docType: STORE\",\"storeType: RETAIL_STORE\"],\"query\":\"*:*\",\"sort\":\"geodist() asc\"}",
"q.op": "AND",
"fq": "{!geofilt}",
"rows": "40",
"sfield": "latlon"
}
},
"response": {
"numFound": 3,
"start": 0,
"docs": [
{
"identifier": "STORE_15",
"country": "United States",
"docType": "STORE",
"externalId": "DC_STORE_15",
"storeName": "Facility",
"countryCode": "USA",
"city": "New York",
"latlon": "40.72,-74",
"postalCode": "10012",
"storePhone": "",
"storeCode": "STORE_15",
"docType-identifier": "STORE-STORE_15",
"stateCode": "NY",
"state": "New York",
"address1": "10 Times Square",
"storeType": "RETAIL_STORE",
"_version_": 1735068683092361221,
"dist": 0.9465923971374126
},
{
"identifier": "STORE_20",
"country": "United States",
"docType": "STORE",
"externalId": "DC_STORE_20",
"storeName": "New facility",
"countryCode": "USA",
"city": "New York",
"latlon": "40.72,-74",
"postalCode": "10012",
"storePhone": "",
"storeCode": "STORE_20",
"docType-identifier": "STORE-STORE_20",
"stateCode": "NY",
"state": "New York",
"address1": "4 Broadway",
"storeType": "RETAIL_STORE",
"_version_": 1735068683093409793,
"dist": 0.9465923971374126
},
{
"identifier": "STORE_9",
"country": "United States",
"docType": "STORE",
"externalId": "DC_STORE_9",
"storeName": "Broadway",
"countryCode": "USA",
"city": "New York",
"latlon": "40.72,-74",
"postalCode": "10012",
"storePhone": "1212555-5555",
"storeCode": "STORE_9",
"docType-identifier": "STORE-STORE_9",
"stateCode": "NY",
"state": "New York",
"address1": "540 Broadway",
"storeType": "RETAIL_STORE",
"_version_": 1735068683094458369,
"dist": 0.9465923971374126
}
]
}
}{
"filters": {
"sku": "MSH02-32-Black",
"facilityId": "STORE_15, STORE_20, STORE_9 "
}
}{
"count": "1",
"docs": [
{
"facilityId": "STORE_15",
"atp": 3.000000
},
{
"facilityId": "STORE_20",
"atp": 8.000000
},
{
"facilityId": "STORE_9",
"atp": 14.000000
},
]
}{
"viewSize": 40,
"filters": ["storeType: RETAIL_STORE"]
}Learn how to integrate Order Management System (OMS) with Marketing Automation Platforms for automated 'Ready to Pickup' email notifications.
These guidelines provide detailed steps for integrating the Order Management System (OMS) with Marketing Automation Platforms to enable the automated delivery of 'Ready to Pickup' email notifications to customers. These notifications are triggered when store staff packs the ordered items in a shipment and indicate their readiness for pickup using HotWax Commerce's BOPIS fulfillment app or Fulfillment APIs.
When store staff pack the order items and indicate their readiness for pickup, the quickShipEntireShipGroup API creates a shipment from the selected shipgroup and moves it to the "Packed" status.
sendReadyToPickupItemNotification chained event condition action (ECA) serviceWhen the shipment status is packed, the sendReadyToPickupItemNotification chained ECA service is triggered to check the order type of the shipment and the configuration for sending ready-for-pickup emails.
The chained service works for both Store pickup and Ship to store shipments. Emails are triggered when Store pickup shipments are moved to packed status and Ship to store shipments are moved to "scheduled" status. The system responsible for sending the email and order details is configured in the following Product Store setting.
Note: Additionally, this ECA service also offers the option to manually trigger the "ready to pickup" email notification. When this ECA service is triggered, it internally initiates the email for shipment process. This feature allows users to manually initiate the sending of email notifications to inform recipients that their item is ready for pickup.
The email transmission system is identified by the parameter systemMessageRemoteId, while the information to configure the email's content is specified by the templateContentId. This templateContentId enables the OMS (Order Management System) to locate and fetch the content required for composing the email.
When the marketing automation platform handles email transmission, the OMS shares the required information in JSON format, specified by the templateContentId, to the platform.
Note: If the OMS is responsible for sending the email, it incorporates the data into a preconfigured email template within its system.
After receiving the required content, the marketing automation platform personalizes the customer's email using the provided details and delivers the email to the customer.
HotWax Commerce has ready integration with Listrak, a marketing automation platform. Added below is a JSON file sample
By following these steps, you can send Ready-For-Pickup email notifications from the OMS to the marketing automation platform.
weight
The weight of the package.
Yes
weightUomId
The unit of measurement for weight (e.g., pounds, kilograms).
Yes
shipGroupSeqId
The Id of the ship group sequence.
Yes
State Name
The name of the state or region where the pickup facility is located.
Country Name
The name of the country where the pickup facility is located.
Order Name
The name or reference number of the pickup order.
Product Name
The name of the product being picked up.
Quantity
The quantity of the product being picked up.
Price
The price of the product.
Image
An image or visual representation of the product.
Subtotal
The subtotal amount for the pickup order.
GrandTotal
The grand total amount for the pickup order.
orderId
The unique identifier of the order.
Yes
setPackedOnly
A flag indicating if the shipment should only be packed. If the customer is going to pickup their order at the fulfillment location, then this should be enabled to prevent the order from being marked as shipped. Default value is 'Y' if not specified.
Yes
dimensionUomId
The unit of measurement for dimensions (e.g., inches, centimeters).
Yes
shipmentBoxTypeId
The Id of the shipment box type.
shipmentId
The Id of the shipment made.
_EVENT_MESSAGE_
The message for the event performed.
ProductStoreEmailSetting
The email settings in the Order Management System (OMS) for the product store identifier.
emailType
The type of email to be sent.
productStoreId
The Id of the product store.
subject
The subject of the email.
templateContentId
The Id of the template content.
systemMessageRemoteId
The Id of the system responsible for sending the email.
shipmentId
The Id of the shipment.
Yes
emailType
The type of the email.
Yes
First Name
The first name of the recipient.
Last Name
The last name of the recipient.
To Facility Name
The name of the facility for pickup.
Address 1
The first line of the pickup location's address.
Address 2
The second line of the pickup location's address (if applicable).
City
The city where the pickup facility is located.
Yes
{
"orderId": "10037",
"setPackedOnly": "Y",
"dimensionUomId": "DM_cm",
"shipmentBoxTypeId": "YOURPACKNG",
"weight": "1",
"weightUomId": "WT_kg",
"shipGroupSeqId": "00001"
}{
"orderId": "10037",
"setPackedOnly": "Y",
"weight": "1",
"shipmentBoxTypeId": "YOURPACKNG",
"shipGroupSeqId": "00001",
"shipmentId": "10140",
"dimensionUomId": "WT_kg",
"weightUomId": "WT_kg",
"_EVENT_MESSAGE_": "Congratulations! Shipment #10140 is ready for pickup"
}<ProductStoreEmailSetting
emailType="PRDS_READY_TO_PICKUP"
productStoreId="STORE"
subject="Ready For Pickup"
templateContentId="READY_FOR_PICKUP",
systemMessageRemoteId= NN_LISTRAK_CONFIG><service name="sendReadyToPickupItemNotification" engine="java" require-new-transaction="true" max-retry="3"
location="co.hotwax.customerservice.shipment.ShipmentServices" export="true" invoke="sendReadyToPickupItemNotification" auth="true">
<description>Send a ready to pick up item notification</description>
<attribute name="shipmentId" type="String" mode="IN"/>
<attribute name="emailType" type="String" mode="IN" optional="true" default-value="PRDS_READY_TO_PICKUP"/>
</service>const data = {
"emailAddress": "[email protected]",
"segmentationFieldValues": [
{
"segmentationFieldId": 2378294,
"value": "${originFacility.facilityName!}"
},
{
"segmentationFieldId": 2378297,
"value": "https://localhost:8443/"
},
{
"segmentationFieldId": 2378298,
"value": "${originFacility.facilityName!}"
},
{
"segmentationFieldId": 2378299,
"value": "${postalAddress.address1!}"
},
{
"segmentationFieldId": 2378300,
"value": "${postalAddress.address2!}"
},
{
"segmentationFieldId": 2378301,
"value": "${postalAddress.city!}"
},
{
"segmentationFieldId": 2378302,
"value": "${postalAddress.stateProvinceGeoId!}"
},
{
"segmentationFieldId": 2378303,
"value": "${postalAddress.postalCode!}"
},
{
"segmentationFieldId": 2378304,
"value": "${productUrl!}"
},
{
"segmentationFieldId": 2378305,
"value": "${orderItem.itemDescription!}"
},
{
"segmentationFieldId": 2378306,
"value": "${product.productName!}"
},
{
"segmentationFieldId": 2378384,
"value": "${shipmentItem.quantity!}"
},
{
"segmentationFieldId": 2378402,
"value": "${orderName!orderId}"
},
{
"segmentationFieldId": 2378403,
"value": "${partyName!}"
}
]
};