Create unified promotions

This endpoint allows you to create a new unified promotion. These promotions offer advanced capabilities for defining eligibility, triggers, actions (like awarding loyalty points or issuing coupons), and restrictions, integrating deeply with loyalty programs and customer activities.

Example request

curl --location 'https://nightly.intouch.capillarytech.com/intouch-api/v3/unifiedPromotions' \
--header 'cookie: _ga=GA1.2.2043386039.1756703131; wfx_unq=5JaUWAcqd4sJGKWK; intercom-device-id-m6855w1q=2cb436a9-655a-4e88-b754-8c3b11266d15; _ga=GA1.4.2043386039.1756703131; CS=d2a60b30fe4d893578c180cbbbd04d9e; _ga_DMDM65MHS0=GS2.2.s1760894755$o29$g1$t1760894856$j60$l0$h0; CC=ylNooqZBIKJgaEuPCNga4JiDJ2Eu7Jwh2ThY-jQ_SSjNWiJ1XXqXCiWoFnYnwDzz; CCEXP=1761105140; CT=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpZCI6WyIyOTc0NjAiXSwib3JnSUQiOjAsImV4cCI6MTc2MTEwNTE0MCwiaWF0IjoxNzYxMDE4NzQxLCJpc3MiOiJjYXBpbGxhcnl0ZWNoLmNvbSIsImF1ZCI6ImNhcGlsbGFyeSxpbnRvdWNoLGFyeWEscmVvbixhcHBzIiwic291cmNlIjoiV0VCQVBQIiwicmVmZXJlbmNlSUQiOiI1MDc4Njk4MSJ9.ldxFQL4wz-yrZSNr4qLNE3PhEOCUo2TL26iDK0iCENI; userPreferenceSelected=50786981_RCID; _gid=GA1.2.1414318397.1761018743; _gid=GA1.4.1414318397.1761018743; OID=51174; fs_uid=#FSV9A#67c5eb74-78ba-4dff-80ee-decd6d52f587:f2a15563-189d-4ede-bc18-ff239210138a:1761033205798::2#a77fbed8#/1788501236; intercom-session-m6855w1q=OS9CR3ZSUnNQTUQ5akJET3IwUmo5SkhqRFJmVUdYc2xQUlpydzNwT3V6SVpqYmhrWjVNZnJDQUs4QkQvKzVEVEpEYzZRQU10Uy9HVzEvZExOVUo5bER3TE9ma0NSODFQRkpLOEE2VDcvcG89LS1SWXFzR29vVkl0aDhGVkF2WWsvOTJ3PT0=--657d323da037bcd9416c5de41f5a3f32a0deded5; AMP_dc8065a65e=JTdCJTIyZGV2aWNlSWQlMjIlM0ElMjIyMjNkMTFiNC05MGVkLTRmNTEtYWFiMi01YTgxZGIzYmIxYTQlMjIlMkMlMjJ1c2VySWQlMjIlM0ElMjJnZW9yZ2Uuam9obnNvbiU0MGNhcGlsbGFyeXRlY2guY29tJTIyJTJDJTIyc2Vzc2lvbklkJTIyJTNBMTc2MTAzMzQxOTIzNSUyQyUyMm9wdE91dCUyMiUzQWZhbHNlJTJDJTIybGFzdEV2ZW50VGltZSUyMiUzQTE3NjEwMzM1MTE3NjAlMkMlMjJsYXN0RXZlbnRJZCUyMiUzQTQ2MTAlMkMlMjJwYWdlQ291bnRlciUyMiUzQTAlN0Q=; _ga_KL2T5V26LV=GS2.2.s1761033647$o12$g1$t1761034360$j33$l0$h0; _ga_Z68ZS274TW=GS2.2.s1761058143$o88$g0$t1761058238$j60$l0$h0; _ga_KL2T5V26LV=GS2.4.s1761058255$o13$g0$t1761058255$j60$l0$h0' \
--header 'content-type: application/json' \
--header '' \
--data '{
  "metadata": {
    "name": "Activity Based Prom",
    "description": "Enrollment for all members, requires activity-based opt-in.",
    "programId": "HiddenGemDefaultProgram_ID",
    "orgId": 12345,
    "startDate": "2025-11-27T00:00:00Z",
    "endDate": "2025-12-27T23:59:59Z",
    "timezoneName": "Asia/Kolkata",
    "promotionType": "LOYALTY",
    "status": "DRAFT",
    "loyaltyConfigMetaData": {
        "isStackable": false,
        "isExclusive": false,
        "isAlwaysApply": false,
        "isConsideredForRanking": false
    },
    "promotionMode": "UNIFIED"
  },
  "customerEnrolment": {


    "enrolmentMethod": "TRANSACTION"
  },
  "activities": [


    {
      "id": "activity_reward_trigger",
      "type": "SINGLE",
      "name": "Main Reward Activity",
      "event": "TransactionAdd",
      "ruleExpression": null,
      "expJSON": null,
      "commonCycleActionMapping": [
        {
          "cycle": "cycle_promo_period",

          "startDate": "2025-11-27T00:00:00Z",
          "endDate": "2025-12-27T23:59:59Z",
          "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"
              }
            }
          ]
        }
      ]
    }
  ],
  "workflowMetadata": {
    "optin": {

      "basedOn": "ACTIVITY",
      "activities": [


        {
          "id": "activity_optin_trigger",
          "type": "SINGLE",
          "name": "Opt-in Trigger Activity",
          "event": "TransactionAdd",
          "ruleExpression": null,
          "expJSON": null

        }
      ]

    },
    "enrolment": {

    }
  },
  "comments": null,
  "parentId": null,
  "limits": [],
  "liabilityOwnerSplitInfo": []
}'

