Create Promotion for UCC

post https://{host}/api_gateway/loyalty/v1/programs/{programId}/createPromotion/{promotionType}

Lets you create a promotion for UCC a specific loyalty program.

This API is used to create a loyalty promotion. A loyalty promotion rewards customers for achieving a target.

Prerequisites

Authentication: Basic/OAuth authentication
Default access group

Resource information


URI	v1/programs/{programId}/createPromotion/{promotionType}
HTTP method	POST
Pagination	NA
Rate limit	NA
Batch support	NA

API endpoint example

https://eu.api.capillarytech.com/api_gateway/loyalty/v1/programs/699/createPromotion/simple

Request path parameters

Parameter	Data Type	Description
programID	Integer	Unique id of the loyalty program
promotionType	String	Type of promotion. Supported values `SIMPLE`, `RANGE`, `KEYWORD`

Sample request body

{
    "promotion": {
        "id": -1,
        "name": "test_promo_uniqueName110",
        "programId": 2932,
        "startDate": "2024-08-09T12:00:00+01:00",
        "endDate": "2024-08-25T12:00:00+01:00",
        "allocatePointsOn": "BILL",
        "identifier": "test_promo_uniqueIdentifier110",
        "eventName": "TARGETCOMPLETED",
        "pointsOfferType": "LOYALTY",
        "promotionType": "BILL",
        "promotionSourceType": "USER_CREATED",
        "limits": {
            "pointsPerCustomer": -1,
            "numberOfTimesPerCustomer": -1,
            "totalPointsInPromotion": -1
        },
        "promotionRestrictions": {
            "loyaltyEarningType": "ISSUE_AND_EARN",
            "isStackable": false,
            "isExclusive": false,
            "isConsideredForRanking": false,
            "targetRuleIds": [
                123
            ],
            "targetGroupIds": [
                1234567
            ],
            "restrictions": {
                "redemptionRestrictions": [
                    {
                        "name": "MAX_ALLOWED_TIMES_PER_CUSTOMER",
                        "value": 3,
                        "type": "PERIOD_BASED",
                        "periodType": "MOVING_WINDOW",
                        "periodUnit": "WEEKLY"
                    },
                    {
                        "name": "MAX_ALLOWED_TIMES_PER_PROMOTION",
                        "value": 3,
                        "type": "NON_PERIOD_BASED"
                    }
                ],
                "issualRestrictions": [
                    {
                        "name": "MAX_NUMBER_OF_ISSUALS_PER_CUSTOMER",
                        "value": 3,
                        "type": "NON_PERIOD_BASED"
                    }
                ],
                "earnRestrictions": [
                    {
                        "name": "MAX_NUMBER_OF_EARNS_PER_CUSTOMER",
                        "value": 3
                    }
                ],
                "expiryRestrictions": [
                    {
                        "name": "ISSUAL_PROMOTION_EXPIRY_BASED_ON",
                        "type": "PROMOTION",
                        "value": 10
                    }
                ]
            }
        },
        "rulesetInfos": [
            {
                "id": -1,
                "contextID": 2932,
                "orgID": 51174,
                "contextType": "program",
                "endpointName": "POINTSENGINE_ENDPOINT",
                "name": "rulesetName_uniqueue1",
                "type": "USER_CREATED",
                "startDate": 1089532593324,
                "endDate": 33593126193324,
                "active": true,
                "rules": [
                    {
                        "id": -1,
                        "exp": "true",
                        "expJSON": "{ \"arity\": \"literal\", \"value\": \"true\", \"type\": \"boolean:primitive\" }",
                        "isActive": true,
                        "caseToActions": {
                            "true": [
                                {
                                    "id": -1,
                                    "actionName": "AWARD_TARGET_POINTS_ACTION",
                                    "mandatoryPropertiesValues": {
                                        "ProRateOnSourceValue": "EVENT_DEFAULT_VALUE",
                                        "DelayStrategy": "AS_DEFINED_IN_ALLOCATION_STRATEGY",
                                        "SourceValueRoundingStrategy": "ACTUAL",
                                        "ExpiryStrategy": "81042",
                                        "AwardStrategy": "82690",
                                        "PointsRoundingStrategy": "ACTUAL",
                                        "TargetGroupId": "1234567",
                                        "TargetRuleName": "TargetRuleName"
                                    }
                                }
                            ]
                        },
                        "filterInfo": [],
                        "description": "",
                        "expDataType": "",
                        "ruleSetId": -1,
                        "updatedViaNewUI": false
                    }
                ],
                "filterInfo": [
                    {
                        "id": -1,
                        "contextType": "RULESET",
                        "name": "LoyaltyType",
                        "description": "LoyaltyType",
                        "isInclude": true,
                        "propertyToValues": {
                            "loyaltyType": [
                                "loyalty"
                            ]
                        }
                    },
                    {
                        "id": -1,
                        "contextType": "RULESET",
                        "name": "EventSource",
                        "description": "EventSource",
                        "isInclude": true,
                        "propertyToValues": {
                            "eventSource": [
                                "INSTORE"
                            ]
                        }
                    }
                ],
                "cappingInfo": [],
                "isRulesetForGlobalPromotion": "false",
                "programIds": []
            }
        ]
    }
}

