Product recommendations extension

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.

Requirements

Configure the app extension

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.

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:

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 following table shows the requirements for the POS product recommendations app extension:

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

App extension architecture

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.

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.

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 product 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:

Recommendations Preview

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:

Full Recommendations

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 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 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.

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.

Next steps