Prerequisites

  • Authentication: Basic or OAuth authentication.
  • Default access group

Rate limit

  • Demo and Testing Clusters: 1,000 requests per minute per API key
  • Other Organizations: The rate limit is brand-specific.

To modify the limit, create a ticket with the Capillary Product support team.

Body Parameters

Field

Type

Required

Description

name

string

Yes

Specifies the unique name of the promotion, used for identification. For instance, setting this to "Weekend Double Points" clearly identifies the offer. Supported Values: String (max length 200). Example: "Q3 Bonus Points for Gold Tier"

orgId

integer

Yes

Indicates the unique organization ID the promotion belongs to. This ensures the promotion runs under the correct business account. Supported Values: Valid Organization ID (integer). Example: 100737

startDate

string

Yes

Specifies the active start date and time (ISO 8601 UTC) when the promotion becomes effective. This marks the exact moment customers can start qualifying for the "Weekend Double Points". Supported Values: ISO 8601 date-time string. Example: "2025-11-01T00:00:00Z"

endDate

string

Yes

Specifies the active end date and time (ISO 8601 UTC) when the promotion stops being effective. This is the cut-off time for earning double points in the weekend offer. Supported Values: ISO 8601 date-time string. Example: "2025-11-30T23:59:59Z"

promotionType

string

Yes

Indicates the nature of the reward or promotion type, used for categorization. Setting to LOYALTY classifies the "Weekend Double Points" as a points-based offer, enabling loyalty-specific actions. GENERIC or DISCOUNT might indicate other types of benefits. Supported Values: String representing promotion type (e.g., "LOYALTY", "GENERIC", "DISCOUNT"). Example: "LOYALTY"

status

enum

Yes

Specifies the initial status upon creation, determining its visibility and execution state. DRAFT: Saved but not active. ACTIVE: Live and evaluating. PAUSED: Temporarily stopped. PENDING_APPROVAL: Awaiting approval. STOPPED: Permanently ended. SNAPSHOT: A historical version. LIVE: Actively running. UPCOMING: Scheduled to start. COMPLETED: Finished. PUBLISH_FAILED: Failed to activate. Supported Values: DRAFT, ACTIVE, PAUSED, PENDING_APPROVAL, STOPPED, SNAPSHOT, LIVE, UPCOMING, COMPLETED, PUBLISH_FAILED. Example: "DRAFT"

description

string

Optional

Indicates a brief description of the promotion's purpose for internal reference. E.g., "Standard weekend points multiplier campaign". Supported Values: String. Example: "Award bonus points for purchases over $50"

programId

string

Optional

Specifies the loyalty program ID this promotion is associated with, linking it to that program's points system. Supported Values: String or Integer representing Program ID. Example: "2607" or "MAIN_REWARDS"

timezoneName

