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

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

GET /v2/loyalty/programs/{program_id}/promotions

Lists the loyalty promotions associated with a loyalty program.

Results are sorted by the created_at date in descending order (newest to oldest).

Name Description
program_id
string

Required

The ID of the base loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the main keyword.

Name Description
status
string

The status to filter the results by. If a status is provided, only loyalty promotions with the specified status are returned. Otherwise, all loyalty promotions associated with the loyalty program are returned.

cursor
string

The cursor returned in the paged response from the previous call to this endpoint. Provide this cursor to retrieve the next page of results for your original request. For more information, see Pagination.

limit
integer (32-bit)

The maximum number of results to return in a single paged response. The minimum value is 1 and the maximum value is 30. The default value is 30. For more information, see Pagination.

Response Fields

Name Description
errors
Error [ ]

Any errors that occurred during the request.

loyalty_promotions
LoyaltyPromotion [ ]

The retrieved loyalty promotions.

cursor
string

The cursor to use in your next call to this endpoint to retrieve the next page of results for your original request. This field is present only if the request succeeded and additional results are available. For more information, see Pagination.

Examples

You are viewing an old version of the API
GET /v2/loyalty/programs/{program_id}/promotions
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js
curl https://connect.squareup.com/v2/loyalty/programs/d619f755-2d17-41f3-990d-c04ecedd64dd/promotions \
  -H 'Square-Version: 2022-09-21' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
Response JSON
{
  "loyalty_promotions": [
    {
      "id": "loypromo_f0f9b849-725e-378d-b810-511237e07b67",
      "name": "Tuesday Happy Hour Promo",
      "incentive": {
        "type": "POINTS_MULTIPLIER",
        "points_multiplier_data": {
          "points_multiplier": 3
        }
      },
      "available_time": {
        "start_date": "2022-08-16",
        "time_periods": [
          "BEGIN:VEVENT\nDTSTART:20220816T160000\nDURATION:PT2H\nRRULE:FREQ=WEEKLY;BYDAY=TU\nEND:VEVENT"
        ]
      },
      "trigger_limit": {
        "times": 1,
        "interval": "DAY"
      },
      "status": "ACTIVE",
      "created_at": "2022-08-16T08:38:54Z",
      "updated_at": "2022-08-16T08:38:54Z",
      "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
    },
    {
      "id": "loypromo_e696f057-2286-35ff-8108-132241328106",
      "name": "July Special",
      "incentive": {
        "type": "POINTS_MULTIPLIER",
        "points_multiplier_data": {
          "points_multiplier": 2
        }
      },
      "available_time": {
        "start_date": "2022-07-01",
        "end_date": "2022-08-01",
        "time_periods": [
          "BEGIN:VEVENT\nDTSTART:20220704T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=MO\nEND:VEVENT",
          "BEGIN:VEVENT\nDTSTART:20220705T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=TU\nEND:VEVENT",
          "BEGIN:VEVENT\nDTSTART:20220706T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=WE\nEND:VEVENT",
          "BEGIN:VEVENT\nDTSTART:20220707T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=TH\nEND:VEVENT",
          "BEGIN:VEVENT\nDTSTART:20220701T090000\nDURATION:PT8H\nRRULE:FREQ=WEEKLY;UNTIL=20220801T000000;BYDAY=FR\nEND:VEVENT"
        ]
      },
      "trigger_limit": {
        "times": 5,
        "interval": "ALL_TIME"
      },
      "minimum_spend_amount_money": {
        "amount": 2000,
        "currency": "USD"
      },
      "status": "ENDED",
      "created_at": "2022-06-27T15:37:38Z",
      "updated_at": "2022-06-27T15:37:38Z",
      "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
    }
  ]
}