Cart app extension

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.

Requirements

Configure the app extension

You can configure the POS cart app extension from your Partner Dashboard.

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

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

rule/concern type/requirement
API format REST
Content type JSON
Security mechanism HMAC/Signed requests. See 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 configuring the app extension from your Partner Dashboard.

App extension architecture

The POS cart app extension is based on the following three endpoints:

  • promotions
  • perform_action
  • revert_action

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

The promotions endpoint

When a new order is started in Shopify POS (for example, 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.

promotions endpoint

The following example shows a request to the promotions endpoint:

The following example 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.

The following example shows how the returned response renders:

Returned Discount

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 identify the action properly.

perform_action endpoint

The following example shows a request to the perform_action endpoint:

In the following example response, 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 doesn't redeem multiple offers in a single order.

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.

revert_action endpoint

The following example shows a request to the revert_action endpoint:

In the following example response, 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:

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, then you can be sure that the app extension request was sent from Shopify.

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

Next steps

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