string

Optional

Defines the timezone for interpreting the start/end dates, ensuring the "Weekend Double Points" offer starts and ends correctly in the target region. Supported Values: Valid IANA Time Zone Database name. Example: "Asia/Kolkata" or "America/New_York"

promoIdentifer

string

Optional

Specifies a unique string identifier for the promotion, often used as a human-readable alternative to the system ID for API calls or integrations. Supported Values: String (often unique per organization). Example: "weekend-double-points-nov25"

loyaltyEarningType

enum

Optional

Defines how rewards are issued. DIRECT_EARN adds points/rewards directly upon qualification (e.g., points added immediately after purchase). ISSUE_AND_EARN first issues a placeholder (like a pending coupon or points batch) which might require a separate step or condition to be finalized/earned. Supported Values: DIRECT_EARN, ISSUE_AND_EARN. Example: "DIRECT_EARN"

loyaltyConfigMetaData

Object

Optional

Defines complex rules for promotion interaction. You can use this to prevent the "Weekend Double Points" from applying if an employee discount is used. Supported Values: A valid LoyaltyConfigMetaDto object. Example: { "isStackable": false, "isExclusive": true }

..isStackable

boolean

Optional

Indicates if this promotion can be combined (stacked) with others. false means the "Weekend Double Points" cannot be combined with a "10% Off" coupon in the same transaction. Supported Values: true, false. Example: false

..isExclusive

boolean

Optional

Indicates if this promotion cancels out all other non-stackable promotions when applied. If true, applying this bonus prevents any other offer, even stackable ones. Supported Values: true, false. Example: false

..isAlwaysApply

boolean

Optional

Indicates if the promotion should always be applied automatically when conditions are met. true ensures "Weekend Double Points" apply without needing a code or manual selection. Supported Values: true, false. Example: true

..isConsideredForRanking

boolean

Optional

Indicates if earnings from this promotion should contribute to customer tier ranking calculations. true means the extra points from "Weekend Double Points" help customers reach the next loyalty tier faster. Supported Values: true, false. Example: true

..skipEarnedDateCheckOnRedeem

boolean

Optional

Specifies to skip validation of the reward's earned date during redemption, allowing redemption before official earning time. false ensures points from "Weekend Double Points" can only be used after they're properly awarded. Supported Values: true, false. Example: false

promotionMetadata

Object

Optional

Defines a list of custom key-value pairs for additional metadata, often for reporting or integration purposes. You can tag the "Weekend Double Points" offer with {"key": "CampaignTheme", "value": "Seasonal"}. Supported Values: Array of PromotionMetadata objects. Example: [ { "key": "CampaignCode", "value": "FALL25" } ]

..isBrandDefined

string

Optional

Indicates if the metadata key is custom (true) or system-defined (false). For a custom "CampaignTheme" tag, this value is true. Supported Values: String representing boolean. Example: "true"

..key

string

Optional

Specifies the metadata key name. Use this key for tracking internal campaigns. Supported Values: String. Example: "CampaignCode"

..value

string

Optional

Specifies the metadata key value. Use this value for the specific code for the campaign. Supported Values: String. Example: "FALL25"

.customerEnrolment

Object

Yes

Specifies the rules for initial customer inclusion/targeting. Defines who is eligible for the "Weekend Double Points" offer from the start. Supported Values: A valid CustomerEnrolment object. Example: { "enrolmentMethod": "TRANSACTION" }

See the "customerEnrolment" Objects" tables below for the full structure.

.activities

Object

Optional

Defines the triggers and resulting actions (rewards). E.g., An activity that triggers when a customer makes a purchase (TransactionAdd) and awards points. Supported Values: Array of SingleActivity or GroupActivity objects. Example: [ { "id": "act_1", "type": "SINGLE", ... }, { "id": "act_group", "type": "GROUP", ... } ]

See the "activities" Objects" tables below for the full structure.

.limits

Object

Optional

Specifies system-enforced limits for issuance and redemption (Limit). E.g., Limit total promotion redemptions to 1000. Supported Values: Array of Limit objects. Example: [ { "granularity": "OVERALL", "limitType": "COUNT", "limitValue": 1000 } ]

See the "limits" Objects" tables below for the full structure.

.liabilityOwnerSplitInfo

Object

