We're constantly trying to improve your support experience, and your feedback is extremely valuable to us.

Please take a moment to tell us about your experience today.
Sign up for future Help Center user research studies.

POS cart app extension reference

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.

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 merchant. 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: "cart-promotion-actions" : [ { "your_app_id" : "action_id" } ]

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

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.

Next steps

Sign up for a Partner account to get started.

Sign up