Get details of all promotions

Lists all promotions.

This API lists and provides details of all the promotions available in the org. This includes the types of promotions, point and redemption restriction details, start and end dates, activation status etc, ranking and stacking information.

By default, the types of promotions, ranking and stacking are not available for all the orgs. This needs to be enabled separately. For more details on the types of promotions, refer Types of promotions.

Types of promotions

There are three different types of promotions:

  • GENERIC (UI term - Available without issue)
  • LOYALTY (UI term - Direct issue)
  • LOYALTY_EARNING (UI term - Enrol & Issue)

The field pointsOfferType in the response provides information on the type of promotion.

Limits and restrictions

If the Types of promotions is enabled for your organisation, then the information regarding the limits and restrictions on issual, earning, or redemption is available in the object promotionRestriction. This information is also replicated in the limits and customerUsage objects.

API endpoint example

'https://eucrm.cc.capillarytech.com/api_gateway/loyalty/v1/programs/promotions/list?limit=5&offset=1

Prerequisites

  • Authentication: Basic or OAuth authentication
  • Access group resource: Read access to customer group resource

Resource information

URI/api_gateway/loyalty/v1/programs/promotions/list
HTTP methodGET
Pagination supported?Yes
Rate limitNA
Batch supportNo

Query Parameters

Parameter
(Parameters marked with * are mandatory)
Data TypeDescription
limit*IntegerNumber of entries in a page.
offset*IntegerPage number you want to fetch.
programLongProgram ID associated with the promotion.
statusEnumStatus of promotion. Valid values are COMPLETED, LIVE, UPCOMING, INACTIVE.
activityEnumEvent name for promotion. Valid values re CustomerRegistration, CustomerUpdate, GenericEvent, NewBill, PointsContributionToGroup, PointsTransfer, ReturnBill,TargetCompleted, TransactionAdd, ALL.
startDateStringStart date of the promotion in ISO8601 format. Example: 2024-04-04T00:00Z
endDateStringEnd date of promotion in ISO8601 format. Example: 2024-04-27T23:59:59Z
promotionNameStringName of the promotion. In case you want to fetch data of a specific promotion.

Note: startDate and endDate must appear in pairs.

https://eucrm.cc.capillarytech.com/api_gateway/loyalty/v1/programs/promotions/list?limit=5&offset=1

Response Parameters

