Cart app extension
Shopify merchants can use apps to manage loyalty programs and discounts for Shopify Point of Sale (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.
RequirementsAnchor link to section titled "Requirements"
- You've created a development store.
- You've created an app.
- You've embedded your app in Shopify POS.
Configure the app extensionAnchor link to section titled "Configure the app extension"
You can configure the POS cart app extension from your Partner Dashboard.
- From your Partner Dashboard, click Apps.
- Click the name of your app.
- Click Extensions.
- Under Point of Sale, click the POS cart card.
- Enter the URL path that will be used to build your POS cart app extension endpoints.
- 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 endpointsAnchor link to section titled "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 requirementsAnchor link to section titled "Endpoint requirements"
The following table shows the requirements for the POS cart app extension:
|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 requestsAnchor link to section titled "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 endpointAnchor link to section titled "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 architectureAnchor link to section titled "App extension architecture"
The POS cart app extension is based on the following three endpoints:
See the POS cart app extension endpoints for more information about all of the following endpoints.
The promotions endpointAnchor link to section titled "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.
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:
The perform_action endpointAnchor link to section titled "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.
The following example shows a request to the
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.
The revert_action endpointAnchor link to section titled "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.
The following example shows a request to the
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 verificationAnchor link to section titled "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.
- 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.