Optional

Defines how the reward liability (cost) is financially distributed (LiabilityOwnerSplitInfo). E.g., Splitting the cost of a joint promotion 50/50 with a partner. Supported Values: Array of LiabilityOwnerSplitInfo objects. Example: [ { "liabilityOwnerId": 999, "ratio": 0.5, ... } ]

See the "limits" Objects" tables below for the full structure.

Customer enrollment and workflow metadata objects

These sections define how customers become eligible for the promotion, either initially or dynamically.

Field

Type

Required

Description

.customerEnrolment

Object

Yes

Specifies the rules for who is eligible for the promotion.\
Eg. The brand automatically enrolls any customer who makes a purchase during the promo period.

..enrolmentMethod

enum

Optional

Defines the primary enrollment type. \
Supported Values:

  • TRANSACTION: Enrolls customers automatically when they perform a relevant transaction during the promotion.
  • IMPORT: Enrolls a predefined list of customers uploaded separately.
  • AUDIENCE_FILTER: Pre-enrolls only customers belonging to specified audience segments before the promotion starts.

..audienceGroups

Object

Conditional

Indicates the target customer segments for pre-enrollment.

Required if enrolmentMethod is AUDIENCE_FILTER.

Example: [ { "audienceGroupId": 12345, "audienceGroupName": "Gold Tier" } ]

...audienceGroupId

integer

Yes

Specifies the unique identifier of the target audience group when using AUDIENCE_FILTER.

...audienceGroupName

string

Optional

Indicates the name of the audience group.
Example: "Gold Tier"

...description

string

Optional

Indicates the description of the audience group . Example "High spending customers"

.workflowMetadata

Object

Optional

Defines advanced rules for dynamic or opt-in workflows. Can define secondary ways to join the "Weekend Double Points" offer after it starts.

..enrolment

Object

Optional

Specifies rules for system-managed enrollment after the initial enrollment . Example: This rule can be configured to automatically enrolls users in "Weekend Double Points" if they enter the "Gold Tier" during the promotion.

...basedOn

enum

Optional

Defines the what the promotion is triggered for the dynamic enrollment.

Supported values:

ACTIVITY: Enrolls when a specified customer activity occurs. Eg: A coffee shop instantly enrolls you in its "First Purchase Bonus" promotion at the moment you buy your first coffee, because making that specific purchase is the activity that triggers the enrollment.

AUDIENCE: Enrolls when a customer newly enters a specified audience segment.
Eg. A bank automatically enrolls you in its "VIP Lounge Access" promotion the moment you deposit enough money to become a "Gold Tier member," because newly entering that audience segment is the trigger for enrollment.

...activities

Array

Conditional

Specifies activities that trigger automatic enrollment. E.g., Enrolling in "Weekend Double Points" after completing a survey activity.
Required if basedOn is ACTIVITY

Refer to the activities object table below for full structure

...audienceMapping

Array

Conditional

Specifies audience groups for automatic enrollment.
E.g., Enrolling users if they enter group 12345 ("Gold Tier") during the promo.

Required if basedOn is AUDIENCE.

....groupId

integer

Optional

Indicates the ID of the audience group for dynamic enrollment.

Example: 12345

....groupName

string

Optional

Indicates the name of the audience group .
Example: Gold Tier

...restrictions

Object

Optional

Specifies restriction rules for enrolment/opt-in frequency (PromotionRestrictions). E.g., Limiting dynamic enrollment to once per customer. Supported Values: A valid PromotionRestrictions object. Example: { "enrolmentLimitPerCustomer": { "value": 1, "type": "NON_PERIOD_BASED" } }

....optinExpiryBasedOn

Object

Optional

Defines the expiry duration/date for the user's opt-in status (PromotionExpiryConfig). Supported Values: A valid PromotionExpiryConfig object. Example: { "type": "CUSTOM", "value": 30 }

.....value

integer

Optional

Specifies the numerical value for the expiry duration (e.g., number of days if type is CUSTOM). Supported Values: Integer. Example: 30

.....expiryDate

string

Optional

Specifies a fixed date for the opt-in expiry (if type is FIXED_DATE). Supported Values: ISO 8601 date-time string. Example: "2026-12-31T23:59:59Z"

.....type

enum

Optional

