This endpoint retrieves a paginated list of all unified promotions within the organization, allowing filtering and sorting.

Example request

curl --location 'https://{Host}/v3/promotions' \
--header 'Authorization: Basic Z2VvcmdlLmJ1a2w6NzYzNDkxOGF4ZjU4ZjY3MmNhZjY1ZmY=' \
--header 'Cookie: _cfuvid=FpP1pTKDZjT_pAkTzJBGUZqKDqpA-1761801071752-0.0.1.1-604800000'

curl --location 'https://eu.api.capillarytech.com/v3/promotions?searchText=sign%20up' \
--header 'Authorization: Basic Z2VvcmdlLmRvY2RlbW86NjYjk1MWY5MGY1NTY5NDk1YmNkNzUxYmJiY2U=' \
--header 'Cookie: _cfuvid=FpP1pTKkTzJBGUZqKDqpA-1761801071752-0.0.1.1-604800000; _cfuvid=jnGbtvnNJI85qRcw7Ho7SDPv5sP0HLx9pom2SRZtKoQ-1765204446635-0.0.1.1-604800000'

Prerequisites

Authentication: Basic or OAuth authentication.
Default access group

Resource information


Pagination	Yes
Batch support	No

Query parameters

Field	Type	Required	Description
searchText	string	Optional	Specifies a search term to filter promotions by name or description. Use this to quickly find promotions containing specific keywords, like "Holiday Bonus". Supported Values: String. Example: "Holiday Bonus"
status	String	Optional	Specifies an array of statuses to filter by, allowing retrieval of only promotions in specific states. You can specify multiple values, separated by commas. Supported Values: `DRAFT`, `ACTIVE`, `PAUSED`, `PENDING_APPROVAL`, `LIVE`, `UPCOMING`. Example: `ACTIVE`, `UPCOMING`
page	integer	Optional	Specifies the page number to retrieve (0-indexed) for pagination. Use 0 for the first page, 1 for the second, etc.
size	integer	Optional	Specifies the number of promotions to return per page. Set to 20 to retrieve 20 promotions at a time. Supported Values: Positive integer. Default value: 10
includeDraftDetails	boolean	Optional	Indicates whether to include details about the draft version if a promotion exists as both a live version and a draft. true includes extra draft info. Default is false

Example response

