POS product recommendations (legacy)

• You've created a development store.
• You've created an app in the Partner Dashboard or using Shopify CLI.
• You've embedded your app in Shopify POS.

You can configure the POS product recommendations extension from your Partner Dashboard.

1. Go to your Partner Dashboard.
2. In the sidebar, click Apps.
3. Click the app name.
4. Click Extensions.
5. Under Point of Sale, click the Product recommendations card.
6. Enter the URL path that will be used to build your POS product recommendations extension endpoints.
7. Click Save.
8. Create and release a new app version to make this extension available to users. You need to release a new app version whenever you update the extension configuration in the Partner Dashboard.

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:

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.

The following table shows the requirements for the POS product recommendations app extension:

All requests to the recommendations endpoint must respond within three seconds, otherwise Shopify will timeout the call and return an error to the user. This is to stop the Shopify POS experience from being slow.

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 configuring the app extension from your Partner Dashboard.

The POS product recommendations extension is based on the following three endpoints:

• recommendations
• recommendations_shown
• action_taken

See the POS product recommendation extension endpoints for more information about all of the following endpoints.

Shopify POS sends a request to your app's recommendations endpoint in response to the following actions:

• The POS user adds a product to the cart.
• The customer on the cart changes.
• The POS user views the details of a product.
• The POS user 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 user. The recommendations_shown request is sent to notify you of that event.

The following is an example request to the recommendations endpoint:

The following is an example response, which includes the chosen template type and a list of products or variants grouped with custom titles. The response 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.

The following example shows how the returned response renders:

Shopify POS sends a request to your app's recommendations_shown endpoint when the POS user 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 POS user:

The request contains the same request_uuid value that was sent with the original request to your recommendations endpoint.

The following is an example request to the recommendations_shown endpoint:

There's 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 POS user.

Shopify POS sends a request to your app's action_taken endpoint if a POS user 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 that a recommended product was sold.

The following is an example request to the action_taken endpoint:

The following is another example of this request indicating a recommended product being sold:

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.

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 Getting started with session token authentication.

• Learn about the fields that Shopify sends to your app for each of the POS product recommendations app extension endpoint calls, including the response fields and possible values for the templates and actions that your app sends to Shopify.