Specifies the expiry reference. PROMOTION: Opt-in expires when the promotion ends. CUSTOM: Opt-in expires after value days. FIXED_DATE: Opt-in expires on expiryDate. Supported Values: PROMOTION, CUSTOM, FIXED_DATE. Example: "CUSTOM"

....enrolmentExpiryBasedOn

Object

Optional

Defines the expiry duration/date for the user's enrolment status (PromotionExpiryConfig). E.g., If dynamic enrollment only lasts 7 days. Supported Values: A valid PromotionExpiryConfig object. Example: { "type": "CUSTOM", "value": 7 }

.....value

integer

Optional

Specifies the numerical value for the expiry duration (e.g., number of days if type is CUSTOM). Supported Values: Integer. Example: 7

.....expiryDate

string

Optional

Specifies a fixed date for the enrolment expiry (if type is FIXED_DATE). Supported Values: ISO 8601 date-time string. Example: "2025-12-31T23:59:59Z"

.....type

enum

Optional

Specifies the expiry reference. PROMOTION: Enrolment expires when the promotion ends. CUSTOM: Enrolment expires after value days. FIXED_DATE: Enrolment expires on expiryDate. Supported Values: PROMOTION, CUSTOM, FIXED_DATE. Example: "CUSTOM"

....optinLimitPerCustomer

Object

Optional

Specifies the maximum number of times a customer can opt-in (PromotionRestrictionsConfig). E.g., Allowing opt-in only once per customer. Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 1, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count of the restriction. Supported Values: Integer. Example: 1

.....type

enum

Optional

