Cart app extension

• You've created a development store.
• You've created an app.
• You've embedded your app in Shopify POS.

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

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

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.

The following table shows the requirements for the POS cart app extension:

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.

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.

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.

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.

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:

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.

The following example shows a request to the perform_action endpoint:

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

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.

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:

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.

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