List Member Promotions

get

https://{Host}/v3/members/{memberId}/promotions

Recent Requests

Log in to see full request history

Time	Status	User Agent
Retrieving recent requests…

Loading…

Returns a paginated list of loyalty promotions associated with a specific member. Use the optional query parameter filters to narrow results by enrolment status, promotion identifier, or promotion ID.

Example request

curl -X GET "https://{host}/v3/members/{memberId}/promotions?page=0&size=10" \
  -H "Authorization: Basic {token}"

Prerequisites

Authentication: Basic authentication. Provide a valid Authorization header.
Default access group.

Resource information


Pagination	Yes
Batch support	No

Path parameters

Field	Type	Required	Description
`memberId`	Long	Yes	Unique customer identifier of the member.

Query parameters

Field	Type	Required	Description
`page`	Integer	Optional	Page number for pagination (0-indexed). Defaults to `0`.
`size`	Integer	Optional	Number of promotions to return per page. For example, if there are 37 total promotions and `size` is 10, the first page returns 10 promotions. Defaults to `10`. The maximum supported value is `50`.
`memberEnrollmentStatus`	String	Optional	Filters promotions by the member's enrolment status. Supported values: `PENDING_ENROLLMENT`, `PENDING_OPT_IN`, `AVAILABLE_TO_REDEEM`, `REDEEMED`, `EXPIRED`. Case-sensitive.
`promotionIdentifier`	String	Optional	Filters by the promotion's unique string identifier. The identifier must resolve to a promotion in `ACTIVE`, `PAUSED`, or `STOPPED` state.
`promotionId`	Integer	Optional	Filters by the promotion's numeric ID. The promotion must be in `ACTIVE`, `PAUSED`, or `STOPPED` state.
`includeActivitySummary`	Boolean	Optional	When `true`, each promotion in the response also includes an `activitySummaries` breakdown of benefits the member has earned from that promotion's activities. Defaults to `false`. Only supported on this listing endpoint — not available on the single promotion view endpoint.

API Quick Reference

GET /v3/members/{memberId}/promotions
   └─ Response
       ├─ pageDetails (object)
       │   ├─ pageNumber (number)
       │   ├─ pageSize (number)
       │   ├─ totalEntries (number)
       │   └─ pageCount (number)
       ├─ memberId (number)
       └─ promotions []
           ├─ promotionId (number)
           ├─ promotionName (string)
           ├─ programId (number)
           ├─ startDateISO (string)
           ├─ endDateISO (string)
           ├─ timezoneName (string)
           ├─ promotionIdentifier (string)
           ├─ description (string)
           ├─ promotionType (string)
           ├─ loyaltyEarningType (string)
           ├─ active (boolean)
           ├─ latestOptInDateISO (string)
           ├─ latestOptOutDateISO (string)
           └─ activitySummaries []
               ├─ activityId (string)
               ├─ activityName (string)
               └─ benefitsEarned []
                   ├─ type (string)
                   ├─ value (string)
                   ├─ earnedOn (string)
                   └─ eventLogId (string)

Example response

{
  "pageDetails": {
    "pageNumber": 0,
    "pageSize": 10,
    "totalEntries": 37,
    "pageCount": 4
  },
  "memberId": 388757626,
  "promotions": [
    {
      "promotionId": 126779,
      "promotionName": "UAT ULP - Updating enrolment type using API",
      "programId": 973,
      "startDateISO": "2026-03-18T06:11:00Z",
      "endDateISO": "2026-03-19T06:11:59Z",
      "timezoneName": "Indian/Maldives",
      "promotionIdentifier": "f385f258-c315-412c-b910-7bd8a8d89427",
      "description": "UAT ULP - Updating enrolment type using API",
      "promotionType": "LOYALTY_EARNING",
      "loyaltyEarningType": "DIRECT_EARN",
      "active": true,
      "latestOptInDateISO": "2026-03-18T06:22:40Z",
      "latestOptOutDateISO": "2026-03-18T06:22:28Z"
    },
    {
      "promotionId": 126635,
      "promotionName": "Single Activity Promotion2",
      "programId": 973,
      "startDateISO": "2026-03-01T05:11:00Z",
      "endDateISO": "2026-03-31T05:11:59Z",
      "timezoneName": "Asia/Kolkata",
      "promotionIdentifier": "single-activity-promotion2",
      "description": "A promotion with single activity",
      "promotionType": "GENERIC",
      "active": true
    }
  ]
}

{
  "pageDetails": {
    "pageNumber": 0,
    "pageSize": 10,
    "totalEntries": 37,
    "pageCount": 4
  },
  "memberId": 388757626,
  "promotions": [
    {
      "promotionId": 126779,
      "promotionName": "UAT ULP - Updating enrolment type using API",
      "programId": 973,
      "startDateISO": "2026-03-18T06:11:00Z",
      "endDateISO": "2026-03-19T06:11:59Z",
      "timezoneName": "Indian/Maldives",
      "promotionIdentifier": "f385f258-c315-412c-b910-7bd8a8d89427",
      "description": "UAT ULP - Updating enrolment type using API",
      "promotionType": "LOYALTY_EARNING",
      "loyaltyEarningType": "DIRECT_EARN",
      "active": true,
      "latestOptInDateISO": "2026-03-18T06:22:40Z",
      "latestOptOutDateISO": "2026-03-18T06:22:28Z",
      "activitySummaries": [
        {
          "activityId": "592b840e-9ced-4f7c-8692-35189c3428ae",
          "activityName": "Activity 1",
          "benefitsEarned": [
            {
              "type": "REGULAR_POINTS",
              "value": "10",
              "earnedOn": "2026-03-18T06:25:51Z",
              "eventLogId": "823456789"
            }
          ]
        }
      ]
    },
    {
      "promotionId": 126635,
      "promotionName": "Single Activity Promotion2",
      "programId": 973,
      "startDateISO": "2026-03-01T05:11:00Z",
      "endDateISO": "2026-03-31T05:11:59Z",
      "timezoneName": "Asia/Kolkata",
      "promotionIdentifier": "single-activity-promotion2",
      "description": "A promotion with single activity",
      "promotionType": "GENERIC",
      "active": true
    }
  ]
}

