• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
List loyalty programs

Deprecated
Effective May 13th, 2021

Returns a list of loyalty programs in the seller's account.

Loyalty programs define how buyers can earn points and redeem points for rewards. Square sellers can have only one loyalty program, which is created and managed from the Seller Dashboard. For more information, see Loyalty Program Overview.

Replaced with RetrieveLoyaltyProgram when used with the keyword main.

Permissions
LOYALTY_READ
Guide
List loyalty programs
Deprecation date
2021-05-13
Replaced by
RetrieveLoyaltyProgram Migration guide

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
programs
LoyaltyProgram [ ]

A list of LoyaltyProgram for the merchant.

Examples

You are viewing an old version of the API
GET /v2/loyalty/programs
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/loyalty/programs \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
Response JSON 
{
  "programs": [
    {
      "id": "d619f755-2d17-41f3-990d-c04ecedd64dd",
      "status": "ACTIVE",
      "reward_tiers": [
        {
          "id": "e1b39225-9da5-43d1-a5db-782cdd8ad94f",
          "points": 10,
          "name": "10% off entire sale",
          "definition": {
            "scope": "ORDER",
            "discount_type": "FIXED_PERCENTAGE",
            "percentage_discount": "10"
          },
          "created_at": "2020-04-20T16:55:11Z",
          "pricing_rule_reference": {
            "object_id": "74C4JSHESNLTB2A7ITO5HO6F",
            "catalog_version": "1605486402527"
          }
        }
      ],
      "terminology": {
        "one": "Point",
        "other": "Points"
      },
      "location_ids": [
        "P034NEENMD09F"
      ],
      "created_at": "2020-04-20T16:55:11Z",
      "updated_at": "2020-05-01T02:00:02Z",
      "accrual_rules": [
        {
          "accrual_type": "SPEND",
          "points": 1,
          "spend_data": {
            "amount_money": {
              "amount": 100,
              "currency": "USD"
            },
            "excluded_category_ids": [
              "7ZERJKO5PVYXCVUHV2JCZ2UG",
              "FQKAOJE5C4FIMF5A2URMLW6V"
            ],
            "excluded_item_variation_ids": [
              "CBZXBUVVTYUBZGQO44RHMR6B",
              "EDILT24Z2NISEXDKGY6HP7XV"
            ],
            "tax_mode": "BEFORE_TAX"
          }
        }
      ]
    }
  ]
}

Error Descriptions
400 Bad request UNSUPPORTED_LOYALTY_REWARD_TIER

The referenced loyalty program reward tier is not supported. This could happen if the reward tier created in a first party application is incompatible with the Loyalty API.

 >
400 Bad request 
{
  "errors": [
    {
      "code": "UNSUPPORTED_LOYALTY_REWARD_TIER",
      "category": "INVALID_REQUEST_ERROR"
    }
  ]
}