POS cart app extension reference
This reference describes the fields that Shopify sends to your app for each of the Point of Sale (POS) cart app extension endpoint calls. The reference also includes the response fields and possible values for the templates and actions that your app sends to Shopify.
Request fields
Anchor link to section titled "Request fields"The following fields are sent from Shopify to your app for each endpoint call:
| Name | Type | Required | Value |
|---|---|---|---|
shop_id |
Number | ✓ | Shopify's unique identifier for the shop. |
shopify_domain |
String | ✓ | The shop's domain ending in myshopify.com. |
customer_id |
Number | Shopify's unique identifier for the customer. If both customer_id and customer_email are blank, then your app should return only promotions that apply to all customers. |
|
customer_email |
String | The customer's email address. If both customer_id and customer_email are blank, then your app should return only promotions that apply to all customers. |
|
locale |
String | ✓ | Used to translate any textual data into the correct language for the POS staff member. Example values: en-US, en. |
currency_code |
String | ✓ | Used to determine the correct amount in the case of a flat_discount action. |
supported_templates |
Array | ✓ | Defines a set of data and how that data is rendered in the POS client. Possible values: ["simple_action_list"]. |
supported_actions |
Array | ✓ | Defines the possible set of actions that can be taken by the user. Possible values:
|
action_id |
String | ✓ | Value generated by the app to uniquely identify a discount or promotion and sent to the app server as part of the perform_action and revert_action endpoint calls. When an order is created the action_id is included as a note_attribute property of the Order resource, and included in the orders/create webhook in the following format: "note_attributes": [{ "name": "cart-promotion-actions", "value": "[(\"your_app_id\", \"action_id\")]" }] |
Response fields
Anchor link to section titled "Response fields"In response to the JSON object described above, your app returns the templates and actions specific to the destination endpoint (promotions, perform_action, revert_action).
The simple_action_list template
Anchor link to section titled "The simple_action_list template"In response to the supported_templates field in the request, your app can return the simple_action_list template. The values in the template are rendered as part of the POS UI card, as described in the table below.
| 1. | Header |
|---|---|
| 2. | Points label |
| 3. | Points balance |
| 4. | Actions list |
If both points_label and points_balance are present, then the points will be rendered in between the header and the actions list. If either or both of points_label or points_balance are missing, then the points row is not rendered and the actions list appears directly below the header.
The template includes the following fields:
| Name | Type | Required | Value |
|---|---|---|---|
type |
String | ✓ | Type of supported_templates. Must match one of the values in the request. |
points_label |
String | Text label that appears next to the amount of points in Shopify POS (for example, "Point balance" or "Store credit"). |
|
points_balance |
String | Any string value representing the customer's balance (for example, "$10.50" in store credit or "1000" loyalty points). |
|
actions |
Array | ✓ | An array of action objects. Each object has the following fields:
|
HTTP status responses
Anchor link to section titled "HTTP status responses"The following status codes should be used to handle app errors for the perform_action and revert_action requests:
- 404 - The
action_idcan’t be found. - 500 - The request could not be processed for any other reason.
This reference describes the fields that Shopify sends to your app for each of the different endpoint calls. The reference also includes the response fields and possible values for the templates and actions that your app sends to Shopify.
- Learn how to implement the POS cart app extension.