ParameterData TypeDescription
statusObjectAn object containing the status code and message of the response.
codeIntegerThe status code indicating the result of the request.
messageStringA message providing additional information about the status.
validationErrorsObjectAn object containing validation errors, if any.
dataObjectAn object containing promotion data retrieved from the request.
idLongThe ID of the promotion.
nameStringThe name of the promotion.
descriptionStringThe description of the promotion.
promotionStatusStringThe status of the promotion. Values are COMPLETED, LIVE, UPCOMING, or INACTIVE
lastUpdateDateString (Date)The date and time when the promotion was last updated.
lastUpdatedByIntegerThe ID of the user who last updated the promotion.
programNameStringThe name of the program associated with the promotion.
promotionTypeStringIdentifies where the promotion is applied, if it's customer level promotion or transaction level promotion.
programIdLongThe ID of the program associated with the promotion.
startDateString (Date)The start date and time of the promotion.
endDateString (Date)The end date and time of the promotion.
identifierStringUniversally unique identifier of the promotion.
isActiveBooleanIndicates if the promotion is currently active.
eventNameStringThe name of the event associated with the promotion.
pointsOfferTypeStringThe type of promotion. The types of promotion are GENERIC, LOYALTY, and LOYALTY_EARNING.
- promotionRestrictionsObjectRestrictions and settings for the promotion. Issual restrictions - Provides info on the restrictions on the enrolment of the customers. earnRestrictions provides information on the restrictions on the promotion issual. expiryRestrictions provide info on the enrol and issue expiry. Redemption restrictions provides information on the maximum redemptions of points per issue of promotion
-- redemptionRestrictionsObjectContains information on the redemption limits for a promotion.
--- nameEnumType of redemption restriction. Supported values:
MAX_ALLOWED_POINTS_PER_EVENT: The maximum points that can be earned for a single activity (make a transaction, redeem points etc.) done by a customer.
MAX_ALLOWED_TIMES_PER_CUSTOMER: The maximum number of activities (make a transaction, redeem points etc.) a customer can do to earn points.
MAX_ALLOWED_POINTS_PER_CUSTOMER:The maximum number of points a customer can earn from a promotion.
MAX_ALLOWED_TIMES_PER_PROMOTION: The maximum number of activities (make a transaction, redeem points etc.) allowed across all customers in the brand for the promotion.
MAX_ALLOWED_POINTS_PER_PROMOTION:The maximum number of points available across all customers in the brand for the promotion.
MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER:The maximum number of times a customer can redeem a promotion after earning
--- valueIntegerNumber of units corresponding to the name. Specify -1 for no limit (max limit: 100).
--- typeEnumType of period for restriction. Supported values: PERIOD_BASED, NON_PERIOD_BASED.
--- periodTypeEnumType of period. Supported value: MOVING_WINDOW.
--- periodUnitEnumFrequency of the period. Supported values: DAILY, WEEKLY, MONTHLY.
-- issualRestrictionsObjectContains information on the issual limits for a promotion.
--- nameEnumType of issual restriction. Supported values:
MAX_NUMBER_OF_ISSUALS_PER_CUSTOMER: Maximum number of times a promotion can be issued to a customer.
--- valueIntegerNumber of units corresponding to the name. Specify -1 for no limit (max limit: 100).
-- earnRestrictionsObjectContains information on the earn limits for a promotion (specific to enrol-and-issue promotions).
--- nameEnumType of earn restriction. Supported values:
MAX_NUMBER_OF_EARNS_PER_CUSTOMER: The maximum number of times a loyalty promotion can be issued to a customer.
MAX_NUMBER_OF_EARNS_PER_PROMOTION: The maximum number of times a loyalty promotion can be issued across customers.
MAX_POINTS_PER_EARN_PER_CUSTOMER: The maximum number of points a customer can earn in a single event from a promotion.
--- valueIntegerNumber of units corresponding to the name. Specify -1 for no limit (max limit: 100).
-- expiryRestrictionsObjectContains information on the expiry for a promotion (mandatory for all promotion types).
--- nameEnumAction that is expiring. Supported values:
ISSUAL_PROMOTION_EXPIRY_BASED_ON: The time period within which the customer must complete the activity required to issue the loyalty promotion. Once this lapses, the customer cannot earn the loyalty promotion.
EARN_PROMOTION_EXPIRY_BASED_ON: The time period within which the customer must complete the activity required to receive the loyalty promotion benefits. Once this lapses, the customer cannot earn the benefits.
--- typeEnumType of expiration. Supported values: PROMOTION, CUSTOM.
--- valueIntegerNumber of days the loyalty promotion expires from the date of issual.
isAlwaysApplyBooleanIndicates whether the promotion is always applied.
isStackableBooleanIndicates whether the promotion is stackable.
isConsideredForRankingBooleanIndicates whether the promotion is considered for ranking.
loyaltyEarningTypeStringThis parameter is not in use.
expiryReminderStringThe expiry reminder settings for the promotion.
isExclusiveBooleanIndicates whether the promotion is exclusive.
scopeStringThe scope of the promotion.
cappingStatusBooleanIndicates if the loyalty promotion has restrictions on reward currencies. The value will be true or false only if the loyalty promotion has a fixed-window calendar.
true: Capping is enabled for the loyalty promotion.
false: Capping is disabled for the loyalty promotion.
null: Loyalty promotion does not have a fixed-window calendar.
pageDetailsObjectAn object containing details about the pagination of the response.
pageNumberIntegerThe current page number.
pageSizeIntegerThe number of entries per page.
totalEntriesIntegerThe total number of entries.
pageCountIntegerThe total number of pages in the response.
{
    "status": {
        "code": 200,
        "message": "success"
    },
    "validationErrors": null,
    "data": [
        {
            "id": 56796,
            "name": "Happyhour",
            "description": "Promotion Description",
            "promotionStatus": "INACTIVE",
            "lastUpdateDate": "2024-04-16T07:39:05Z",
            "lastUpdatedBy": 606249,
            "programName": "Default Program",
            "promotionType": "BILL",
            "programId": 469,
            "startDate": "2024-04-04T00:00Z",
            "endDate": "2024-04-27T23:59:59Z",
            "identifier": "d32dd076-67b2-4b15-b52d-83f9c4785589",
            "isActive": false,
            "eventName": "TRANSACTIONADD",
            "pointsOfferType": "GENERIC",
            "promotionRestrictions": {
                "restrictions": {
                    "redemptionRestrictions": [
                        {
                            "name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
                            "value": 100,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        }
                    ],
                    "issualRestrictions": [],
                    "earnRestrictions": [],
                    "expiryRestrictions": []
                },
                "scope": null,
                "isStackable": false,
                "isConsideredForRanking": false,
                "loyaltyEarningType": null,
                "expiryReminder": null,
                "isExclusive": false,
                "isAlwaysApply": false,
              	"cappingStatus": true
            }
        },
        {
            "id": 56783,
            "name": "Update Profile",
            "description": "Promotion Description",
            "promotionStatus": "INACTIVE",
            "lastUpdateDate": "2024-04-08T07:55:10Z",
            "lastUpdatedBy": 606249,
            "programName": "Default Program",
            "promotionType": "CUSTOMER",
            "programId": 469,
            "startDate": "2024-04-04T00:00Z",
            "endDate": "2024-04-30T23:59:59Z",
            "identifier": "c4576641-cce4-475a-aae5-fd2236b2d631",
            "isActive": false,
            "eventName": "CUSTOMERREGISTRATION",
            "pointsOfferType": "GENERIC",
            "promotionRestrictions": {
                "restrictions": {
                    "redemptionRestrictions": [
                        {
                            "name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
                            "value": 100,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        }
                    ],
                    "issualRestrictions": [],
                    "earnRestrictions": [],
                    "expiryRestrictions": []
                },
                "scope": null,
                "isStackable": false,
                "isConsideredForRanking": false,
                "loyaltyEarningType": null,
                "expiryReminder": null,
                "isExclusive": false,
                "isAlwaysApply": false,
             	  "cappingStatus": true
            }
        },
        {
            "id": 56782,
            "name": "Specificstores",
            "description": "Promotion Description",
            "promotionStatus": "INACTIVE",
            "lastUpdateDate": "2024-04-08T07:55:32Z",
            "lastUpdatedBy": 606249,
            "programName": "Default Program",
            "promotionType": "BILL",
            "programId": 469,
            "startDate": "2024-04-04T00:00Z",
            "endDate": "2024-04-30T23:59:59Z",
            "identifier": "69511a30-b828-485c-9d7a-7a92b4e30bcf",
            "isActive": false,
            "eventName": "TRANSACTIONADD",
            "pointsOfferType": "GENERIC",
            "promotionRestrictions": {
                "restrictions": {
                    "redemptionRestrictions": [
                        {
                            "name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
                            "value": 100,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        }
                    ],
                    "issualRestrictions": [],
                    "earnRestrictions": [],
                    "expiryRestrictions": []
                },
                "scope": null,
                "isStackable": false,
                "isConsideredForRanking": false,
                "loyaltyEarningType": null,
                "expiryReminder": null,
                "isExclusive": false,
                "isAlwaysApply": false,
                "cappingStatus": false
            }
        },
        {
            "id": 56747,
            "name": "Accumulatepoints",
            "description": "Promotion Description",
            "promotionStatus": "INACTIVE",
            "lastUpdateDate": "2024-04-16T07:39:36Z",
            "lastUpdatedBy": 606249,
            "programName": "Default Program",
            "promotionType": "CUSTOMER",
            "programId": 469,
            "startDate": "2024-04-03T00:00Z",
            "endDate": "2024-04-30T23:59:59Z",
            "identifier": "95010c0f-4177-45f4-9888-82d43d42a672",
            "isActive": false,
            "eventName": "TARGETCOMPLETED",
            "pointsOfferType": "GENERIC",
            "promotionRestrictions": {
                "restrictions": {
                    "redemptionRestrictions": [
                        {
                            "name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
                            "value": 100,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        }
                    ],
                    "issualRestrictions": [],
                    "earnRestrictions": [],
                    "expiryRestrictions": []
                },
                "scope": null,
                "isStackable": false,
                "isConsideredForRanking": false,
                "loyaltyEarningType": null,
                "expiryReminder": null,
                "isExclusive": false,
                "isAlwaysApply": false,
               	 "cappingStatus": false
            }
        },
        {
            "id": 56746,
            "name": "Trackredeem1",
            "description": "Promotion Description",
            "promotionStatus": "COMPLETED",
            "lastUpdateDate": "2024-04-03T11:22:50Z",
            "lastUpdatedBy": 75009908,
            "programName": "Default Program",
            "promotionType": "CUSTOMER",
            "programId": 469,
            "startDate": "2024-04-03T00:00Z",
            "endDate": "2024-04-10T23:59:59Z",
            "identifier": "01a833e1-60e1-45d7-84bc-ba9154d4f86a",
            "isActive": true,
            "eventName": "TARGETCOMPLETED",
            "pointsOfferType": "GENERIC",
            "promotionRestrictions": {
                "restrictions": {
                    "redemptionRestrictions": [
                        {
                            "name": "MAX_REDEMPTIONS_PER_EARN_PER_CUSTOMER",
                            "value": 100,
                            "type": "NON_PERIOD_BASED",
                            "periodType": null,
                            "periodUnit": null
                        }
                    ],
                    "issualRestrictions": [],
                    "earnRestrictions": [],
                    "expiryRestrictions": []
                },
                "scope": null,
                "isStackable": false,
                "isConsideredForRanking": false,
                "loyaltyEarningType": null,
                "expiryReminder": null,
                "isExclusive": false,
                "isAlwaysApply": false,
              	"cappingStatus": true
            }
        }
    ],
    "pageDetails": {
        "pageNumber": 1,
        "pageSize": 5,
        "totalEntries": 88,
        "pageCount": 18
    }
}

API-specific error codes

Error codeDescription
4054Offset or limit missing.
4053Start date or end date missing.
4057Start date or end date not in the correct format.
2010Program ID incorrect.
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!