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

You are viewing an old version of the API
Retrieve loyalty program

GET /v2/loyalty/programs/{program_id}

Retrieves the loyalty program in a seller's account, specified by the program ID or the keyword main.

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.

Permissions
LOYALTY_READ
Guide
Retrieve loyalty program Try in API Explorer

Path Parameters

Example code
Name Description
program_id
string
Required

The ID of the loyalty program or the keyword main. Either value can be used to retrieve the single loyalty program that belongs to the seller.

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
program
LoyaltyProgram

The loyalty program that was requested.

Examples

You are viewing an old version of the API
GET /v2/loyalty/programs/{program_id}
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/loyalty/programs/main \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
Response JSON 
{
  "program": {
    "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"
    }
  ]
}