{
    "data": {
        "content": [
            {
                "metadata": {
                    "name": "Efd Activity Based Prom",
                    "description": "Enrollment for all members, requires activity-based opt-in.",
                    "programId": "HiddenGemDefaultProgram_ID",
                    "orgId": 100458,
                    "startDate": "2025-11-27T00:00:00Z",
                    "endDate": "2025-12-27T23:59:59Z",
                    "timezoneName": "Asia/Kolkata",
                    "promotionType": "LOYALTY",
                    "status": "DRAFT",
                    "promoIdentifer": null,
                    "promotionId": 0,
                    "createdOn": "2025-10-30T08:43:29Z",
                    "lastModifiedOn": "2025-10-30T08:43:29Z",
                    "createdBy": 0,
                    "lastModifiedBy": 0,
                    "loyaltyEarningType": null,
                    "version": null,
                    "draftDetails": null,
                    "loyaltyConfigMetaData": {
                        "isStackable": false,
                        "isConsideredForRanking": false,
                        "isExclusive": false,
                        "isAlwaysApply": false,
                        "skipEarnedDateCheckOnRedeem": null
                    },
                    "promotionMetadata": null,
                    "commonStrategies": null,
                    "promotionMode": "UNIFIED"
                },
                "customerEnrolment": {
                    "enrolmentMethod": "TRANSACTION"
                    "enrolmentMethod": "TRANSACTION",
                    "customerEligibilityType": "ALL"
                },
                "activities": [
                    {
                        "type": "SINGLE",
                        "id": "activity_reward_trigger",
                        "type": "SINGLE",
                        "name": "Main Reward Activity",
                        "commonCycleActionMapping": [
                            {
                                "cycle": "cycle_promo_period",
                                "actions": [
                                    {
                                        "id": "action_award_points",
                                        "actionName": "AWARD_CURRENCY",
                                        "actionClass": "com.capillary.loyalty.engine.actor.promotion.actions.AwardCurrency",
                                        "mandatoryPropertiesValues": {
                                            "POINTS_TO_AWARD": "100",
                                            "CURRENCY_IDENTIFIER": "POINTS"
                                        }
                                    }
                                ],
                                "startDate": "2025-11-27",
                                "endDate": "2025-12-27"
                            }
                        ],
                        "event": "TransactionAdd",
                        "allCycles": []
                    }
                ],
                "comments": null,
                "parentId": null,
                "parentDetails": null,
                "version": 1,
                "limits": [],
                "liabilityOwnerSplitInfo": [],
                "id": "6903253184daf5486232dec9",
                "workflowMetadata": {
                    "enrolment": {
                        "basedOn": null,
                        "activities": null,
                        "audienceMapping": null,
                        "restrictions": null
                    },
                    "optin": {
                        "basedOn": "ACTIVITY",
                        "audienceMapping": null,
                        "activities": [
                            {
                                "type": "SINGLE",
                                "id": "activity_optin_trigger",
                                "type": "SINGLE",
                                "name": "Opt-in Trigger Activity",
                                "event": "TransactionAdd",
                                "allCycles": []
                            }
                        ],
                        "restrictions": null
                    }
                },
                "communicationApprovalStatus": null
            }
        ],
        "pageable": {
            "pageNumber": 0,
            "pageSize": 10,
            "sort": {
                "empty": true,
                "sorted": false,
                "unsorted": true
            },
            "offset": 0,
            "unpaged": false,
            "paged": true
        },
        "totalElements": 1,
        "totalPages": 1,
        "last": true,
        "size": 10,
        "number": 0,
        "sort": {
            "empty": true,
            "sorted": false,
            "unsorted": true
        },
        "numberOfElements": 1,
        "first": true,
        "empty": false
    },
    "errors": null,
    "warnings": null
}

Response parameters

