get
https://{Host}/v3/members//promotions/
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Returns the full participation history for a specific promotion for a member, including enrollment and opt-in timeline events, promotion metadata, and promotion-level custom fields. Use the optional query parameters to narrow results by enrolment status or promotion identifier, and to control how many timeline events are returned.
Example request
curl -X GET "https://{host}/v3/members/388757266/promotions/1133608813?memberEnrollmentStatus=AVAILABLE_TO_REDEEM" \
-H "Authorization: Basic dGlsbGhnXXXXXXXX"Prerequisites
- Authentication: Basic authentication. Provide a valid
Authorizationheader. - The member must exist in the org.
- The promotion must be in
ACTIVE,PAUSED, orSTOPPEDstatus.
Resource information
| Pagination | No |
| Batch support | No |
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
memberId | Long | Yes | Unique identifier of the member. |
promotionId | Long | Yes | Unique identifier of the promotion. Must resolve to an ACTIVE, PAUSED, or STOPPED promotion. |
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
memberEnrollmentStatus | String | Optional | Filters the returned participation timeline by enrollment status. Supported values: PENDING_ENROLLMENT, PENDING_OPT_IN, AVAILABLE_TO_REDEEM, REDEEMED, EXPIRED. Case-sensitive. |
promotionIdentifier | String | Optional | Filters results to a specific promotion by its unique string identifier. Must resolve to an ACTIVE, PAUSED, or STOPPED promotion, otherwise error 310193 is returned. |
timelineEventLimit | Integer | Optional | Maximum number of timeline events returned in .events, counted across all event types (ENROLLED, OPTED_IN, REVOKED_ENROLL, REVOKED_OPTIN, REDEEMED) combined, not per event type. Events are sorted newest first and truncated to this count. Defaults to 20 when omitted. There is no enforced maximum, so pass a higher value (for example timelineEventLimit=50) to retrieve a member's complete opt-in/opt-out audit trail in a single call. This endpoint does not support pagination; timelineEventLimit is the only way to control result size. |
API Quick Reference
GET /v3/members/{memberId}/promotions/{promotionId}
└─ response
├─ memberId (number)
└─ promotions []
├─ promotionId (number)
├─ promotionName (string)
├─ programId (number)
├─ startDateISO (string)
├─ endDateISO (string)
├─ timezoneName (string)
├─ promotionIdentifier (string)
├─ unifiedPromotionId (string)
├─ description (string)
├─ active (boolean)
├─ optInStartDateISO (string)
├─ optInEndDateISO (string)
├─ promotionCustomFields []
│ ├─ key (string)
│ ├─ value (string)
│ └─ brandDefined (boolean)
└─ customerPromotionTimelines []
└─ events []
├─ eventType (string)
├─ eventId (number)
├─ enrollmentId (number)
├─ optInId (number)
├─ parentId (number)
├─ eventLogId (number)
├─ eventTimeISO (string)
├─ eventProcessingTimeISO (string)
├─ eventExpiryDateISO (string)
├─ activityDetails []
│ ├─ activityId (string)
│ ├─ activityName (string)
│ └─ incentiveType (string)
├─ revokedBy (number)
└─ revokedReason (string)Example response
{
"memberId": 388757266,
"promotions": [
{
"promotionId": 1133608813,
"promotionName": "test-loyalty-promo-123",
"programId": 2607,
"startDateISO": "2026-03-01T00:00:00+05:30",
"endDateISO": "2026-04-01T23:59:59+05:30",
"timezoneName": "Asia/Kolkata",
"promotionIdentifier": "2dac55ea-2ae8-486a-bed1-0c7992c2565c",
"unifiedPromotionId": "abc12345-0000-4abc-8def-000000000000",
"description": "test-loyalty-promo-123",
"active": true,
"promotionCustomFields": [
{ "key": "header-new", "value": "1234", "brandDefined": true },
{ "key": "xsx", "value": "4567", "brandDefined": true }
],
"customerPromotionTimelines": [
{
"events": [
{
"eventType": "OPTED_IN",
"eventId": 185122,
"parentId": 222987,
"eventLogId": 52208279,
"eventTimeISO": "2026-03-10T13:57:20+05:30",
"eventProcessingTimeISO": "2026-03-10T13:57:20+05:30",
"eventExpiryDateISO": "2026-04-01T23:59:59+05:30"
},
{
"eventType": "ENROLLED",
"eventId": 222987,
"eventLogId": 52208266,
"eventTimeISO": "2026-03-10T13:55:10+05:30",
"eventExpiryDateISO": "2026-04-01T23:59:59+05:30"
},
{
"eventType": "REVOKED_OPTIN",
"optInId": 185110,
"parentId": 222975,
"eventLogId": 52208150,
"eventTimeISO": "2026-03-09T11:20:05+05:30",
"eventProcessingTimeISO": "2026-03-09T11:21:07+05:30",
"revokedBy": 50685491,
"revokedReason": "member requested opt-out"
},
{
"eventType": "REVOKED_ENROLL",
"enrollmentId": 222975,
"eventLogId": 52208150,
"eventTimeISO": "2026-03-09T11:20:05+05:30",
"eventProcessingTimeISO": "2026-03-09T11:21:07+05:30",
"revokedBy": 50685491,
"revokedReason": "member requested opt-out"
},
{
"eventType": "REDEEMED",
"eventLogId": 52208098,
"eventTimeISO": "2026-03-08T09:40:00+05:30",
"activityDetails": [
{ "activityId": "act-1001", "activityName": "Spend over $1", "incentiveType": "POINTS" }
]
}
]
}
]
}
]
}Response parameters
| Field | Type | Description |
|---|---|---|
.memberId | Long | Unique identifier of the member. |
.promotions | Array | List of promotion objects with full participation timeline details. |
..promotionId | Long | Unique identifier of the promotion. |
..promotionName | String | The display name of the promotion shown to members during enrollment. |
..programId | Integer | The unique identifier of the loyalty program under which this promotion operates. |
..startDateISO | String | Indicates the promotion's start date and time in ISO 8601 format, returned in the server time zone. EU server example: 2026-03-01T00:00:00Z → 01 March 2026, 00:00:00 (UTC) India server example: 2026-03-01T00:00:00+05:30 → 01 March 2026, 00:00:00 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
..endDateISO | String | Indicates the promotion's end date and time in ISO 8601 format, returned in the server time zone. EU server example: 2026-04-01T23:59:59Z → 01 April 2026, 23:59:59 (UTC) India server example: 2026-04-01T23:59:59+05:30 → 01 April 2026, 23:59:59 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
..timezoneName | String | The IANA timezone name that governs how the promotion's start, end, and opt-in dates are evaluated and displayed. |
..promotionIdentifier | String | Unique string identifier of the promotion. |
..unifiedPromotionId | String | UUID that identifies the promotion in the Unified Promotions system. |
..description | String | The text describing the promotion's benefits and terms, displayed to members during enrollment. |
..active | Boolean | Indicates if the promotion is currently in effect and eligible for member enrollment and redemption. |
..optInStartDateISO | String | Indicates the start of the opt-in window in ISO 8601 format, returned in the server time zone. Returned only when an opt-in window is configured for the promotion. EU server example: 2026-03-01T00:00:00Z → 01 March 2026, 00:00:00 (UTC) India server example: 2026-03-01T00:00:00+05:30 → 01 March 2026, 00:00:00 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
..optInEndDateISO | String | Indicates the end of the opt-in window in ISO 8601 format, returned in the server time zone. Returned only when an opt-in window is configured for the promotion. EU server example: 2026-03-15T23:59:59Z → 15 March 2026, 23:59:59 (UTC) India server example: 2026-03-15T23:59:59+05:30 → 15 March 2026, 23:59:59 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
..promotionCustomFields | Array | Custom key-value fields configured at the promotion level to store brand-specific metadata. |
...key | String | The identifier for the custom field used to reference its associated value. |
...value | String | The data stored for this custom field, as configured by the brand during promotion setup. |
...brandDefined | Boolean | Indicates if the custom field is part of the brand's configuration, as opposed to a system-provided default. |
..customerPromotionTimelines | Array | A chronological record of the member's enrollment, opt-in, revocation, and redemption events for this promotion. |
...events | Array | Flat, chronological list of every timeline event for this member and promotion, sorted newest first. Combines enrollment, opt-in, revocation, and redemption events into a single list; use .eventType to distinguish them. Truncated to timelineEventLimit (default 20) across all event types combined. |
....eventType | String | Possible values: ENROLLED (the member was enrolled), OPTED_IN (the member opted into an enrollment cycle), REVOKED_ENROLL (an enrollment was revoked), REVOKED_OPTIN (an opt-in was revoked), REDEEMED (one or more incentives were awarded). GENERIC promotions never produce ENROLLED, OPTED_IN, REVOKED_ENROLL, or REVOKED_OPTIN events, but can still produce REDEEMED events. Which of the fields below are populated depends on this value; see the notes on each field. |
....eventId | Long | The enrollment ID for an ENROLLED event, or the opt-in ID for an OPTED_IN event. Not present for REDEEMED or REVOKED_* events; those carry the relevant ID in .enrollmentId or .optInId instead. |
....enrollmentId | Long | The ID of the enrollment being revoked. Present only for REVOKED_ENROLL events. |
....optInId | Long | The ID of the opt-in being revoked. Present only for REVOKED_OPTIN events. |
....parentId | Long | The ID of the enclosing enrollment. Present for OPTED_IN events (the enrollment the member opted into), and for REVOKED_OPTIN events when the revoke was pinned to a single enrollment. |
....eventLogId | Long | Event log ID for this event, usable for audit and cross-referencing with other APIs. |
....eventTimeISO | String | Indicates when this event occurred, in ISO 8601 format, returned in the server time zone. EU server example: 2026-03-10T08:25:10Z → 10 March 2026, 08:25:10 (UTC) India server example: 2026-03-10T13:55:10+05:30 → 10 March 2026, 13:55:10 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request. |
....eventProcessingTimeISO | String | For OPTED_IN events, the date and time the opt-in was processed by the system. For REVOKED_ENROLL and REVOKED_OPTIN events, the date and time the revoke was processed. Not present for ENROLLED or REDEEMED events. Returned in ISO 8601 format, in the server time zone. |
....eventExpiryDateISO | String | The expiry date and time for this enrollment or opt-in, in ISO 8601 format, returned in the server time zone. Present only for ENROLLED and OPTED_IN events. |
....activityDetails | Array | Object containing one entry per promotion activity that awarded an incentive as part of this event. Present only for REDEEMED events. |
.....activityId | String | Identifier of the promotion activity that awarded the incentive. |
.....activityName | String | Display name of the promotion activity that awarded the incentive. |
.....incentiveType | String | The type of incentive awarded by this activity, for example POINTS. Unrecognized incentive types are returned as UNKNOWN. |
....revokedBy | Long | The ID of the user or system actor that performed the revoke. Present only for REVOKED_ENROLL and REVOKED_OPTIN events, and only when source-tracking details were provided on the revoke request. |
....revokedReason | String | The reason recorded for the revoke. Present only for REVOKED_ENROLL and REVOKED_OPTIN events, and only when source-tracking details were provided on the revoke request. |
Error and warning codes
| Code | Type | Description |
|---|---|---|
| 310192 | Error | Member not found for the given memberId. Use a valid memberId. |
| 310194 | Error | No ACTIVE, PAUSED, or STOPPED promotion found for the given promotionId. Use a valid promotionId. |
| 310193 | Error | No ACTIVE, PAUSED, or STOPPED promotion found for the given promotionIdentifier. Use a valid promotionIdentifier. |
| 310196 | Error | Invalid value for memberEnrollmentStatus. Supported values: PENDING_ENROLLMENT, PENDING_OPT_IN, AVAILABLE_TO_REDEEM, REDEEMED, EXPIRED. |
| 500 | Error | Internal server error. Retry the request after a short delay. |