Request Parameters

Parameter	Datatype	Description
promotion	object	Root object containing all promotion details.
- id*	int	Unique ID of the promotion. Set this value to -1 while creating a new promotion.
- name*	string	Unique name of the promotion. The character limit for the name is 255 characters.
- programId*	int	Unique ID of the loyalty program to associate with the promotion.
- startDate*	date-time	Validity of the promotion. Pass the ISO standard date (`yyyy-mm-ddThh:mm:ss.s+z`).
- endDate*	date-time	End date of the promotion. Pass the ISO standard date (`yyyy-mm-ddThh:mm:ss.s+z`).
- allocatePointsOn	string	Quantity on which points needs to be allocated `BILL` , `LINEITEM`
- identifier*	string	Unique identifier for the promotion. The character limit for the identifier is 255 characters.
- eventName*	enum	Name of the event associated with the promotion, e.g., `TARGETCOMPLETED`.
- pointsOfferType	string	Type of points being offered, e.g., `LOYALTY`.
- promotionType	string	Type of promotion, e.g., `BILL`.
- promotionSourceType	string	Source from where the promotion is created: Supported values `PROMOTION_API`, `CAMPAIGN`, `BADGES`, `USER_CREATED`. Pass the value as `USER_CREATED` for creating a UCC promotion.
- limits	object	Promotion limits configuration.
-- pointsPerCustomer	int	Maximum points that can be issued per customer (set to `-1` for no limit).
-- numberOfTimesPerCustomer	int	Maximum number of times points can be issued to a customer (set to `-1` for no limit).
-- totalPointsInPromotion	int	Total points that can be generated during the promotion (set to `-1` for no limit).
- promotionRestrictions	object	Restriction settings for the promotion.
-- loyaltyEarningType	string	Type of earning, e.g., `ISSUE_AND_EARN`
-- isStackable	boolean	Indicates if the promotion can be stacked with other promotions
-- isExclusive	boolean	Indicates if the promotion is exclusive (set to `false`).
-- isConsideredForRanking	boolean	Indicates if the promotion is considered for ranking (set to `false`).
-- targetRuleIds*	array	List of target rule IDs.
-- targetGroupIds*	array	List of target group IDs.
-- restrictions	object	Defines various restrictions for redemption, issual, and earning.
--- redemptionRestrictions	array	Restrictions for redemption.
---- name	string	Name of the restriction, e.g., `MAX_ALLOWED_TIMES_PER_CUSTOMER`.
---- value	int	Value for the restriction, e.g., `3`.
---- type	string	Type of restriction, e.g., `PERIOD_BASED`.
---- periodType	string	Period type. Supported values `MOVING_WINDOW`, `FIXED_WINDOW`
---- periodUnit	string	Period unit, Supported values `DAILY` `WEEKLY`, `MONTHLY`
--- issualRestrictions	array	Restrictions for issual.
---- name	string	Name of the issual restriction
---- value	int	Value for the issual restriction
---- type	string	Type of restriction, e.g., `NON_PERIOD_BASED`.
--- earnRestrictions	array	Restrictions for earning.
---- name	string	Name of the earn restriction, e.g., `MAX_NUMBER_OF_EARNS_PER_CUSTOMER`.
---- value	int	Value for the earn restriction
--- expiryRestrictions	array	Expiry restrictions.
---- name	string	Name of the expiry restriction
---- value	int	Value for the expiry restriction
- rulesetInfos*	object	Information about the ruleset associated with the promotion.
-- id	int	Unique ID of the ruleset. Set to `-1` for new promotion.
-- contextID*	int	Unique ID of the program.
-- orgID*	int	Unique ID of the organisation
-- contextType*	string	Type of context.
-- endpointName*	string	Name of the endpoint
-- name*	string	Unique name for the ruleset
-- type*	string	Type of ruleset. For creating a UCC promotion, set this value to `USER_CREATED`.
-- startDate*	int	Start date of the ruleset in Epoch time.
-- endDate*	int	End date of the ruleset in Epoch time.
-- active*	boolean	Status of the ruleset (set to `true`).
-- rules*	array	List of rules applied to the promotion.
--- id	int	Unique ID of the rule (set to `-1` for creating a new rule).
--- exp*	boolean	Rule expression to determine if the rule is true or false.
--- expJSON*	string	Rule expression in JSON format.
--- isActive*	boolean	Status of the rule.
--- caseToActions*	object	Defines actions to take when the rule is satisfied.
---- actionName*	string	Name of the action.
---- mandatoryPropertiesValues*	object	Defines the mandatory properties for the action (e.g., `ProRateOnSourceValue`, `AwardStrategy`, etc.).
-- filterInfo	array	Information on the scope filters applied to the ruleset.
--- name	string	Name of the filter, e.g., `LoyaltyType`.
--- propertyToValues	object	Key-value pairs for filter properties, e.g., `loyaltyType: [ "loyalty" ]`.
-- cappingInfo	array	Optional capping information for the ruleset.
-- isRulesetForGlobalPromotion	boolean	Indicates if the ruleset is for a global promotion.