Defines the restriction period type. NON_PERIOD_BASED: Limit applies for the entire promotion duration. PERIOD_BASED: Limit resets based on a defined period. Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type. MOVING_WINDOW: Uses a rolling time window (e.g., last 7 days). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit for the rolling window (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "MONTHLY"

....maxRedemptionsPerEarnPerCustomer

Object

Optional

Specifies the max redemptions allowed after one specific earning activity within the promotion (PromotionRestrictionsConfig). E.g., Earn a discount coupon once, redeem it up to 3 times. Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 3, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count of the restriction. Supported Values: Integer. Example: 3

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "DAILY"

....enrolmentLimitPerPromotion

Object

Optional

Specifies the total global limit for enrolments across all customers (PromotionRestrictionsConfig). E.g., Only the first 10,000 customers can enroll. Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 10000, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count of the restriction. Supported Values: Integer. Example: 10000

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "WEEKLY"

....enrolmentLimitPerCustomer

Object

Optional

Specifies the max number of times a single customer can enroll (or re-enroll) (PromotionRestrictionsConfig). E.g., Limit enrollment to once per customer. Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 1, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count of the restriction. Supported Values: Integer. Example: 1

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "MONTHLY"

....maxPointsPerEarnPerCustomer

Object

Optional

Specifies the max points a customer can earn from this promotion from one activity (PromotionRestrictionsConfig). E.g., Even if eligible for 200 points from one transaction, cap it at 100. Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 100, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count/value of the restriction. Supported Values: Integer. Example: 100

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "DAILY"

..optin

Object

Optional

Specifies explicit rules for customer-managed opt-in. E.g., Requiring customers to perform an action to join the "Weekend Double Points" offer. Supported Values: A valid Optin object. Example: { "basedOn": "EXTERNAL_TRIGGER" }

...basedOn

enum

Optional

Defines the trigger for opt-in. ACTIVITY: Opts in when a specified customer activity occurs. AUDIENCE: Opts in when a customer newly enters a specified audience segment. Supported Values: ACTIVITY, AUDIENCE. Example: "EXTERNAL_TRIGGER"

...activities

Array

Conditional

Required if basedOn is ACTIVITY. Specifies activities (See section 3) that trigger opt-in. E.g., Clicking a link tracked as a "PageView" event. Supported Values: Array of valid Activity objects. Example: [ { "id": "act_optin", "type": "SINGLE", "event": "PageView" } ]

...audienceMapping

Array

Conditional

Required if basedOn is AUDIENCE. Specifies audience groups (AudienceMapping) for opt-in. E.g., Opting in users who enter the "Newsletter Subscribers" group. Supported Values: Array of AudienceMapping objects. Example: [ { "groupId": 54321 } ]

....groupId

integer

Optional

Indicates the ID of the audience group for opt-in. Supported Values: Valid Audience Group ID (integer). Example: 54321

....groupName

string

Optional

Indicates the name of the audience group (informational). Supported Values: String. Example: "Newsletter Subscribers"

...restrictions

Object

Optional

Specifies restriction rules for opt-in frequency (PromotionRestrictions). E.g., Limiting opt-in attempts to once daily. Supported Values: A valid PromotionRestrictions object. Example: { "optinLimitPerCustomer": { "value": 1, "type": "PERIOD_BASED", "periodUnit": "DAILY" } }

....optinExpiryBasedOn

Object

Optional

Defines the expiry duration/date for the user's opt-in status (PromotionExpiryConfig). Supported Values: A valid PromotionExpiryConfig object. Example: { "type": "PROMOTION" }

.....value

integer

Optional

Specifies the numerical value for the expiry duration (e.g., days). Supported Values: Integer. Example: 30

.....expiryDate

string

Optional

Specifies a fixed date for the opt-in expiry. Supported Values: ISO 8601 date-time string. Example: "2026-12-31T23:59:59Z"

.....type

enum

Optional

Specifies the expiry reference (PROMOTION, CUSTOM, FIXED_DATE). Supported Values: PROMOTION, CUSTOM, FIXED_DATE. Example: "PROMOTION"

....enrolmentExpiryBasedOn

Object

Optional

Defines the expiry duration/date for the user's enrolment status (PromotionExpiryConfig). Supported Values: A valid PromotionExpiryConfig object. Example: { "type": "FIXED_DATE", "expiryDate": "2025-12-31T23:59:59Z" }

.....value

integer

Optional

Specifies the numerical value for the expiry duration (e.g., days). Supported Values: Integer. Example: 90

.....expiryDate

string

Optional

Specifies a fixed date for the enrolment expiry. Supported Values: ISO 8601 date-time string. Example: "2025-12-31T23:59:59Z"

.....type

enum

Optional

Specifies the expiry reference (PROMOTION, CUSTOM, FIXED_DATE). Supported Values: PROMOTION, CUSTOM, FIXED_DATE. Example: "FIXED_DATE"

....optinLimitPerCustomer

Object

Optional

Specifies the maximum number of times a customer can opt-in (PromotionRestrictionsConfig). Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 1, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count of the restriction. Supported Values: Integer. Example: 1

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "MONTHLY"

....maxRedemptionsPerEarnPerCustomer

Object

Optional

Specifies the max redemptions after one earn activity (PromotionRestrictionsConfig). Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 1, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count of the restriction. Supported Values: Integer. Example: 1

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "DAILY"

....enrolmentLimitPerPromotion

Object

Optional

Specifies the total global limit for enrolments across all customers (PromotionRestrictionsConfig). Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 10000, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count of the restriction. Supported Values: Integer. Example: 10000

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "WEEKLY"

....enrolmentLimitPerCustomer

Object

Optional

Specifies the max number of times a single customer can enroll (PromotionRestrictionsConfig). Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 1, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count of the restriction. Supported Values: Integer. Example: 1

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "MONTHLY"

....maxPointsPerEarnPerCustomer

Object

Optional

Specifies the max points a customer can earn from this promotion from one activity (PromotionRestrictionsConfig). Supported Values: A valid PromotionRestrictionsConfig object. Example: { "value": 1000, "type": "NON_PERIOD_BASED" }

.....value

integer

Optional

Specifies the maximum count/value of the restriction. Supported Values: Integer. Example: 1000

.....type

enum

Optional

Defines the restriction period type (NON_PERIOD_BASED or PERIOD_BASED). Supported Values: NON_PERIOD_BASED, PERIOD_BASED. Example: "NON_PERIOD_BASED"

.....periodType

enum

Conditional

Required if type is PERIOD_BASED. Defines the window type (MOVING_WINDOW). Supported Values: MOVING_WINDOW. Example: "MOVING_WINDOW"

.....periodUnit

enum

Conditional

Required if type is PERIOD_BASED. Defines the unit (DAILY, WEEKLY, MONTHLY). Supported Values: DAILY, WEEKLY, MONTHLY. Example: "DAILY"

Language
URL
Click Try It! to start a request and see the response here!