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: `flat_discount`: The discount is applied as a flat amount in the selected currency. `percent_discount`: The discount is applied as a percentage. `add_variant`: The discount is applied as a product variant.
`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: `type`: String Type of discount. Possible values: `flat_discount`, `percent_discount`, `add_variant`. `title`: String Text that appears in Shopify POS describing the action to be taken. `description`: String Text that appears in Shopify POS describing the action to be taken in smaller grey font below the `title` text. `action_id`: String The same `action_id` that was returned in the response to the `promotions` endpoint call. `value`: String Value that will be applied for the `type` of discount. For `flat_discount` actions, the `value` can be any valid currency amount (for example, "4.95" for $4.95). For `percent_discount` actions, the `value` must be between "0.0" and "1.0" (for example, "0.5" for 50%). For `add_variant` actions, the `value` must be a variant ID.

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_id can’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.

Next steps

Anchor link to section titled "Next steps"

Learn how to implement the POS cart app extension.