Sample response

{
    "status": {
        "code": 200,
        "message": "success"
    },
    "validationErrors": null,
    "data": [
        {
            "id": 200654,
            "name": "test_promo_uniqueName10",
            "promotionStatus": "COMPLETED",
            "programId": 2822,
            "startDate": "2024-08-09T00:00:00.284Z",
            "endDate": "2024-08-10T23:59:59.285Z",
            "identifier": "test_promo_uniqueIdentifier10",
            "isActive": true,
            "eventName": "TARGETCOMPLETED",
            "allocatePointsOn": "BILL",
            "limits": {
                "pointsPerCustomer": -1,
                "numberOfTimesPerCustomer": -1,
                "totalPointsInPromotion": -1,
                "totalPointsPerEventLimit": -1
            },
            "pointsOfferType": "LOYALTY",
            "promotionRestrictions": {
                "restrictions": {
                    "redemptionRestrictions": [
                        {
                            "name": "MAX_ALLOWED_TIMES_PER_CUSTOMER",
                            "value": 3,
                            "type": "PERIOD_BASED",
                            "periodType": "MOVING_WINDOW",
                            "periodUnit": "WEEKLY"
                        },
                        {
                            "name": "MAX_ALLOWED_TIMES_PER_PROMOTION",
                            "value": 3,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        },
                        {
                            "name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
                            "value": 100,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        }
                    ],
                    "issualRestrictions": [
                        {
                            "name": "MAX_NUMBER_OF_ISSUALS_PER_CUSTOMER",
                            "value": 3
                        }
                    ],
                    "earnRestrictions": [
                        {
                            "name": "MAX_NUMBER_OF_EARNS_PER_CUSTOMER",
                            "value": 3
                        }
                    ],
                    "expiryRestrictions": [
                        {
                            "name": "ISSUAL_PROMOTION_EXPIRY_BASED_ON",
                            "value": 10,
                            "type": "PROMOTION"
                        }
                    ]
                },
                "scope": null,
                "isStackable": false,
                "isConsideredForRanking": true,
                "loyaltyEarningType": "ISSUE_AND_EARN",
                "expiryReminder": null,
                "isExclusive": false,
                "isAlwaysApply": false,
                "targetGroupIds": [
                    1234567
                ],
                "targetRuleIds": [
                    123
                ]
            }
        }
    ]
}

Response parameters

