You are viewing an old version of the API

All Versions

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).

Permissions

LOYALTY_READ

Guide

List loyalty promotions Try in API Explorer

Path Parameters

Example code

Name	Description
`program_id string` Required	The ID of the base loyalty program. To get the program ID, call RetrieveLoyaltyProgram using the `main` keyword.

Query Parameters

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

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

curl https://connect.squareup.com/v2/loyalty/programs/d619f755-2d17-41f3-990d-c04ecedd64dd/promotions \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/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"
      },
      "qualifying_item_variation_ids": [
        "CJ3RYL56ITAKMD4VRCM7XERS",
        "AT3RYLR3TUA9C34VRCB7X5RR"
      ],
      "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"
      },
      "qualifying_category_ids": [
        "XTQPYLR3IIU9C44VRCB3XD12"
      ],
      "status": "ENDED",
      "created_at": "2022-06-27T15:37:38Z",
      "updated_at": "2022-06-27T15:37:38Z",
      "loyalty_program_id": "d619f755-2d17-41f3-990d-c04ecedd64dd"
    }
  ]
}