Response parameters

Field	Type	Description
`pageDetails`	Object	Object containing pagination metadata for the response.
`.pageNumber`	Integer	The zero-based index of the current page in the result set.
`.pageSize`	Integer	The number of promotions returned in the current page of results.
`.totalEntries`	Integer	The total count of promotions matching the specified filters across all pages.
`.pageCount`	Integer	The total number of pages available at the specified page size.
`memberId`	Long	Unique identifier of the member whose promotions are being retrieved.
`promotions`	Array	The list of promotions the member is enrolled in or eligible to participate in.
`.promotionId`	Long	Unique identifier for the promotion.
`.promotionName`	String	The display name of the promotion.
`.programId`	Integer	The unique identifier of the loyalty program under which this promotion operates.
`.startDateISO`	String (date-time)	Indicates the promotion's start date and time in ISO 8601 format, returned in the server time zone. EU server example: 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example: 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
`.endDateISO`	String (date-time)	Indicates the promotion's end date and time in ISO 8601 format, returned in the server time zone. EU server example: 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example: 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
`.timezoneName`	String	IANA time zone name that governs how the promotion's start, end, and opt-in dates are evaluated and displayed.
`.promotionIdentifier`	String	The human-readable identifier used to reference the promotion across systems, distinct from the system-generated ID.
`.description`	String	The text describing the promotion's offer and key benefits to the member.
`.promotionType`	String	The category of the promotion. Possible values: `GENERIC`: benefits are provided directly once the customer meets the promotion's requirements, `LOYALTY`: the promotion is issued to the customer based on prior behavior or transactions, and benefits are provided once the customer meets the criteria on a later transaction, `LOYALTY_EARNING`: the customer is enrolled, the promotion is then issued based on specific criteria, and the customer earns the benefit by meeting the issued promotion's requirements.
`.loyaltyEarningType`	String	The earning sub-type for `LOYALTY_EARNING` promotions. Possible values: `DIRECT_EARN`: the customer earns the benefit directly from a qualifying transaction, with no separate opt-in step, `ISSUE_AND_EARN`: the customer can opt in multiple times within the enrolment window, earning the benefit on each qualifying opt-in. Present only when set; absent for other `promotionType` values.
`.active`	Boolean	Indicates if the promotion is currently eligible for member enrollment and participation.
`.latestOptInDateISO`	String (date-time)	The member's most recent opt-in date and time for this promotion, in ISO 8601 format, returned in the server time zone. EU server example: 2025-12-16T14:30:45Z → 16 December 2025, 14:30:45 (UTC) India server example: 2025-12-16T14:30:45+05:30 → 16 December 2025, 14:30:45 (IST) Present only if the member has opted in to this promotion at least once.
`.latestOptOutDateISO`	String (date-time)	The member's most recent opt-out date and time for this promotion, in ISO 8601 format, returned in the server time zone. Same server-time-zone behavior as `latestOptInDateISO`. Present only if the member has opted out of this promotion at least once.
`.activitySummaries`	Array	Per-activity breakdown of benefits the member has earned from this promotion. Present only when the request includes `includeActivitySummary=true` and the member has earned at least one benefit on this promotion.
`..activityId`	String	Unique identifier of the activity within the promotion.
`..activityName`	String	Display name of the activity.
`..benefitsEarned`	Array	The benefits the member has earned from this activity, most recent first. Benefits that have been fully returned or reversed are excluded.
`...type`	String	Category of the benefit earned. Possible values: `REGULAR_POINTS`, `TRACKERS`, `PROMISED_POINTS`, `EXTERNAL_TRIGGER_BASED_POINTS`, `ALTERNATE_CURRENCIES`.
`...value`	String	The amount of the benefit earned.
`...earnedOn`	String (date-time)	Indicates when the benefit was earned, in ISO 8601 format, returned in the server time zone. Same server-time-zone behavior as `latestOptInDateISO`.
`...eventLogId`	String	The event transaction ID that generated this benefit.

Error and warning codes

Code	Type	Description
310192	Error	Member not found for the given `memberId`. Provide a valid member identifier.
310193	Error	No `ACTIVE`, `PAUSED`, or `STOPPED` promotion found for the given `promotionIdentifier`.
310194	Error	No `ACTIVE`, `PAUSED`, or `STOPPED` promotion found for the given `promotionId`.
310195	Error	`size` exceeds the maximum allowed limit of 50. Note: The API's own error message currently states the limit as 20 — the actual enforced maximum is 50.
310196	Error	Invalid value for `memberEnrollmentStatus`. Must be one of: `PENDING_ENROLLMENT`, `PENDING_OPT_IN`, `AVAILABLE_TO_REDEEM`, `REDEEMED`, `EXPIRED`. Case-sensitive.
500	Error	Internal server error. Retry the request after a short delay.

Response

Language

Credentials

Basic

base64

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json