Parameter	Data type	Description
status	Object	Contains the response status.
-code	Integer	Status code of the response (e.g., 200 for success).
-message	String	Status message (e.g., "success").
validationErrors	Object	Contains validation errors, if any. Null indicates no errors.
data	Array	Contains data related to the promotion.
- id	Integer	Unique identifier for the promotion.
- name	String	Name of the promotion.
-promotionStatus	String	Current status of the promotion (e.g., “LIVE”, "COMPLETED").
- programId	Integer	ID of the associated loyalty program.
- startDate	String	Start date of the promotion in ISO 8601 format.
- endDate	String	End date of the promotion in ISO 8601 format.
- identifier	String	Unique identifier for the promotion.
-isActive	Boolean	Indicates if the promotion is active.
- eventName	String	Event that triggers the promotion. An event refers to a specific action for example a store visit or transaction.
- allocatePointsOn	String	Where points are allocated (e.g., "BILL").
- limits	Object	Promotion limits.
-- pointsPerCustomer	Integer	Maximum points a customer can earn. (-1 indicates no limit).
-- numberOfTimesPerCustomer	Integer	Number of times a customer can participate. (-1 indicates no limit).
-- totalPointsInPromotion	Integer	Total points available in the promotion. (-1 indicates no limit).
-- totalPointsPerEventLimit	Integer	Total points limit per event. (-1 indicates no limit).
- pointsOfferType	String	Type of points offered (e.g., "LOYALTY"). A points offer refers to loyalty points issued to customers
promotionRestrictions	Object	Contains the restrictions applicable to the promotion. Restrictions can be configured while setting up the loyalty promotion.
- restrictions	Object	Contains various restriction types.
-- redemptionRestrictions	Array	Redemption-related restrictions. These are advanced settings for redemption.
--- name	String	Name of the redemption restriction
--- value	Integer	Maximum allowed times per customer.
--- type	String	Restriction type (e.g., "PERIOD_BASED").
--- periodType	String	Period type for restriction (e.g., "MOVING_WINDOW", FIXED_WINDOW).
--- periodUnit	Array	Period unit for restriction (e.g., "WEEKLY", “MONTHLY”).
-- issualRestrictions	Array	Issual related restrictions. An “issual” refers to the issuance of a specific promotion to customers based on their behavioral events or transactions.
--- name	Array	Name of the issuance restriction
--- value	Integer	Maximum issuances per customer.
-- earnRestrictions	Array	Earnrelated restrictions. “Earn" refers to the process where a customer completes the necessary activities to qualify for a promotion.
--- name	String	Name of the earning restriction
--- value	Integer	Maximum earnings per customer.
-- expiryRestrictions	Array	Expiry-related restrictions.
--- name	String	Name of the expiry restriction
--- value	Integer	Expiry value.
--- type	String	Expiry type (e.g., "PROMOTION").
- scope	Object	Scope of the promotion (if applicable).
- isStackable	Boolean	Indicates if the promotion can be combined with other promotions.
- isConsideredForRanking	Boolean	Indicates if the promotion is considered for ranking.
- loyaltyEarningType	String	Type of loyalty earning.
- expiryReminder	Object	Expiry reminder, if any. Null indicates no reminder.
- isExclusive	Boolean	Indicates if the promotion is exclusive.
- isAlwaysApply	Boolean	Indicates if the promotion always applies.
- targetGroupIds	Integer	List of target group IDs.
- targetRuleIds	Integer	List of target rule IDs.

API error codes

Code	Description	Solution
4007	Promotion identifier already exists for the program	Check the promotion id and ensure it is unique.
4003	A promotion with the same name exists for the program	Check the promotion name and ensure it is unique.
4011	Given start date is null or empty	Check the promotion start date and ensure it is in the correct format
4012	Given end date is null or empty	Check the promotion end date and ensure it is in the correct format
4074	For SourceType UserCreated, TargetGroupId and TargetRuleId are mandatory	Enter the TargetGroupID and TargetRuleID for the promotion
4079	Promotion Source Type cannot be null or empty	Enter the promotion source type
4075	UCC Promotions should always have one RuleSet	Ensure that only one ruleset is passed. Add the rulesets for the promotion if not added.
4076	Invalid UCC Promotions Ruleset check for ruleSetName, ContextId, OrgId, ContextType and start & End is not null	Check if the mandatory rule set fields are passed.
4076	Invalid UCC Promotions Rules passed check for expression , expressionJson and name is not null	Check if the mandatory rule set fields are correct.
4080	Invalid UCC Promotions Actions, Both key and value in cannot be null or empty	Check if the mandatoryPropertiesValues key / value is null or Empty.
4078	Invalid name in Promotions RuleSet Filter	Check the filter name and ensure it is valid.