Handling POS cart app extension endpoints

This guide contains example endpoint calls to help you integrate your app with the POS cart app extension.

Handling the promotions API call

The promotions API call is made any time a new order is started in empty cart state, or when the customer value on the cart changes. If the customer_id field is missing from the request, then no customer has been added and only promotions that apply to all customers should be returned.

HTTP request

POST https://myapp.com/pos-extension-api/promotions

{
  "customer_id": 1,
  "locale": "en",
  "supported_templates": [
    "simple_action_list"
  ],
  "supported_actions": [
    "flat_discount",
    "percent_discount",
    "add_variant"
  ],
  "currency_code": "USD",
  "shop_id": 1,
  "shopify_domain": "shopify-domain.myshopify.com"
}

Expected HTTP status response:

  • 200 - OK

See the POS cart app extension reference for a description of each field.

App response

{
  "type": "simple_action_list",
  "points_label": "Point balance",
  "points_balance": "23867",
  "actions": [
    {
      "type": "flat_discount",
      "title": "Add $5.00 discount",
      "description": "-1000 points",
      "action_id": "123ABC",
      "value": "5.00"
    }
  ]
}

The example response 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.

See the POS cart app extension reference for a description of each field.

As a result, Shopify POS renders the app card with the new template data:

Handling the perform_action API call

The perform_action API call is made any time a POS staff member applies one of the actions that was returned in the promotions API call. The action_id field indicates which action was performed.

HTTP request

POST https://myapp.com/pos-extension-api/perform_action

{
  "action_id": "123ABC",
  "customer_id": 1,
  "locale": "en",
  "supported_templates": [
    "simple_action_list"
  ],
  "supported_actions": [
    "flat_discount",
    "percent_discount",
    "add_variant"
  ],
  "currency_code": "USD",
  "shop_id": 1,
  "shopify_domain": "shopify-domain.myshopify.com"
}'

Expected HTTP status response:

  • 200 - OK (indicates that the action was successfully processed by the partner app)

See the POS cart app extension reference for a description of each field.

App response

{
  "type": "simple_action_list",
  "points_label": "Point balance",
  "points_balance": "22867",
  "actions": []
}

In the example response, the points_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 does not redeem multiple offers in a single order.

See the POS cart app extension reference for a description of each field.

Handling the revert_action API call

The revert_action API call is made any time an action has already been taken but Shopify POS determines that the action needs to be reverted. For example, the order has been abandoned or the discount has been deleted from the cart.

HTTP request

POST https://myapp.com/pos-extension-api/revert_action

{
  "action_id": "123ABC",
  "customer_id": 1,
  "locale": "en",
  "supported_templates": [
    "simple_action_list"
  ],
  "supported_actions": [
    "flat_discount",
    "percent_discount",
    "add_variant"
  ],
  "currency_code": "USD",
  "shop_id": 1,
  "shopify_domain": "shopify-domain.myshopify.com"
}'

Expected HTTP status responses:

  • 200 - OK (indicates that the action was successfully reverted by the partner app)

See the POS cart app extension reference for a description of each field.

App response

{
  "type": "simple_action_list",
  "points_label": "Point balance",
  "points_balance": "23867",
  "actions": [
    {
      "type": "flat_discount",
      "title": "Add $5.00 discount",
      "description": "-1000 points",
      "action_id": "123ABC",
      "value": "5.00"
    }
  ]
}

In this example, 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.

See the POS cart app extension reference for a description of each field.

HTTP status responses

The following status codes should be used to handle partner 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.

Sign up for a Partner account to get started.

Sign up