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

Example request

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

curl --location 'https://eu.api.capillarytech.com/v3/unifiedPromotions?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 name of the promotion. Possible Values: String.
...description	String	Specifies the description of the promotion. Possible Values: String.
...programId	String	Specifies the program ID associated with the promotion.
...orgId	Integer	Specifies the organization ID.
...startDate	String (date-time)	Specifies the start date and time of the promotion in org.
...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 promotion.
...status	String	Indicates the current status of the promotion.
...promoIdentifer	String	Specifies a unique string identifier for the promotion.
...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 the loyalty earning type.
...version	String	Specifies the version string of the promotion.
...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 draft's status. Possible Values: String status.
....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 is stackable.
....isConsideredForRanking	Boolean	Indicates if the promotion is considered for ranking. Possible Values: true, false.
....isExclusive	Boolean	Indicates if the promotion is exclusive. Possible Values: true, false.
....isAlwaysApply	Boolean	Indicates if the promotion should always apply. Possible Values: true, false.
....skipEarnedDateCheckOnRedeem	Boolean	Indicates if the earned date check should be skipped on redemption. Possible Values: true, false.
...promotionMetadata	Array (Object)	Defines a list of custom key-value metadata pairs.
....isBrandDefined	String	Specifies if the metadata is defined by the brand.
....key	String	Specifies the metadata key.
....value	String	Specifies the metadata value. q
...commonStrategies	Object	Defines common strategies, like expiry.
....expiry	Array (Object)	Defines a list of expiry strategies.
.....strategyTypeId	Integer (int32)	Specifies the strategy type ID.
.....propertyValues	String	Specifies the property values for the strategy.
.....owner	String	Specifies the owner of the strategy.
.....updatedViaNewUI	Boolean	Indicates if the strategy was updated via the new UI.
.....useCommonExpiryStrategy	Boolean	Indicates if the common expiry strategy is used.
.....strategyRef	String	Specifies the strategy reference.
.....strategySubType	String	Indicates the strategy sub-type.
...promotionMode	String	Indicates the promotion mode.
..customerEnrolment	Object	Defines the customer enrollment rules.
...enrolmentMethod	String	Indicates the method of customer enrollment.
...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	Specifies the action name.
.....actionClass	String	Specifies the action class.
.....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 the scope of the limit.
...granularity	String	Indicates the granularity of the limit.
...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 the type of limit.
...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 the type of period.
....periodUnit	String	Indicates the unit for the period.
....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 opt-in expiry.
.....enrolmentExpiryBasedOn	Object	Defines enrolment expiry.
.....optinLimitPerCustomer	Object	Defines opt-in limit.
.....maxRedemptionsPerEarnPerCustomer	Object	Defines redemption limit.
.....enrolmentLimitPerPromotion	Object	Defines total enrolment limit.
.....enrolmentLimitPerCustomer	Object	Defines enrolment limit per customer.
.....maxPointsPerEarnPerCustomer	Object	Defines max points per earn limit.
...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 opt-in expiry.
.....enrolmentExpiryBasedOn	Object	Defines enrolment expiry.
.....optinLimitPerCustomer	Object	Defines opt-in limit.
.....maxRedemptionsPerEarnPerCustomer	Object	Defines redemption limit.
.....enrolmentLimitPerPromotion	Object	Defines total enrollment limit.
.....enrolmentLimitPerCustomer	Object	Defines enrollment limit per customer.
.....maxPointsPerEarnPerCustomer	Object	Defines max points per earn limit.
..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).