Using the POS cart app extension

Overview

Shopify merchants can use apps to manage loyalty programs and discounts for Shopify POS. You can add the POS cart app extension to your app so that merchants can quickly and easily manage loyalty points and apply discounts directly to the cart from within Shopify POS.

Configure the app extension from your Partner Dashboard

You can configure the app extension from your Partner Dashboard.

Steps:

  1. From your Partner Dashboard, click Apps.
  2. Click the name of the app that you want to change.
  3. Click Extensions.
  4. Click Point of Sale.
  5. In the POS cart section, click Manage POS cart.
  6. Enter the URL path that will be used to build your POS cart app 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 will uses the following endpoints:

https://myapp.com/pos-extension-api/promotions
https://myapp.com/pos-extension-api/perform_action
https://myapp.com/pos-extension-api/revert_action

Create the endpoints

Before your app can receive communication from Shopify through an app extension, you need to host a series of standardized API endpoints on your app's primary domain. These endpoints are called when your app extension is rendered and when there's a related action requested from your app.

Endpoint requirements

The requirements for the POS cart app extension are as follows:

rule/concern type/requirement
API format REST
Content type JSON
Security mechanism HMAC/Signed requests. See Using webhooks to learn how to verify a webhook created through the API.
Protocol HTTPS (app domain requires valid SSL certificate)

Responding to requests

All endpoints must respond within three seconds, otherwise Shopify will timeout the call and return an error to the merchant. This is to prevent merchants having a slow experience in Shopify POS.

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. This is done when setting up the app extension in the Partner Dashboard.

App extension architecture

The POS cart app extension is based on three endpoints:

  • promotions
  • perform_action
  • revert_action

See the POS cart app extension endpoints for more information about all of the endpoints shown below.

The promotions endpoint

When a new order is started in Shopify POS (i.e. the cart is empty) or the customer on the cart changes, Shopify sends a request to your app's promotions endpoint. This request contains the supported templates and actions that your app can use when returning data to Shopify. Your app's response includes the chosen template, the customer's loyalty points, and any applicable actions. Each action is a promotion that can be applied to the cart.

A sample request to the promotions endpoint can be found below:

{
  "shop_id": 1234,
  "customer_id": 5678,
  "supported_templates": [
    "simple_action_list"
  ],
  "supported_actions": [
    "flat_discount",
    "percent_discount",
    "add_variant"
  ],
  "currency_code": "USD",
  "locale": "en-us"
}

An example response can be found below, which includes a template type, information about the customer's points, and the applicable actions. The action in the response applies a flat $5 discount to the customer's order.

{
    "type": "simple_action_list",
    "points_label": "Points balance",
    "points_balance": "23867",
    "actions": [
      {
        "type": "flat_discount",
        "title": "Add $5.00 discount",
        "description": "-1000 points",
        "action_id": "123ABC",
        "value": "5"
      }
    ]
  }

The sample returned response renders as follows:

The perform_action endpoint

After your app has returned the template and actions array, Shopify POS renders the information and the merchant can tap a promotion to apply it to the cart. The performed action is sent to Shopify, which proxies the action to your app's perform_action endpoint. The request contains the action_id field to properly identify the action.

A sample request to the perform_action endpoint can be found below:

{
  "action_id": "123ABC",
  "customer_id": 5678,
  "locale": "en",
  "supported_templates": [
    "simple_action_list"
  ],
  "supported_actions": [
    "flat_discount",
    "percent_discount",
    "add_variant"
  ],
  "currency_code": "USD",
  "shop_id": 1234
}

In the example response below, the points_balance field is reduced from "23867" to "22867" since the applied discount cost 1000 points. The actions array is empty because in this example the customer does not redeem multiple offers in a single order.

{
  "type": "simple_action_list",
  "points_label": "Point balance",
  "points_balance": "22867",
  "actions": []
}

The revert_action endpoint

After a successful call to your app's perform_action endpoint, it's possible for the action to be reverted. For example, the order could be abandoned or the discount deleted from the cart. In these cases, Shopify sends a request to your app's revert_action endpoint with the ID of the action to be reverted.

A sample request to the revert_action endpoint can be found below:

{
  "action_id": "123ABC",
  "customer_id": 5678,
  "locale": "en",
  "supported_templates": [
    "simple_action_list"
  ],
  "supported_actions": [
    "flat_discount",
    "percent_discount",
    "add_variant"
  ],
  "currency_code": "USD",
  "shop_id": 1234
}

In the example below, after the discount action is reverted, the points balance is increased back to the original value of "23867", and the discount action becomes available to the customer again:

{
  "type": "simple_action_list",
  "points_label": "Point balance",
  "points_balance": "23867",
  "actions": [
    {
      "type": "flat_discount",
      "title": "Add $5.00 discount",
      "description": "-1000 points",
      "action_id": "123ABC",
      "value": "5.00"
    }
  ]
}

Implement verification

App extension requests by Shopify can be verified by calculating a digital signature.

Each request includes a base64-encoded X-Shopify-Hmac-SHA256 header, which is generated using the app's shared secret along with the data sent in the request.

To verify that the request came from Shopify, compute the HMAC digest and compare it to the value in the X-Shopify-Hmac-SHA256 header. If they match, you can be sure that the app extension request was sent from Shopify.

For more information see Using webhooks to learn how to verify a webhook created through the API. This is the same procedure to be followed for app extensions.

Additional Resources