Field	Type	Description
data	Object	Defines the main data object containing pagination details and the list of promotions.
.totalElements	integer	Specifies the total number of promotions found matching the filter criteria across all pages.
.totalPages	integer	Specifies the total number of pages available based on the size parameter.
.size	integer	Specifies the number of items requested per page.
.content	Object	Defines the list of UnifiedPromotion objects for the current page.
..id	String	Specifies the unique system-generated identifier for the unified promotion.
..metadata	Object	Defines the object containing all metadata for the promotion.
...name	String	Specifies the display name of the promotion.
...description	String	Specifies the description of the promotion.
...programId	String	Specifies the unique ID of the loyalty program this promotion belongs to.
...orgId	Integer	Specifies the unique ID of the organization that owns this promotion.
...startDate	String (date-time)	Specifies the date and time from which the promotion becomes active, in ISO 8601 format.
...endDate	String (date-time)	Specifies the end date and time of the promotion in ISO 8601 format.
...timezoneName	String	Specifies the timezone name for the promotion's schedule.
...promotionType	String	Specifies the type of the promotion, which determines how rewards are issued to customers.
...status	String	Indicates the current lifecycle status of the promotion.
...promoIdentifer	String	Specifies the external identifier configured for the promotion. Unlike the system-generated `promotionId`, this is a human-readable or externally assigned string used to reference the promotion across systems.
...promotionId	Integer (int32)	Specifies the legacy numerical promotion ID.
...createdOn	String (date-time)	Specifies the creation timestamp, in ISO time format.
...lastModifiedOn	String (date-time)	Specifies the date and time when the promotion was last modified, in ISO time format.
...createdBy	Integer (int32)	Specifies the user ID of the creator.
...lastModifiedBy	Integer (int32)	Specifies the user ID of the user who has last modified the promotion.
...loyaltyEarningType	String	Indicates how customers earn rewards under this promotion — whether points are issued automatically on a qualifying event, or whether the customer must first opt in before earning.
...version	String	Specifies the version label of the promotion configuration, which increments each time the promotion is significantly updated.
...draftDetails	Object	Defines details if the promotion is a draft. Included if includeDraftDetails is true.
....id	String	Specifies the draft's unique ID.
....status	String	Specifies the current status of the draft version.
....version	Integer (int32)	Specifies the draft version number.
....lastModifiedBy	Integer (int32)	Specifies the user who last modified the draft.
....lastModifiedOn	String (date-time)	Specifies when the draft was last modified. Possible Values: ISO 8601 date-time string.
...loyaltyConfigMetaData	Object	Defines loyalty-specific configurations.
....isStackable	Boolean	Indicates if the promotion can be applied alongside other active promotions within the same transaction.
....isConsideredForRanking	Boolean	Indicates if the promotion is included in priority ranking, which controls which promotions take precedence when multiple are applicable to the same transaction.
....isExclusive	Boolean	Indicates if the promotion is evaluated in isolation, preventing any other promotion from being applied in the same transaction.
....isAlwaysApply	Boolean	Indicates if the promotion is applied unconditionally, bypassing the ranking and stacking rules configured for the org.
....skipEarnedDateCheckOnRedeem	Boolean	Indicates if customers can redeem rewards from this promotion outside its active earning period.
...promotionMetadata	Array (Object)	Defines a list of custom key-value metadata pairs.
....isBrandDefined	String	Indicates if this metadata key-value pair was configured by the brand, as opposed to being system-generated.
....key	String	Specifies the metadata key.
....value	String	Specifies the value associated with the metadata key.
...commonStrategies	Object	Defines shared configuration strategies applied across the promotion, such as how issued points or benefits expire.
....expiry	Array (Object)	Defines the expiry rules that determine when points or benefits issued under this promotion become invalid.
.....strategyTypeId	Integer (int32)	Specifies the unique identifier of the expiry strategy type applied to this promotion.
.....propertyValues	String	Specifies the configuration parameters of the expiry strategy as a JSON string, such as the expiry duration.
.....owner	String	Specifies the entity responsible for managing this expiry strategy.
.....updatedViaNewUI	Boolean	Indicates if this expiry strategy was last updated using the Loyalty+ UI.
.....useCommonExpiryStrategy	Boolean	Indicates if the promotion uses the org-level expiry strategy instead of a promotion-level configuration.
.....strategyRef	String	Specifies the reference ID that links this expiry configuration to its strategy definition.
.....strategySubType	String	Indicates the sub-type of the expiry strategy, such as a fixed expiry date or a rolling window from the date of issue.
...promotionMode	String	Indicates the mode under which the promotion was created.
..customerEnrolment	Object	Defines the customer enrollment rules.
...enrolmentMethod	String	Indicates how customers are enrolled into the promotion.
...customerEligibilityType	String	Restricts which customers are eligible based on loyalty enrollment status. Values: LOYAL, NON_LOYAL, ALL.
...audienceGroups	Array (Object)	Defines a list of audience groups for enrollment.
....audienceGroupId	Integer (int64)	Specifies the unique ID for the audience group.
....audienceGroupName	String	Specifies the name of the audience group.
....description	String	Specifies the description of the audience group.
..activities	Array (Object)	Defines a list of activities.
...id	String	Specifies the unique ID for the activity.
...type	String	Specifies the type of the activity.
...name	String	Specifies the name of the activity.
...refId	String	Specifies the reference ID for the activity.
...parentId	String	Specifies the parent activity's ID.
...commonCycleActionMapping	Array (Object)	Defines action mappings for common cycles.
....cycle	String	Specifies the cycle name/ID.
....defaultValue	Number (double)	Specifies the default value for the action.
....actions	Array (Object)	Defines a list of actions.
.....id	String	Specifies the action ID.
.....actionName	String	Identifies the type of reward action. Supported values: `AWARD_POINTS_ACTION` (award points), `AWARD_CURRENCY` (award currency like points), `AWARD_BADGE` (award badge), `PE_ISSUE_VOUCHER_ACTION` (issue coupon), `EARN_PROMOTION_ACTION` (earn promotion for opt-in workflows), `UPGRADE_SLAB_ACTION_SLAB` (upgrade tier), `INITIATE_SUPPLEMENTARY_MEMBERSHIP` (enroll in secondary program).
.....actionClass	String	Fully qualified Java class name that implements the action. Example: `com.capillary.shopbook.pointsengine.endpoint.impl.action.AwardPointsActionImpl` for awarding points, or `com.capillary.loyalty.engine.actor.promotion.actions.AwardCurrency` for unified promotions.
.....description	String	Specifies the action description.
.....mandatoryPropertiesValues	Object	Defines key-value pairs for mandatory properties.
.....mandatoryComplexPropertiesValues	Object	Defines key-value pairs for mandatory complex properties.
.....embeddedStrategies	Array (Object)	Defines a list of embedded StrategyInfo objects.
....startDate	String (date-time)	Specifies the cycle mapping start date, in ISO 8601 date-time.
....endDate	String (date-time)	Specifies the cycle mapping end date, in ISO 8601 date-time.
....rulesetId	String	Specifies the cycle mapping ruleset ID.
...rulesetId	String	Specifies the ruleset ID for the activity.
...cycles	Array (Object)	Defines a list of general cycles.
...event	String	Specifies the event associated with the single activity.
...ruleExpression	String	Specifies the rule expression for the single activity.
...expJSON	String	Specifies the rule expression in JSON format.
...frequencyType	String	Specifies the frequency type.
...targetEvaluationType	String	Specifies the target evaluation type.
...targetCycleStartDate	String (date-time)	Specifies the target cycle start date, in ISO 8601 date-time.
...targetCycleEndDate	String (date-time)	Specifies the target cycle end date, in ISO 8601 date-time.
...activityCycles	Array (Object)	Defines activity-specific cycles.
...milestones	Array (Object)	Defines milestones.
...allCycles	Array (Object)	Defines a list of all cycles.
...event	String	Specifies the event associated with the group activity.
...combinationType	String	Indicates how child activities are combined.
...children	Array (Object)	Defines a nested list of child GroupActivity or SingleActivity objects.
...ruleExpression	String	Specifies the rule expression for the group activity.
...expJSON	String	Specifies the rule expression in JSON format.
..comments	String	Specifies any comments on the promotion.
..parentId	String	Specifies the ID of the parent promotion.
..parentDetails	Object	Defines details of the parent promotion.
...id	String	Specifies the parent promotion ID.
...status	String	Specifies the parent promotion status.
...version	Integer (int32)	Specifies the parent promotion version.
...lastModifiedBy	Integer (int32)	Specifies the user who last modified the parent.
...lastModifiedOn	String (date-time)	Specifies when the parent was last modified.
..version	Integer (int32)	Specifies the version number of the promotion.
..limits	Array (Object)	Defines a list of limits for the promotion.
...id	Integer (int64)	Specifies the limit ID.
...entityScope	String	Indicates whether the limit applies to each individual customer or across the promotion as a whole.
...granularity	String	Indicates the time-based frequency at which the limit resets and is re-evaluated.
...entityId	Integer (int64)	Specifies the entity ID the limit applies to.
...actionType	String	Indicates the action type being limited.
...actionSubTypeId	String	Specifies the action sub-type ID.
...limitType	String	Indicates what the limit controls — the number of times the promotion can be applied, or the total points that can be awarded.
...limitValue	Number	Specifies the value of the limit.
...period	Object	Defines the time period for the limit.
....id	Integer (int64)	Specifies the period ID.
....periodType	String	Indicates whether the limit resets on a rolling schedule or applies across the full duration of the promotion.
....periodUnit	String	Indicates the time unit of the rolling window over which the limit is enforced.
....periodValue	Integer (int32)	Specifies the value for the period.
....periodStartDay	String	Indicates the start day for weekly periods.
....startDate	String (date-time)	Specifies the fixed start date for the period, in ISO 8601 date-time.
....endDate	String (date-time)	Specifies the fixed end date for the period, in ISO 8601 date-time.
...createdOn	String (date-time)	Specifies the creation timestamp of the limit, in ISO 8601 date-time.
...createdBy	Integer (int64)	Specifies the user ID of the limit creator. Possible Values: Integer user ID (system-set).
...lastUpdatedOn	String (date-time)	Specifies the last update timestamp of the limit, in ISO 8601 date-time.
...lastUpdatedBy	Integer (int64)	Specifies the user ID of the last updater.
...active	Boolean	Indicates if the limit is active. Possible Values: true, false.
..liabilityOwnerSplitInfo	Array (Object)	Defines how liability is split.
...orgId	Integer (int32)	Specifies the organization ID.
...liabilityOwnerId	Integer (int32)	Specifies the liability owner ID.
...componentId	Integer (int32)	Specifies the component ID.
...componentType	String	Indicates the component type. Possible Values: PROGRAM, PROMOTION.
...createdBy	Integer (int32)	Specifies the user ID of the creator.
...ratio	Number (double)	Specifies the liability split ratio. Possible Values: Number between 0 and 1.
...liabilityOwnerName	String	Specifies the liability owner's name.
...liabilityOwnerType	String	Indicates the liability owner's type. Possible Values: PARTNER, PROGRAM.
...active	Boolean	Indicates if the split info is active. Possible Values: true, false.
..workflowMetadata	Object	Defines workflow metadata for enrolment and opt-in.
...enrolment	Object	Defines enrolment workflow details (Enrolment). Possible Values: A valid Enrolment object or empty object {}.
....basedOn	String	Indicates the basis for enrolment. Possible Values: `ACTIVITY`, `AUDIENCE`, `EXTERNAL_TRIGGER`.
....activities	Array (Object)	Defines activities triggering enrolment.
....audienceMapping	Array (Object)	Defines audience mappings for enrolment.
.....groupId	Integer (int64)	Specifies the group ID.
.....groupName	String	Specifies the group name.
....restrictions	Object	Defines enrolment restrictions.
.....optinExpiryBasedOn	Object	Defines when a customer's opt-in eligibility expires, after which they can no longer opt in to the promotion.
.....enrolmentExpiryBasedOn	Object	Defines when a customer's enrolment expires, after which they are no longer eligible for rewards under this promotion.
.....optinLimitPerCustomer	Object	Defines the maximum number of times a single customer can opt in to the promotion.
.....maxRedemptionsPerEarnPerCustomer	Object	Defines the maximum number of times a customer can redeem the promotion after each earning event.
.....enrolmentLimitPerPromotion	Object	Defines the maximum total number of customer enrolments allowed for the promotion.
.....enrolmentLimitPerCustomer	Object	Defines the maximum number of times a single customer can enrol in the promotion.
.....maxPointsPerEarnPerCustomer	Object	Defines the maximum points a customer can earn in a single earning event under this promotion.
...optin	Object	Defines opt-in workflow details (Optin). Possible Values: A valid Optin object or empty object {}.
....basedOn	String	Indicates the basis for opt-in. Possible Values: ACTIVITY, AUDIENCE, EXTERNAL_TRIGGER.
....activities	Array (Object)	Defines activities (SingleActivity/GroupActivity) triggering opt-in.
....audienceMapping	Array (Object)	Defines audience mappings.
.....groupId	Integer (int64)	Specifies the group ID.
.....groupName	String	Specifies the group name.
....restrictions	Object	Defines opt-in restrictions.
.....optinExpiryBasedOn	Object	Defines when a customer's opt-in eligibility expires, after which they can no longer opt in to the promotion.
.....enrolmentExpiryBasedOn	Object	Defines when a customer's enrolment expires, after which they are no longer eligible for rewards under this promotion.
.....optinLimitPerCustomer	Object	Defines the maximum number of times a single customer can opt in to the promotion.
.....maxRedemptionsPerEarnPerCustomer	Object	Defines the maximum number of times a customer can redeem the promotion after each earning event.
.....enrolmentLimitPerPromotion	Object	Defines the maximum total number of customer enrolments allowed for the promotion.
.....enrolmentLimitPerCustomer	Object	Defines the maximum number of times a single customer can enrol in the promotion.
.....maxPointsPerEarnPerCustomer	Object	Defines the maximum points a customer can earn in a single earning event under this promotion.
..communicationApprovalStatus	Object	Defines the status of communication approval.
...success	Boolean	Indicates if the approval status check was successful.
...message	String	Specifies the status message.
...response	Object	Defines the nested response object.
...statusCode	Integer (int32)	Specifies the status code.
.number	integer (int32)	Specifies the current page number.
.sort	Object or Array (Object)	Defines the sorting rules applied.
..empty	Boolean	Specifies if the sort criteria are empty.
..sorted	Boolean	Specifies if the results are sorted.
..unsorted	Boolean	Specifies if the results are unsorted.
..direction	String	Specifies the sort direction for a property.
..nullHandling	String	Specifies how null values are handled during sorting.
..ascending	Boolean	Indicates if the sort direction is ascending. Possible Values: true, false.
..property	String	Specifies the field name used for sorting.
..ignoreCase	Boolean	Indicates if case should be ignored during sorting.
.pageable	Object	Defines pagination details.
..offset	integer (int64)	Specifies the offset of the first element returned on the page.
..sort	Object or Array (Object)	Defines the sorting rules applied.
...empty	Boolean	Specifies if the sort criteria are empty.
...sorted	Boolean	Specifies if the results are sorted.
...unsorted	Boolean	Specifies if the results are unsorted.
...direction	String	Specifies the sort direction.
...nullHandling	String	Specifies how null values are handled.
...ascending	Boolean	Indicates if the sort direction is ascending.
...property	String	Specifies the field name used for sorting.
...ignoreCase	Boolean	Indicates if case should be ignored during sorting.
..pageNumber	integer (int32)	Specifies the current page number (0-indexed).
..pageSize	integer (int32)	Specifies the number of items requested per page.
..paged	Boolean	Indicates if pagination is applied.
..unpaged	Boolean	Indicates if pagination is not applied.
.numberOfElements	integer (int32)	Specifies the number of promotions returned on the current page.
.last	boolean	Indicates if the current page is the last page.
.first	boolean	Indicates if the current page is the first page.
.empty	boolean	Indicates if the current page is empty.
errors	Array (Object)	Defines a list of errors that occurred, if any.
.code	Integer (int64)	Specifies the error code. Possible Values: Integer error code.
.message	String	Specifies the error message.
warnings	Array (Object)	Defines a list of warnings, if any.
.message	String	Specifies the warning message.

Warning messages

Warning message	Description
Unable to enroll in promotions. Customer already enrolled or limit reached.	The customer is already enrolled in the promotion or the maximum enrollment limit has been reached.
Partial Success: Milestone enrollment failed.	The main promotion enrollment was successful, but one or more milestone enrollments failed.
No upload details found for file: `fileName`.	The promotion list was retrieved, but the latest upload status for an individual milestone file could not be fetched.
Something went wrong. Unable to enroll in promotions.	A connection issue occurred with a downstream service (`EMF`), resulting in an uncertain enrollment state.

Error codes

Error Code	Description
300004	Invalid input. Ensure the `page` is non-negative and `size` is between 1 and 100.
300005	Access denied. Your account does not have the necessary permissions to list promotions for this organization.
300006	Service operation failed. An unexpected internal error occurred while processing the search/list request.
310151	Invalid Status. One or more values in the `status` filter are not recognized by the system.
498	Token Expired. Your authentication session has expired. Please log in again to refresh your token.
999999	Generic Validation Error. Check the error metadata for specific details on invalid filter formats (e.g., date formats).