Using the POS product recommendations app extension
Overview
You can add the POS product recommendations extension to your app so that merchants can quickly and easily access product recommendations from within Shopify POS. Product recommendations are displayed in the smart grid after a product or customer is added to a cart. Recommendations can also be accessed when viewing a customer profile or product details.
Configure the app extension from your Partner Dashboard
- From your Partner Dashboard, click Apps.
- Click the app name.
- Click Extensions.
- Click Shopify POS.
- Click Manage POS product recommendations.
- Enter the URL path that will be used to build your POS product recommendations extension endpoints.
- Click Save.
For example, if your app's base URL is https://myapp.com
and your URL path
is pos-extension-api
, then the extension uses the following endpoints:
https://myapp.com/pos-extension-api/recommendations
https://myapp.com/pos-extension-api/recommendations_shown
https://myapp.com/pos-extension-api/action_taken
Create the endpoints
Before your app can communicate with Shopify through the app extension, you need to host standardized API endpoints on your app's primary domain. These endpoints are called when Shopify POS performs a related action.
Endpoint requirements
The requirements for the POS product recommendations app extension are as follows:
rule/concern | type/requirement |
---|---|
API format | REST |
Request Method | POST |
Content type | JSON |
Security mechanism | Session token. The session token is provided in an AUTHORIZATION header on every request. The token allows you to verify that the request came from Shopify, and provides you with the domain of the shop that is making this request. |
Protocol | HTTPS (app domain requires valid SSL certificate) |
Responding to requests
All requests to the recommendations
endpoint must respond within three seconds, otherwise Shopify will timeout the call and return an error to the merchant.
This is to stop the Shopify POS experience from being slow.
Base endpoint
Your app needs to support three API endpoint calls for the POS cart app extension. To do this, you need to provide a path segment that is appended to the app's base URL to form the complete URL called by Shopify. You can add the path segment by setting up the app extension in the Partner Dashboard.
App extension architecture
The POS product recommendations extension is based on three endpoints:
recommendations
recommendations_shown
action_taken
See the POS product recommendation extension endpoints for more information about all of the endpoints shown below.
The recommendations endpoint
Shopify POS sends a request to your app's recommendations
endpoint in response to the following actions:
- The merchant adds a product to the cart.
- The customer on the cart changes.
- The merchant views the details of a product.
- The merchant views a customer profile.
The request contains the supported templates that your app can use when returning data to Shopify. Your app's response includes the template you choose, and the required data to populate that template in Shopify POS. A request to the recommendation endpoint doesn't mean that the recommendations are displayed to the merchant. The recommendations_shown
request is sent to notify you of that event.
A sample request to the recommendations
endpoint:
{
"request_uuid": "b6fb9cf1-92fd-4ef5-888e-cfe5fb795d75",
"surface": "cart",
"customer_id": 1234,
"elements": [
{
"product_id": 456,
"variant_id": null
},
{
"product_id": 789,
"variant_id": 333
},
],
"supported_templates": ["grouped_product_variant_list"],
"locale": "en-us"
}
An example response can be found below, which includes the chosen template type and a list of product or variants grouped with custom titles. The response here provides recommendations under a "Frequently bought together" group and a "Related products" group. The titles of these groups can be set to whatever you choose.
{
"template": "grouped_product_variant_list",
"title": "3 recommended products",
"groups": [
{
"title": "Frequently bought together",
"elements": [
{
"product_id": 999,
"variant_id": null
},
{
"product_id": 987,
"variant_id": 444
}
]
},
{
"title": "Related products",
"elements": [
{
"product_id": 654,
"variant_id": null
}
]
}
]
}
The sample returned response renders as follows:
The recommendations_shown endpoint
Shopify POS sends a request to your app's recommendations_shown
endpoint when the merchant taps on the recommendations tile on the smart grid, customer profile or product details.
This request corresponds to the full list of recommendations being shown to the merchant:
The following request contains the same request_uuid
value that was sent with the original request to your recommendations
endpoint.
A sample request to the recommendations_shown
endpoint can be found below:
{
"request_uuid": "b6fb9cf1-92fd-4ef5-888e-cfe5fb795d75",
}
There is no need for you to provide a response to this request. Its purpose is to let you know if and when your recommendations are shown to the merchant.
The action_taken endpoint
Shopify POS sends a request to your app's action_taken
endpoint if a merchant adds one of your recommended products to a cart, and also if that cart results in a completed sale.
The request contains the same request_uuid
value that was sent to your recommendations
endpoint with the original request . It also contains an action
field to indicate that Shopify POS is notifying you of a product being added to cart or a recommended product was sold.
A sample request to the action_taken
endpoint:
{
"request_uuid": "b6fb9cf1-92fd-4ef5-888e-cfe5fb795d75",
"action": "added_to_cart",
"elements": [
{
"product_id": 987,
"variant_id": 444,
}
]
}
Here is another example of this request indicating a recommended product being sold:
{
"request_uuid": "b6fb9cf1-92fd-4ef5-888e-cfe5fb795d75",
"action": "order_created",
"order_id": 654
}
There's no need for you to provide a response to this request. Its purpose is to let you know if and when your recommended products are added to a cart and sold.
Implement verification
To verify that app extension requests have come from Shopify, validate the session token that's provided in the AUTHORIZATION
header on every request. To learn more, refer to Authenticate an embedded app using session tokens.