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

1. From your Partner Dashboard, click Apps.
2. Click the app name.
3. Click Extensions.
4. Click Shopify POS.
5. Click Manage POS product recommendations.
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:

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:

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 your app using session tokens.

Additional Resources

• POS overview
• POS product recommendations app extension reference