--- title: Create Promotion Rule slug: create-promotion-rule docTags: createdAt: 2026-08-25T14:22:49.198Z --- { "id": "Dct9qCWVBWkfQ6La07TSt", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.b.preview.loyaltyservices.io/api/v3/promotion-rules", "servers": [ { "url": "https://api.b.preview.loyaltyservices.io/api/v3/promotion-rules" } ], "name": "Create Promotion Rule", "description": "Create a new promotion rule", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "Promotion rule to create", "customType": "PromotionRule", "schema": [ { "name": "code", "kind": "optional", "type": "string", "description": "

Unique code for the promotion rule (promotionCode)

", "example": "PROMO-2026-SUMMER", "minLength": 1, "maxLength": 20 }, { "name": "name", "kind": "optional", "type": "string", "description": "

Human-readable name for this promotion rule shown in the admin UI.

", "example": "Summer 2026 Promotion", "minLength": 1, "maxLength": 100 }, { "name": "description", "kind": "optional", "type": "string", "description": "Short description of the promotion shown to members online.", "example": "Earn 500 bonus points on any qualifying stay.", "maxLength": 300 }, { "name": "typeCode", "kind": "optional", "type": "string", "description": "

Categorises this promotion rule. Values for this field need to match datacodes setup with a CodeType of: PromotionRuleType.

", "example": "Points" }, { "name": "subTypeCode", "kind": "optional", "type": "string", "description": "

Sub-classification of the promotion type. Values for this field need to match datacodes setup with a CodeType of: PromotionRuleSubType.

", "example": "Standard" }, { "name": "statusCode", "kind": "optional", "type": "string", "description": "

Lifecycle status of the rule. Values for this field need to match datacodes setup with a CodeType of: ProBonusStatus. Active (A) rules are eligible to fire; Inactive (I) rules are skipped.

", "example": "A" }, { "name": "startDate", "kind": "optional", "type": "string", "description": "First date on which qualifying transactions can trigger this rule.", "example": "2026-01-01", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "Last date on which qualifying transactions can trigger this rule.", "example": "2026-12-31", "format": "date" }, { "name": "campaignName", "kind": "optional", "type": "string", "description": "Name of the campaign this rule is grouped under.", "example": "Q1 2026 Enrollment Campaign" }, { "name": "displayOnline", "kind": "optional", "type": "boolean", "description": "

Controls whether this promotion is surfaced on member-facing online channels.

", "example": true }, { "name": "displayOnlineUntilDate", "kind": "optional", "type": "string", "description": "

Date after which this rule is no longer surfaced on member-facing online channels.

", "example": "2026-12-31", "format": "date" }, { "name": "contentKey", "kind": "optional", "type": "string", "description": "Identifier used to associate this rule with localised content.", "example": "promo-summer-2026" }, { "name": "clientTag", "kind": "optional", "type": "string", "description": "

Client-defined tag code. Values for this field need to match datacodes setup with a CodeType of: PromotionClientTag. Requires feature flag promotions-client-tag to be enabled.

", "example": "VIP" }, { "name": "workflowStatus", "kind": "optional", "type": "string", "description": "

Editorial state of the rule. Values for this field need to match datacodes setup with a CodeType of: RuleWorkflowStatus.

", "example": "WORKING" }, { "name": "rawExpression", "kind": "optional", "type": "string", "description": "Boolean eligibility expression evaluated against member and accrual context." }, { "name": "dataReleaseName", "kind": "optional", "type": "string", "description": "

Name of the data release bundle this rule is assigned to. Pass a name to assign the rule to an existing release; omit or set to null to leave unassigned.

", "example": "Rules Release 2025", "maxLength": 250 }, { "name": "limits", "kind": "optional", "type": "object", "description": "Cap configuration controlling how many times a promotion rule can fire per member.", "modelRef": "#/components/schemas/PromotionRuleLimits", "customType": "PromotionRuleLimits", "schema": [ { "name": "occurrenceLimit", "kind": "optional", "type": "integer", "description": "Maximum number of times this promotion rule can fire for a single member over its lifetime.", "example": 3, "format": "int64" }, { "name": "pointLimit", "kind": "optional", "type": "integer", "description": "Cumulative point cap per member across all firings of this promotion rule.", "example": 5000, "format": "int64" }, { "name": "graceLimit", "kind": "optional", "type": "integer", "description": "

Number of days after endDate during which late-arriving transactions are still eligible to trigger this rule.

", "example": 30, "format": "int32" }, { "name": "uniqueProperty", "kind": "optional", "type": "string", "description": "

Member property used to enforce uniqueness — the rule can fire at most once per distinct value of this property. When present, enforceUnique is implicitly true. Values for this field need to match a supported member property key.

", "example": "ace01" }, { "name": "uniqueAcrossAllCycles", "kind": "optional", "type": "boolean", "description": "

When true, uniqueness is enforced across all promotion cycles rather than within a single cycle only.

", "example": false }, { "name": "transactionsPerDay", "kind": "optional", "type": "integer", "description": "Maximum number of times this promotion rule can fire for a single member within a single calendar day.", "example": 1, "format": "int32" } ] }, { "name": "invoicing", "kind": "optional", "type": "object", "description": "Billing configuration applied when the cost of this rule is charged back to an invoiced party.", "modelRef": "#/components/schemas/ProBonusInvoicing", "customType": "ProBonusInvoicing", "schema": [ { "name": "billable", "kind": "optional", "type": "boolean", "description": "

When true, the cost of this rule is charged back to the invoiced party identified by billableToTypeCode.

" }, { "name": "billableToTypeCode", "kind": "optional", "type": "string", "description": "

The party billed when billable is true. Values for this field need to match datacodes setup with a CodeType of: InvoiceTo. e.g. Hotel or Corporate.

", "example": "Hotel" }, { "name": "invoiceTypeCode", "kind": "optional", "type": "string", "description": "

Invoice classification applied when billableToTypeCode is Hotel. Values for this field need to match datacodes setup with a CodeType of: InvoiceType.

", "example": "Standard" }, { "name": "invoiceAmount", "kind": "optional", "type": "number", "description": "Fixed fee charged per occurrence when billable is true.", "example": 25 }, { "name": "invoiceRate", "kind": "optional", "type": "number", "description": "

Rate-based fee charged per occurrence when billable is true. Client-specific — may not be available on all deployments.

", "example": 0.15 }, { "name": "ownerName", "kind": "optional", "type": "string", "description": "Name of the owner responsible for this rule.", "example": "Marketing Team" }, { "name": "taxable", "kind": "optional", "type": "boolean", "description": "

When true, points awarded by this rule are treated as taxable income.

", "example": false } ] }, { "name": "results", "kind": "optional", "type": "object", "description": "

Reward outcomes applied when a bonus or promotion rule fires. Set only the fields relevant to the desired reward type(s).

", "modelRef": "#/components/schemas/ProBonusResults", "customType": "ProBonusResults", "schema": [ { "name": "pointCategoryCode", "kind": "optional", "type": "string", "description": "

The point category bucket into which awarded points are deposited. Values for this field need to match datacodes setup with a CodeType of: PointCategory. e.g. Base or Bonus.

", "example": "Base" }, { "name": "resultTypeCode", "kind": "optional", "type": "string", "description": "

How the point award is calculated. Values for this field need to match datacodes setup with a CodeType of: ResultType. Fixed awards exactly resultAmount points; Percent awards resultAmount percent of the accrual points; Provided uses the amount supplied by the transaction.

", "example": "Fixed" }, { "name": "resultAmount", "kind": "optional", "type": "number", "description": "

Award magnitude interpreted according to resultTypeCode: the exact point count for Fixed, or the percentage multiplier for Percent. Not used when resultTypeCode is Provided.

", "example": 500 }, { "name": "resultSubTypeCode", "kind": "optional", "type": "string", "description": "

Sub-classification of the point result type. Values for this field need to match datacodes setup with a CodeType of: ResultSubType. Applicable to bonus rules only; not used for promo rules.

", "example": "Base" }, { "name": "tierQualifier", "kind": "optional", "type": "boolean", "description": "

When true, the awarded points also count toward tier qualification.

", "default": false }, { "name": "activityPointsMultiplier", "kind": "optional", "type": "number", "description": "

Multiplier applied to a member activity counter to derive the point award. Mutually exclusive with resultTypeCode/resultAmount. Applicable to bonus rules only; not used for promo rules.

", "example": 2.5 }, { "name": "activityPointCategoryCode", "kind": "optional", "type": "string", "description": "

Point category for activity-based awarded points. Values for this field need to match datacodes setup with a CodeType of: PointCategory. Required when activityPointsMultiplier is set. Applicable to bonus rules only; not used for promo rules.

", "example": "Base" }, { "name": "activityCounterTypeCode", "kind": "optional", "type": "string", "description": "

Counter type whose accumulated value is multiplied by activityPointsMultiplier. Values for this field need to match datacodes setup with a CodeType of: CounterType. Required when activityPointsMultiplier is set. Applicable to bonus rules only; not used for promo rules.

", "example": "Nights" }, { "name": "activityTierQualifier", "kind": "optional", "type": "boolean", "description": "

When true, points awarded via activityPointsMultiplier also count toward tier qualification. Applicable to bonus rules only; not used for promo rules.

", "default": false }, { "name": "tierCode", "kind": "optional", "type": "string", "description": "Tier to assign to the member when this rule fires.", "example": "GOLD" }, { "name": "tierExpireDays", "kind": "optional", "type": "integer", "description": "Number of days until the assigned tier expires. Used only for Trial tiers.", "example": 90, "format": "int32" }, { "name": "tierExpireDate", "kind": "optional", "type": "string", "description": "Exact expiration date for the assigned tier. Used only for Trial tiers.", "example": "2026-12-31", "format": "date" }, { "name": "tierPeriods", "kind": "optional", "type": "integer", "description": "Number of qualification periods the assigned tier is valid for. Used only for Trial tiers.", "example": 2, "format": "int32" }, { "name": "futureTierCode", "kind": "optional", "type": "string", "description": "Tier to assign to the member at the start of the next qualification period.", "example": "PLATINUM" }, { "name": "futureTierExpireDays", "kind": "optional", "type": "integer", "description": "Number of days until the future tier assignment expires. Used only for Trial tiers.", "example": 90, "format": "int32" }, { "name": "futureTierExpireDate", "kind": "optional", "type": "string", "description": "Exact expiration date for the future tier assignment. Used only for Trial tiers.", "example": "2027-12-31", "format": "date" }, { "name": "futureTierPeriods", "kind": "optional", "type": "integer", "description": "Number of qualification periods the future tier is valid for. Used only for Trial tiers.", "example": 2, "format": "int32" }, { "name": "exactEndTierCode", "kind": "optional", "type": "string", "description": "Tier whose end date is pinned to an exact date rather than derived from the qualification period.", "example": "SILVER" }, { "name": "exactEndTierExpireDate", "kind": "optional", "type": "string", "description": "Exact date on which the tier assigned via exactEndTierCode expires.", "example": "2026-06-30", "format": "date" }, { "name": "couponAwardName", "kind": "optional", "type": "string", "description": "Name of the coupon award template to issue when this rule fires.", "example": "Welcome Award" }, { "name": "badgeName", "kind": "optional", "type": "string", "description": "Name of the badge to award when this rule fires.", "example": "Gold Status Badge" }, { "name": "promotionRuleCode", "kind": "optional", "type": "string", "description": "Promotion rule to enroll the member in when this rule fires.", "example": "PROMO-2026-SUMMER" }, { "name": "redemptionRuleCode", "kind": "optional", "type": "string", "description": "Redemption rule to trigger when this rule fires.", "example": "FREE-NIGHT" }, { "name": "redemptionQuantity", "kind": "optional", "type": "integer", "description": "Number of redemptions to execute. Required when redemptionRuleCode is set.", "example": 1, "format": "int32" }, { "name": "communicationKey", "kind": "optional", "type": "string", "description": "Item key of the communication template to send when this rule fires.", "example": "ENROLL_WELCOME" }, { "name": "segmentCode", "kind": "optional", "type": "string", "description": "Segment to add the member to when this rule fires.", "example": "VIP-SEGMENT" }, { "name": "bonusRuleCode", "kind": "optional", "type": "string", "description": "

Secondary bonus rule to trigger when this rule fires (chained bonus).

", "example": "ENROLL-FOLLOW-UP" }, { "name": "cancellable", "kind": "optional", "type": "boolean", "description": "

When true, the result of this rule can be cancelled retroactively. Applicable to bonus rules only; not used for promo rules.

", "default": false }, { "name": "resultExternalCode", "kind": "optional", "type": "string", "description": "

Code identifying the external fulfillment target for this rule result. Values must match datacodes configured client-side. Client-specific — may not be available on all deployments.

", "example": "EXTERNAL_REWARD_CODE" }, { "name": "counters", "kind": "optional", "type": "array", "description": "

Tier-qualifying activity counters to award when this rule fires.

", "modelRef": "#/components/schemas/ProBonusResultCounter", "customType": "ProBonusResultCounter[]", "schema": [ { "name": "counterType", "kind": "optional", "type": "string", "description": "

The type of activity counter to award. Values for this field need to match datacodes setup with a CodeType of: CounterType. Determines which qualifying activity metric (e.g. Nights, Stays, Spend) is credited when the rule fires.

", "example": "Nights" }, { "name": "counterValue", "kind": "optional", "type": "number", "description": "

The number of counter units to award. Interpreted according to counterResultType — a fixed quantity, a percentage of the accrual's earned counter value, or the exact value provided by the transaction.

", "example": 10 }, { "name": "counterResultType", "kind": "optional", "type": "string", "description": "

How counterValue is applied to determine the awarded counter amount. Values for this field need to match datacodes setup with a CodeType of: CounterResultType. Fixed awards the exact counterValue; Percent awards counterValue percent of the accrual counter; Provided awards the counter value supplied by the transaction.

", "example": "Fixed" } ] } ] }, { "name": "registration", "kind": "optional", "type": "object", "description": "Registration configuration controlling when and how members can enrol in this promotion rule.", "modelRef": "#/components/schemas/PromotionRuleRegistration", "customType": "PromotionRuleRegistration", "schema": [ { "name": "startDate", "kind": "optional", "type": "string", "description": "First date on which members can register for this promotion.", "example": "2025-12-01", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "Last date on which members can register for this promotion.", "example": "2026-01-31", "format": "date" }, { "name": "processRetroAccruals", "kind": "optional", "type": "boolean", "description": "

When true, accruals that occurred before registration are retroactively evaluated against this promotion rule.

", "example": true }, { "name": "trackRegistrationSource", "kind": "optional", "type": "boolean", "description": "

When true, the channel through which a member registered for this promotion is recorded.

", "example": false }, { "name": "autoRegister", "kind": "optional", "type": "boolean", "description": "

When true, eligible members are automatically registered for this promotion without requiring explicit opt-in.

", "example": false }, { "name": "awardOnRegistration", "kind": "optional", "type": "boolean", "description": "

When true, the promotion result is awarded at the point of registration rather than on qualifying transaction.

", "example": false }, { "name": "registrationChannelCode", "kind": "optional", "type": "string", "description": "

Code identifying the channel through which registration is allowed. Values for this field need to match datacodes setup with a CodeType of: RegistrationChannel.

", "example": "CAL" }, { "name": "registrationChannelSmartGroupId", "kind": "optional", "type": "integer", "description": "ID of the smart group defining the set of registration channels allowed for this promotion.", "example": 100200, "format": "int64" }, { "name": "minUserRoleCode", "kind": "optional", "type": "string", "description": "Name of the minimum user role required to register a member for this promotion.", "example": "SUPERVISOR" }, { "name": "restricted", "kind": "optional", "type": "boolean", "readOnly": true, "description": "

When true, members must be explicitly registered to participate in this promotion. Registration dates are collected separately from the promotion start/end dates.

", "example": false } ] }, { "name": "qualification", "kind": "optional", "type": "object", "description": "

Qualifying-behaviour configuration controlling how member activity is counted and evaluated against this promotion rule.

", "modelRef": "#/components/schemas/PromotionRuleQualification", "customType": "PromotionRuleQualification", "schema": [ { "name": "counters", "kind": "optional", "type": "array", "description": "Counter targets that must be reached for this promotion rule to fire. Each entry defines a counter type and the qualifying threshold.", "modelRef": "#/components/schemas/PromotionRuleQualificationCounter", "customType": "PromotionRuleQualificationCounter[]", "schema": [ { "name": "counterTypeCode", "kind": "optional", "type": "string", "description": "

The type of activity being counted. Values for this field need to match datacodes setup with a CodeType of: CounterType.

", "example": "Nights" }, { "name": "target", "kind": "optional", "type": "number", "description": "Count at which the promotion rule fires.", "example": 5 }, { "name": "maxIncrement", "kind": "optional", "type": "integer", "description": "Maximum amount by which this counter can be incremented in a single transaction.", "example": 1, "format": "int32" }, { "name": "sortOrder", "kind": "optional", "type": "integer", "description": "Display order of this counter relative to other counters on the promotion rule.", "example": 1, "format": "int32" }, { "name": "counterThresholds", "kind": "optional", "type": "array", "description": "Intermediate counter targets that trigger incremental rewards before the main target is reached.", "modelRef": "#/components/schemas/PromotionRuleCounterThreshold", "customType": "PromotionRuleCounterThreshold[]", "schema": [ { "name": "triggerValue", "kind": "optional", "type": "number", "description": "Counter value at which this threshold fires.", "example": 3 }, { "name": "results", "kind": "optional", "type": "object", "description": "

Reward outcomes applied when a bonus or promotion rule fires. Set only the fields relevant to the desired reward type(s).

", "modelRef": "#/components/schemas/ProBonusResults", "customType": "ProBonusResults", "schema": [ { "name": "pointCategoryCode", "kind": "optional", "type": "string", "description": "

The point category bucket into which awarded points are deposited. Values for this field need to match datacodes setup with a CodeType of: PointCategory. e.g. Base or Bonus.

", "example": "Base" }, { "name": "resultTypeCode", "kind": "optional", "type": "string", "description": "

How the point award is calculated. Values for this field need to match datacodes setup with a CodeType of: ResultType. Fixed awards exactly resultAmount points; Percent awards resultAmount percent of the accrual points; Provided uses the amount supplied by the transaction.

", "example": "Fixed" }, { "name": "resultAmount", "kind": "optional", "type": "number", "description": "

Award magnitude interpreted according to resultTypeCode: the exact point count for Fixed, or the percentage multiplier for Percent. Not used when resultTypeCode is Provided.

", "example": 500 }, { "name": "resultSubTypeCode", "kind": "optional", "type": "string", "description": "

Sub-classification of the point result type. Values for this field need to match datacodes setup with a CodeType of: ResultSubType. Applicable to bonus rules only; not used for promo rules.

", "example": "Base" }, { "name": "tierQualifier", "kind": "optional", "type": "boolean", "description": "

When true, the awarded points also count toward tier qualification.

", "default": false }, { "name": "activityPointsMultiplier", "kind": "optional", "type": "number", "description": "

Multiplier applied to a member activity counter to derive the point award. Mutually exclusive with resultTypeCode/resultAmount. Applicable to bonus rules only; not used for promo rules.

", "example": 2.5 }, { "name": "activityPointCategoryCode", "kind": "optional", "type": "string", "description": "

Point category for activity-based awarded points. Values for this field need to match datacodes setup with a CodeType of: PointCategory. Required when activityPointsMultiplier is set. Applicable to bonus rules only; not used for promo rules.

", "example": "Base" }, { "name": "activityCounterTypeCode", "kind": "optional", "type": "string", "description": "

Counter type whose accumulated value is multiplied by activityPointsMultiplier. Values for this field need to match datacodes setup with a CodeType of: CounterType. Required when activityPointsMultiplier is set. Applicable to bonus rules only; not used for promo rules.

", "example": "Nights" }, { "name": "activityTierQualifier", "kind": "optional", "type": "boolean", "description": "

When true, points awarded via activityPointsMultiplier also count toward tier qualification. Applicable to bonus rules only; not used for promo rules.

", "default": false }, { "name": "tierCode", "kind": "optional", "type": "string", "description": "Tier to assign to the member when this rule fires.", "example": "GOLD" }, { "name": "tierExpireDays", "kind": "optional", "type": "integer", "description": "Number of days until the assigned tier expires. Used only for Trial tiers.", "example": 90, "format": "int32" }, { "name": "tierExpireDate", "kind": "optional", "type": "string", "description": "Exact expiration date for the assigned tier. Used only for Trial tiers.", "example": "2026-12-31", "format": "date" }, { "name": "tierPeriods", "kind": "optional", "type": "integer", "description": "Number of qualification periods the assigned tier is valid for. Used only for Trial tiers.", "example": 2, "format": "int32" }, { "name": "futureTierCode", "kind": "optional", "type": "string", "description": "Tier to assign to the member at the start of the next qualification period.", "example": "PLATINUM" }, { "name": "futureTierExpireDays", "kind": "optional", "type": "integer", "description": "Number of days until the future tier assignment expires. Used only for Trial tiers.", "example": 90, "format": "int32" }, { "name": "futureTierExpireDate", "kind": "optional", "type": "string", "description": "Exact expiration date for the future tier assignment. Used only for Trial tiers.", "example": "2027-12-31", "format": "date" }, { "name": "futureTierPeriods", "kind": "optional", "type": "integer", "description": "Number of qualification periods the future tier is valid for. Used only for Trial tiers.", "example": 2, "format": "int32" }, { "name": "exactEndTierCode", "kind": "optional", "type": "string", "description": "Tier whose end date is pinned to an exact date rather than derived from the qualification period.", "example": "SILVER" }, { "name": "exactEndTierExpireDate", "kind": "optional", "type": "string", "description": "Exact date on which the tier assigned via exactEndTierCode expires.", "example": "2026-06-30", "format": "date" }, { "name": "couponAwardName", "kind": "optional", "type": "string", "description": "Name of the coupon award template to issue when this rule fires.", "example": "Welcome Award" }, { "name": "badgeName", "kind": "optional", "type": "string", "description": "Name of the badge to award when this rule fires.", "example": "Gold Status Badge" }, { "name": "promotionRuleCode", "kind": "optional", "type": "string", "description": "Promotion rule to enroll the member in when this rule fires.", "example": "PROMO-2026-SUMMER" }, { "name": "redemptionRuleCode", "kind": "optional", "type": "string", "description": "Redemption rule to trigger when this rule fires.", "example": "FREE-NIGHT" }, { "name": "redemptionQuantity", "kind": "optional", "type": "integer", "description": "Number of redemptions to execute. Required when redemptionRuleCode is set.", "example": 1, "format": "int32" }, { "name": "communicationKey", "kind": "optional", "type": "string", "description": "Item key of the communication template to send when this rule fires.", "example": "ENROLL_WELCOME" }, { "name": "segmentCode", "kind": "optional", "type": "string", "description": "Segment to add the member to when this rule fires.", "example": "VIP-SEGMENT" }, { "name": "bonusRuleCode", "kind": "optional", "type": "string", "description": "

Secondary bonus rule to trigger when this rule fires (chained bonus).

", "example": "ENROLL-FOLLOW-UP" }, { "name": "cancellable", "kind": "optional", "type": "boolean", "description": "

When true, the result of this rule can be cancelled retroactively. Applicable to bonus rules only; not used for promo rules.

", "default": false }, { "name": "resultExternalCode", "kind": "optional", "type": "string", "description": "

Code identifying the external fulfillment target for this rule result. Values must match datacodes configured client-side. Client-specific — may not be available on all deployments.

", "example": "EXTERNAL_REWARD_CODE" }, { "name": "counters", "kind": "optional", "type": "array", "description": "

Tier-qualifying activity counters to award when this rule fires.

", "modelRef": "#/components/schemas/ProBonusResultCounter", "customType": "ProBonusResultCounter[]", "schema": [ { "name": "counterType", "kind": "optional", "type": "string", "description": "

The type of activity counter to award. Values for this field need to match datacodes setup with a CodeType of: CounterType. Determines which qualifying activity metric (e.g. Nights, Stays, Spend) is credited when the rule fires.

", "example": "Nights" }, { "name": "counterValue", "kind": "optional", "type": "number", "description": "

The number of counter units to award. Interpreted according to counterResultType — a fixed quantity, a percentage of the accrual's earned counter value, or the exact value provided by the transaction.

", "example": 10 }, { "name": "counterResultType", "kind": "optional", "type": "string", "description": "

How counterValue is applied to determine the awarded counter amount. Values for this field need to match datacodes setup with a CodeType of: CounterResultType. Fixed awards the exact counterValue; Percent awards counterValue percent of the accrual counter; Provided awards the counter value supplied by the transaction.

", "example": "Fixed" } ] } ] } ] } ] }, { "name": "preQualificationCounters", "kind": "optional", "type": "array", "description": "Counter targets that must be satisfied before a member becomes eligible to progress toward the main promotion targets.", "modelRef": "#/components/schemas/PromotionRulePreQualificationCounter", "customType": "PromotionRulePreQualificationCounter[]", "schema": [ { "name": "counterTypeCode", "kind": "optional", "type": "string", "description": "

The type of activity being counted. Values for this field need to match datacodes setup with a CodeType of: CounterType.

", "example": "Nights" }, { "name": "target", "kind": "optional", "type": "number", "description": "

Count at which the pre-qualification condition is met.

", "example": 2 }, { "name": "maxIncrement", "kind": "optional", "type": "integer", "description": "Maximum amount by which this counter can be incremented in a single transaction.", "example": 1, "format": "int32" } ] }, { "name": "counterExpression", "kind": "optional", "type": "string", "description": "

Boolean expression evaluated against the promotion counters to determine qualification. When present, overrides simple threshold logic.

", "example": "(C1 AND C2) OR C3" }, { "name": "activityPeriod", "kind": "optional", "type": "integer", "description": "Length of the activity window in days. Only transactions falling within this rolling window are counted toward promotion progress.", "example": 90, "format": "int32" }, { "name": "slidingQualificationPeriod", "kind": "optional", "type": "integer", "description": "

Period length in days within which the required number of qualifying transactions must occur. Used for sliding-window promotions.

", "example": 30, "format": "int64" }, { "name": "limitedTimeSegment", "kind": "optional", "type": "boolean", "description": "

When true, qualifying activity is restricted to a defined time segment rather than the full promotion period.

", "example": false }, { "name": "rewardThresholds", "kind": "optional", "type": "boolean", "description": "

When true, the promotion has one or more reward thresholds; members earn an incremental result each time a threshold is crossed rather than a single result at completion.

", "example": false }, { "name": "renewableCounters", "kind": "optional", "type": "boolean", "description": "

When true, promotion counters reset to zero after each qualifying accrual is processed, allowing the rule to fire repeatedly within a cycle.

", "example": false } ] } ], "modelRef": "#/components/schemas/PromotionRule", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "OAuth2", "name": "OAuth2", "kind": "optional", "type": "oauth2", "description": "

See https://docs.wearephaedon.com/docs/platform-api-authentication

", "oauth2Flows": { "clientCredentials": { "tokenUrl": "https://phaedon.oktapreview.com/oauth2/auscfbbmieFBGGOzR1d7/v1/token", "scopes": { "api:custom-data:read": "Grants read access to custom data information", "api:custom-data:modify": "Grants modify access to custom data information", "api:data-codes:read": "Grants read access to data codes", "api:data-codes:modify": "Grants modify access to data codes", "api:coupon-compensation:read": "Grants read access to compensations for coupon code", "api:coupon-compensation:create": "Grants access to create compensations for coupon code", "api:coupon-compensation:modify": "Grants access to edit compensation nights for coupon code", "api:coupon-request:modify": "Grants modify access to create coupons", "api:member:search": "Grants search access to member information", "api:member:verify": "Grants verify access to member information", "api:member:merge": "Grants access to merge members", "api:member:enroll": "Grants access to enroll members", "api:member:modify": "Grants modify access to member information", "api:member:read": "Grants read access to member information", "api:member:close": "Grants access to close member account", "api:member:migrate": "Grants access to migrate member accounts", "api:member-address:read": "Grants read access to member address information", "api:member-address:modify": "Grants modify access to member address information", "api:member-alias:read": "Grants read access to member alias information", "api:member-alias:modify": "Grants modify access to member alias information", "api:member-badge:read": "Grants read access to member badge information", "api:member-badge:modify": "Grants modify access to member badge information", "api:member-bonus:add": "Grants access to add a bonus to a member", "api:member-bonus:read": "Grants read access to member bonus information", "api:member-comments:read": "Grants read access to member comments information", "api:member-comments:modify": "Grants modify access to member comments information", "api:member-communication:read": "Grants read access to member communication information", "api:member-communication:modify": "Grants modify access to member communication information", "api:member-coupon:read": "Grants read access to member coupon information", "api:member-coupon-use:cancel": "Grants access to cancel member coupon uses", "api:member-coupon:transfer": "Grants access to transfer a member coupon", "api:member-coupon-use:update": "Grants access to update member coupon uses", "api:member-currency:read": "Grants read access to member currency information", "api:member-currency:adjust": "Grants access to adjust member currency", "api:member-currency:migrate": "Grants access to migrate member currency", "api:member-currency-conversion:convert": "Grants access to convert member currency", "api:member-email:read": "Grants read access to member email information", "api:member-email:modify": "Grants modify access to member email information", "api:member-event:read": "Grants read access to member events", "api:member-event:modify": "Grants modify access to member events", "api:event-rule:read": "Grants read access to event rules", "api:event-rule:modify": "Grants access to modify event rule", "api:event-rule:admin": "Grants full admin access to event rules", "api:member-list:read": "Grants read access to member list information", "api:member-list:modify": "Grants modify access to member list information", "api:member-partner-link:read": "Grants read access to member partner link information", "api:member-partner-link:modify": "Grants modify access to member partner link information", "api:member-payment-card:read": "Grants read access to member payment card information", "api:member-payment-card:modify": "Grants modify access to member payment card information", "api:member-phone:read": "Grants read access to member phone information", "api:member-phone:modify": "Grants modify access to member phone information", "api:member-preference:read": "Grants read access to member preference information", "api:member-preference:modify": "Grants modify access to member preference information", "api:member-promotion:read": "Grants read access to member promotion information", "api:member-promotion:register": "Grants access to register a member into a promotion", "api:member-redemption:create": "Grants redeem access to member redemption information", "api:member-redemption:over-redeem": "Grants access to over redeem", "api:member-redemption:read": "Grants read access to member redemption information", "api:member-redemption:cancel": "Grants access to cancel member redemptions", "api:member-redemption:migrate": "Allows migration of member redemption information", "api:member-redemption:patch": "Grants patching access to member redemption", "api:member-tier:read": "Grants read access to member tier information", "api:member-tier:adjust": "Grants access to adjust member tiers", "api:member-tier:migrate": "Grants access to migrate member tiers", "api:member-transaction:read": "Grants read access to transaction information", "api:member-transaction:cancel": "Grants access to cancel transactions", "api:member-transaction:clone": "Grants access to clone transactions", "api:member-transfer:transfer": "Grants access to do member to member transfers", "api:preference:read": "Grants read access to preference information", "api:promotion:read": "Grants read access to promotion information", "api:tier:read": "Grant read access to tier information", "api:promotion:register": "Grants access to register a member into a promotion using token", "api:promotion-token:manage": "Grants access to generate promotion token", "api:redemption:read": "Grants read access to redemption information", "api:redemption:modify": "Grants access to modify redemption information", "api:bonus-rule:read": "Grants read access to bonus rule configuration", "api:bonus-rule:modify": "Grants access to modify bonus rule configuration", "api:bonus-rule:manage": "Grants limited admin access to bonus rule configuration", "api:bonus-rule:admin": "Grants full admin access to bonus rules", "api:promotion-rule:read": "Grants read access to promotion rule configuration", "api:promotion-rule:modify": "Grants access to modify promotion rule configuration", "api:promotion-rule:manage": "Grants limited admin access to promotion rule configuration", "api:promotion-rule:admin": "Grants full admin access to promotion rules", "api:reports:under-investigation": "Grants access to under investigation report", "api:transaction:submit": "Grants access to submit transactions", "api:transaction:migrate": "Grants access to migrate transactions", "api:user:read": "Grants access to read user information", "api:user:modify": "Grants access to create user", "api:user-task:read": "Grants read access to user tasks", "api:user-task:modify": "Grants modify access to user tasks", "api:user-role:read": "Grants read access to user roles", "api:user-role:modify": "Grants modify access to user roles", "api:compensation:read": "Grants read access to hotel summary information", "api:compensation:modify": "Grants modify access to hotel summary information", "api:member-referral:read": "Grants read access to member referral information", "api:member-referral:modify": "Grants modify access to member referral information", "api:member-referral-codes:read": "Grants read access to member referral codes", "api:member-referral-codes:create": "Grants access to create member referral codes", "api:outbound-notification:modify": "Grants access to send outbound notification", "api:outbound-notification:read": "Grants access to read outbound notification types", "api:background-task:read": "Grants read access to background task information", "api:async-task:create": "Grants access to submit operations for background processing", "api:async-task:read": "Grants read access to background processing results", "api:audit-configuration:read": "Grants read access to audit configuration information", "api:audit-configuration:modify": "Grants modify access to audit configuration information", "api:badge:read": "Grant read access to badge information", "api:broadcast-messages:read": "Grant Read access to broadcast messages", "api:expression-config:read": "Grant read access to expression builder configuration", "api:managed-entity:read": "Grant read access to managed entity data", "api:customer-satisfaction:modify": "Grants modify access to customer satisfaction metrics", "api:member-linked-account:modify": "Grant modify access to member linked account", "api:member-linked-account:read": "Grants access to read linked member accounts", "api:enroll-codes:read": "Grants access to read enroll codes", "api:contact-us:modify": "Grants access to submit Contact Us inquiry", "api:data-release:read": "Grants read access to data releases", "api:points-pool:read": "Grants read access to points pools", "api:points-pool:modify": "Grants modify access to points pools", "api:segment:read": "Grants read access to segments", "api:segment:modify": "Grants modify access to segments", "api:communication-type:read": "Grants read access to communication types", "api:communication-type:modify": "Grants modify access to communication types", "api:member-status-match:read": "Grants read access to status match eligibility and submitted images/applications", "api:member-status-match:create": "Grants access to upload status match images and submit applications" } } }, "requiredScopes": [ "api:promotion-rule:modify" ] } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Success", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "PromotionRule", "schema": [ { "name": "code", "kind": "optional", "type": "string", "description": "

Unique code for the promotion rule (promotionCode)

", "example": "PROMO-2026-SUMMER", "minLength": 1, "maxLength": 20 }, { "name": "name", "kind": "optional", "type": "string", "description": "

Human-readable name for this promotion rule shown in the admin UI.

", "example": "Summer 2026 Promotion", "minLength": 1, "maxLength": 100 }, { "name": "description", "kind": "optional", "type": "string", "description": "Short description of the promotion shown to members online.", "example": "Earn 500 bonus points on any qualifying stay.", "maxLength": 300 }, { "name": "typeCode", "kind": "optional", "type": "string", "description": "

Categorises this promotion rule. Values for this field need to match datacodes setup with a CodeType of: PromotionRuleType.

", "example": "Points" }, { "name": "subTypeCode", "kind": "optional", "type": "string", "description": "

Sub-classification of the promotion type. Values for this field need to match datacodes setup with a CodeType of: PromotionRuleSubType.

", "example": "Standard" }, { "name": "statusCode", "kind": "optional", "type": "string", "description": "

Lifecycle status of the rule. Values for this field need to match datacodes setup with a CodeType of: ProBonusStatus. Active (A) rules are eligible to fire; Inactive (I) rules are skipped.

", "example": "A" }, { "name": "startDate", "kind": "optional", "type": "string", "description": "First date on which qualifying transactions can trigger this rule.", "example": "2026-01-01", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "Last date on which qualifying transactions can trigger this rule.", "example": "2026-12-31", "format": "date" }, { "name": "campaignName", "kind": "optional", "type": "string", "description": "Name of the campaign this rule is grouped under.", "example": "Q1 2026 Enrollment Campaign" }, { "name": "displayOnline", "kind": "optional", "type": "boolean", "description": "

Controls whether this promotion is surfaced on member-facing online channels.

", "example": true }, { "name": "displayOnlineUntilDate", "kind": "optional", "type": "string", "description": "

Date after which this rule is no longer surfaced on member-facing online channels.

", "example": "2026-12-31", "format": "date" }, { "name": "contentKey", "kind": "optional", "type": "string", "description": "Identifier used to associate this rule with localised content.", "example": "promo-summer-2026" }, { "name": "clientTag", "kind": "optional", "type": "string", "description": "

Client-defined tag code. Values for this field need to match datacodes setup with a CodeType of: PromotionClientTag. Requires feature flag promotions-client-tag to be enabled.

", "example": "VIP" }, { "name": "workflowStatus", "kind": "optional", "type": "string", "description": "

Editorial state of the rule. Values for this field need to match datacodes setup with a CodeType of: RuleWorkflowStatus.

", "example": "WORKING" }, { "name": "rawExpression", "kind": "optional", "type": "string", "description": "Boolean eligibility expression evaluated against member and accrual context." }, { "name": "dataReleaseName", "kind": "optional", "type": "string", "description": "

Name of the data release bundle this rule is assigned to. Pass a name to assign the rule to an existing release; omit or set to null to leave unassigned.

", "example": "Rules Release 2025", "maxLength": 250 }, { "name": "dataReleaseItemStatus", "kind": "optional", "type": "string", "readOnly": true, "description": "

Deployment status of this rule within its data release. Values for this field need to match datacodes setup with a CodeType of: DataReleaseItemStatus. e.g. LIVE or PENDING.

", "example": "LIVE", "maxLength": 50 }, { "name": "limits", "kind": "optional", "type": "object", "description": "Cap configuration controlling how many times a promotion rule can fire per member.", "modelRef": "#/components/schemas/PromotionRuleLimits", "customType": "PromotionRuleLimits", "schema": [ { "name": "occurrenceLimit", "kind": "optional", "type": "integer", "description": "Maximum number of times this promotion rule can fire for a single member over its lifetime.", "example": 3, "format": "int64" }, { "name": "pointLimit", "kind": "optional", "type": "integer", "description": "Cumulative point cap per member across all firings of this promotion rule.", "example": 5000, "format": "int64" }, { "name": "graceLimit", "kind": "optional", "type": "integer", "description": "

Number of days after endDate during which late-arriving transactions are still eligible to trigger this rule.

", "example": 30, "format": "int32" }, { "name": "uniqueProperty", "kind": "optional", "type": "string", "description": "

Member property used to enforce uniqueness — the rule can fire at most once per distinct value of this property. When present, enforceUnique is implicitly true. Values for this field need to match a supported member property key.

", "example": "ace01" }, { "name": "uniqueAcrossAllCycles", "kind": "optional", "type": "boolean", "description": "

When true, uniqueness is enforced across all promotion cycles rather than within a single cycle only.

", "example": false }, { "name": "transactionsPerDay", "kind": "optional", "type": "integer", "description": "Maximum number of times this promotion rule can fire for a single member within a single calendar day.", "example": 1, "format": "int32" } ] }, { "name": "invoicing", "kind": "optional", "type": "object", "description": "Billing configuration applied when the cost of this rule is charged back to an invoiced party.", "modelRef": "#/components/schemas/ProBonusInvoicing", "customType": "ProBonusInvoicing", "schema": [ { "name": "billable", "kind": "optional", "type": "boolean", "description": "

When true, the cost of this rule is charged back to the invoiced party identified by billableToTypeCode.

" }, { "name": "billableToTypeCode", "kind": "optional", "type": "string", "description": "

The party billed when billable is true. Values for this field need to match datacodes setup with a CodeType of: InvoiceTo. e.g. Hotel or Corporate.

", "example": "Hotel" }, { "name": "invoiceTypeCode", "kind": "optional", "type": "string", "description": "

Invoice classification applied when billableToTypeCode is Hotel. Values for this field need to match datacodes setup with a CodeType of: InvoiceType.

", "example": "Standard" }, { "name": "invoiceAmount", "kind": "optional", "type": "number", "description": "Fixed fee charged per occurrence when billable is true.", "example": 25 }, { "name": "invoiceRate", "kind": "optional", "type": "number", "description": "

Rate-based fee charged per occurrence when billable is true. Client-specific — may not be available on all deployments.

", "example": 0.15 }, { "name": "ownerName", "kind": "optional", "type": "string", "description": "Name of the owner responsible for this rule.", "example": "Marketing Team" }, { "name": "taxable", "kind": "optional", "type": "boolean", "description": "

When true, points awarded by this rule are treated as taxable income.

", "example": false } ] }, { "name": "results", "kind": "optional", "type": "object", "description": "

Reward outcomes applied when a bonus or promotion rule fires. Set only the fields relevant to the desired reward type(s).

", "modelRef": "#/components/schemas/ProBonusResults", "customType": "ProBonusResults", "schema": [ { "name": "pointCategoryCode", "kind": "optional", "type": "string", "description": "

The point category bucket into which awarded points are deposited. Values for this field need to match datacodes setup with a CodeType of: PointCategory. e.g. Base or Bonus.

", "example": "Base" }, { "name": "resultTypeCode", "kind": "optional", "type": "string", "description": "

How the point award is calculated. Values for this field need to match datacodes setup with a CodeType of: ResultType. Fixed awards exactly resultAmount points; Percent awards resultAmount percent of the accrual points; Provided uses the amount supplied by the transaction.

", "example": "Fixed" }, { "name": "resultAmount", "kind": "optional", "type": "number", "description": "

Award magnitude interpreted according to resultTypeCode: the exact point count for Fixed, or the percentage multiplier for Percent. Not used when resultTypeCode is Provided.

", "example": 500 }, { "name": "resultSubTypeCode", "kind": "optional", "type": "string", "description": "

Sub-classification of the point result type. Values for this field need to match datacodes setup with a CodeType of: ResultSubType. Applicable to bonus rules only; not used for promo rules.

", "example": "Base" }, { "name": "tierQualifier", "kind": "optional", "type": "boolean", "description": "

When true, the awarded points also count toward tier qualification.

", "default": false }, { "name": "activityPointsMultiplier", "kind": "optional", "type": "number", "description": "

Multiplier applied to a member activity counter to derive the point award. Mutually exclusive with resultTypeCode/resultAmount. Applicable to bonus rules only; not used for promo rules.

", "example": 2.5 }, { "name": "activityPointCategoryCode", "kind": "optional", "type": "string", "description": "

Point category for activity-based awarded points. Values for this field need to match datacodes setup with a CodeType of: PointCategory. Required when activityPointsMultiplier is set. Applicable to bonus rules only; not used for promo rules.

", "example": "Base" }, { "name": "activityCounterTypeCode", "kind": "optional", "type": "string", "description": "

Counter type whose accumulated value is multiplied by activityPointsMultiplier. Values for this field need to match datacodes setup with a CodeType of: CounterType. Required when activityPointsMultiplier is set. Applicable to bonus rules only; not used for promo rules.

", "example": "Nights" }, { "name": "activityTierQualifier", "kind": "optional", "type": "boolean", "description": "

When true, points awarded via activityPointsMultiplier also count toward tier qualification. Applicable to bonus rules only; not used for promo rules.

", "default": false }, { "name": "tierCode", "kind": "optional", "type": "string", "description": "Tier to assign to the member when this rule fires.", "example": "GOLD" }, { "name": "tierExpireDays", "kind": "optional", "type": "integer", "description": "Number of days until the assigned tier expires. Used only for Trial tiers.", "example": 90, "format": "int32" }, { "name": "tierExpireDate", "kind": "optional", "type": "string", "description": "Exact expiration date for the assigned tier. Used only for Trial tiers.", "example": "2026-12-31", "format": "date" }, { "name": "tierPeriods", "kind": "optional", "type": "integer", "description": "Number of qualification periods the assigned tier is valid for. Used only for Trial tiers.", "example": 2, "format": "int32" }, { "name": "futureTierCode", "kind": "optional", "type": "string", "description": "Tier to assign to the member at the start of the next qualification period.", "example": "PLATINUM" }, { "name": "futureTierExpireDays", "kind": "optional", "type": "integer", "description": "Number of days until the future tier assignment expires. Used only for Trial tiers.", "example": 90, "format": "int32" }, { "name": "futureTierExpireDate", "kind": "optional", "type": "string", "description": "Exact expiration date for the future tier assignment. Used only for Trial tiers.", "example": "2027-12-31", "format": "date" }, { "name": "futureTierPeriods", "kind": "optional", "type": "integer", "description": "Number of qualification periods the future tier is valid for. Used only for Trial tiers.", "example": 2, "format": "int32" }, { "name": "exactEndTierCode", "kind": "optional", "type": "string", "description": "Tier whose end date is pinned to an exact date rather than derived from the qualification period.", "example": "SILVER" }, { "name": "exactEndTierExpireDate", "kind": "optional", "type": "string", "description": "Exact date on which the tier assigned via exactEndTierCode expires.", "example": "2026-06-30", "format": "date" }, { "name": "couponAwardName", "kind": "optional", "type": "string", "description": "Name of the coupon award template to issue when this rule fires.", "example": "Welcome Award" }, { "name": "badgeName", "kind": "optional", "type": "string", "description": "Name of the badge to award when this rule fires.", "example": "Gold Status Badge" }, { "name": "promotionRuleCode", "kind": "optional", "type": "string", "description": "Promotion rule to enroll the member in when this rule fires.", "example": "PROMO-2026-SUMMER" }, { "name": "redemptionRuleCode", "kind": "optional", "type": "string", "description": "Redemption rule to trigger when this rule fires.", "example": "FREE-NIGHT" }, { "name": "redemptionQuantity", "kind": "optional", "type": "integer", "description": "Number of redemptions to execute. Required when redemptionRuleCode is set.", "example": 1, "format": "int32" }, { "name": "communicationKey", "kind": "optional", "type": "string", "description": "Item key of the communication template to send when this rule fires.", "example": "ENROLL_WELCOME" }, { "name": "segmentCode", "kind": "optional", "type": "string", "description": "Segment to add the member to when this rule fires.", "example": "VIP-SEGMENT" }, { "name": "bonusRuleCode", "kind": "optional", "type": "string", "description": "

Secondary bonus rule to trigger when this rule fires (chained bonus).

", "example": "ENROLL-FOLLOW-UP" }, { "name": "cancellable", "kind": "optional", "type": "boolean", "description": "

When true, the result of this rule can be cancelled retroactively. Applicable to bonus rules only; not used for promo rules.

", "default": false }, { "name": "resultExternalCode", "kind": "optional", "type": "string", "description": "

Code identifying the external fulfillment target for this rule result. Values must match datacodes configured client-side. Client-specific — may not be available on all deployments.

", "example": "EXTERNAL_REWARD_CODE" }, { "name": "counters", "kind": "optional", "type": "array", "description": "

Tier-qualifying activity counters to award when this rule fires.

", "modelRef": "#/components/schemas/ProBonusResultCounter", "customType": "ProBonusResultCounter[]", "schema": [ { "name": "counterType", "kind": "optional", "type": "string", "description": "

The type of activity counter to award. Values for this field need to match datacodes setup with a CodeType of: CounterType. Determines which qualifying activity metric (e.g. Nights, Stays, Spend) is credited when the rule fires.

", "example": "Nights" }, { "name": "counterValue", "kind": "optional", "type": "number", "description": "

The number of counter units to award. Interpreted according to counterResultType — a fixed quantity, a percentage of the accrual's earned counter value, or the exact value provided by the transaction.

", "example": 10 }, { "name": "counterResultType", "kind": "optional", "type": "string", "description": "

How counterValue is applied to determine the awarded counter amount. Values for this field need to match datacodes setup with a CodeType of: CounterResultType. Fixed awards the exact counterValue; Percent awards counterValue percent of the accrual counter; Provided awards the counter value supplied by the transaction.

", "example": "Fixed" } ] } ] }, { "name": "registration", "kind": "optional", "type": "object", "description": "Registration configuration controlling when and how members can enrol in this promotion rule.", "modelRef": "#/components/schemas/PromotionRuleRegistration", "customType": "PromotionRuleRegistration", "schema": [ { "name": "startDate", "kind": "optional", "type": "string", "description": "First date on which members can register for this promotion.", "example": "2025-12-01", "format": "date" }, { "name": "endDate", "kind": "optional", "type": "string", "description": "Last date on which members can register for this promotion.", "example": "2026-01-31", "format": "date" }, { "name": "processRetroAccruals", "kind": "optional", "type": "boolean", "description": "

When true, accruals that occurred before registration are retroactively evaluated against this promotion rule.

", "example": true }, { "name": "trackRegistrationSource", "kind": "optional", "type": "boolean", "description": "

When true, the channel through which a member registered for this promotion is recorded.

", "example": false }, { "name": "autoRegister", "kind": "optional", "type": "boolean", "description": "

When true, eligible members are automatically registered for this promotion without requiring explicit opt-in.

", "example": false }, { "name": "awardOnRegistration", "kind": "optional", "type": "boolean", "description": "

When true, the promotion result is awarded at the point of registration rather than on qualifying transaction.

", "example": false }, { "name": "registrationChannelCode", "kind": "optional", "type": "string", "description": "

Code identifying the channel through which registration is allowed. Values for this field need to match datacodes setup with a CodeType of: RegistrationChannel.

", "example": "CAL" }, { "name": "registrationChannelSmartGroupId", "kind": "optional", "type": "integer", "description": "ID of the smart group defining the set of registration channels allowed for this promotion.", "example": 100200, "format": "int64" }, { "name": "minUserRoleCode", "kind": "optional", "type": "string", "description": "Name of the minimum user role required to register a member for this promotion.", "example": "SUPERVISOR" }, { "name": "restricted", "kind": "optional", "type": "boolean", "readOnly": true, "description": "

When true, members must be explicitly registered to participate in this promotion. Registration dates are collected separately from the promotion start/end dates.

", "example": false } ] }, { "name": "qualification", "kind": "optional", "type": "object", "description": "

Qualifying-behaviour configuration controlling how member activity is counted and evaluated against this promotion rule.

", "modelRef": "#/components/schemas/PromotionRuleQualification", "customType": "PromotionRuleQualification", "schema": [ { "name": "counters", "kind": "optional", "type": "array", "description": "Counter targets that must be reached for this promotion rule to fire. Each entry defines a counter type and the qualifying threshold.", "modelRef": "#/components/schemas/PromotionRuleQualificationCounter", "customType": "PromotionRuleQualificationCounter[]", "schema": [ { "name": "counterTypeCode", "kind": "optional", "type": "string", "description": "

The type of activity being counted. Values for this field need to match datacodes setup with a CodeType of: CounterType.

", "example": "Nights" }, { "name": "target", "kind": "optional", "type": "number", "description": "Count at which the promotion rule fires.", "example": 5 }, { "name": "maxIncrement", "kind": "optional", "type": "integer", "description": "Maximum amount by which this counter can be incremented in a single transaction.", "example": 1, "format": "int32" }, { "name": "sortOrder", "kind": "optional", "type": "integer", "description": "Display order of this counter relative to other counters on the promotion rule.", "example": 1, "format": "int32" }, { "name": "counterThresholds", "kind": "optional", "type": "array", "description": "Intermediate counter targets that trigger incremental rewards before the main target is reached.", "modelRef": "#/components/schemas/PromotionRuleCounterThreshold", "customType": "PromotionRuleCounterThreshold[]", "schema": [ { "name": "triggerValue", "kind": "optional", "type": "number", "description": "Counter value at which this threshold fires.", "example": 3 }, { "name": "results", "kind": "optional", "type": "object", "description": "

Reward outcomes applied when a bonus or promotion rule fires. Set only the fields relevant to the desired reward type(s).

", "modelRef": "#/components/schemas/ProBonusResults", "customType": "ProBonusResults", "schema": [ { "name": "pointCategoryCode", "kind": "optional", "type": "string", "description": "

The point category bucket into which awarded points are deposited. Values for this field need to match datacodes setup with a CodeType of: PointCategory. e.g. Base or Bonus.

", "example": "Base" }, { "name": "resultTypeCode", "kind": "optional", "type": "string", "description": "

How the point award is calculated. Values for this field need to match datacodes setup with a CodeType of: ResultType. Fixed awards exactly resultAmount points; Percent awards resultAmount percent of the accrual points; Provided uses the amount supplied by the transaction.

", "example": "Fixed" }, { "name": "resultAmount", "kind": "optional", "type": "number", "description": "

Award magnitude interpreted according to resultTypeCode: the exact point count for Fixed, or the percentage multiplier for Percent. Not used when resultTypeCode is Provided.

", "example": 500 }, { "name": "resultSubTypeCode", "kind": "optional", "type": "string", "description": "

Sub-classification of the point result type. Values for this field need to match datacodes setup with a CodeType of: ResultSubType. Applicable to bonus rules only; not used for promo rules.

", "example": "Base" }, { "name": "tierQualifier", "kind": "optional", "type": "boolean", "description": "

When true, the awarded points also count toward tier qualification.

", "default": false }, { "name": "activityPointsMultiplier", "kind": "optional", "type": "number", "description": "

Multiplier applied to a member activity counter to derive the point award. Mutually exclusive with resultTypeCode/resultAmount. Applicable to bonus rules only; not used for promo rules.

", "example": 2.5 }, { "name": "activityPointCategoryCode", "kind": "optional", "type": "string", "description": "

Point category for activity-based awarded points. Values for this field need to match datacodes setup with a CodeType of: PointCategory. Required when activityPointsMultiplier is set. Applicable to bonus rules only; not used for promo rules.

", "example": "Base" }, { "name": "activityCounterTypeCode", "kind": "optional", "type": "string", "description": "

Counter type whose accumulated value is multiplied by activityPointsMultiplier. Values for this field need to match datacodes setup with a CodeType of: CounterType. Required when activityPointsMultiplier is set. Applicable to bonus rules only; not used for promo rules.

", "example": "Nights" }, { "name": "activityTierQualifier", "kind": "optional", "type": "boolean", "description": "

When true, points awarded via activityPointsMultiplier also count toward tier qualification. Applicable to bonus rules only; not used for promo rules.

", "default": false }, { "name": "tierCode", "kind": "optional", "type": "string", "description": "Tier to assign to the member when this rule fires.", "example": "GOLD" }, { "name": "tierExpireDays", "kind": "optional", "type": "integer", "description": "Number of days until the assigned tier expires. Used only for Trial tiers.", "example": 90, "format": "int32" }, { "name": "tierExpireDate", "kind": "optional", "type": "string", "description": "Exact expiration date for the assigned tier. Used only for Trial tiers.", "example": "2026-12-31", "format": "date" }, { "name": "tierPeriods", "kind": "optional", "type": "integer", "description": "Number of qualification periods the assigned tier is valid for. Used only for Trial tiers.", "example": 2, "format": "int32" }, { "name": "futureTierCode", "kind": "optional", "type": "string", "description": "Tier to assign to the member at the start of the next qualification period.", "example": "PLATINUM" }, { "name": "futureTierExpireDays", "kind": "optional", "type": "integer", "description": "Number of days until the future tier assignment expires. Used only for Trial tiers.", "example": 90, "format": "int32" }, { "name": "futureTierExpireDate", "kind": "optional", "type": "string", "description": "Exact expiration date for the future tier assignment. Used only for Trial tiers.", "example": "2027-12-31", "format": "date" }, { "name": "futureTierPeriods", "kind": "optional", "type": "integer", "description": "Number of qualification periods the future tier is valid for. Used only for Trial tiers.", "example": 2, "format": "int32" }, { "name": "exactEndTierCode", "kind": "optional", "type": "string", "description": "Tier whose end date is pinned to an exact date rather than derived from the qualification period.", "example": "SILVER" }, { "name": "exactEndTierExpireDate", "kind": "optional", "type": "string", "description": "Exact date on which the tier assigned via exactEndTierCode expires.", "example": "2026-06-30", "format": "date" }, { "name": "couponAwardName", "kind": "optional", "type": "string", "description": "Name of the coupon award template to issue when this rule fires.", "example": "Welcome Award" }, { "name": "badgeName", "kind": "optional", "type": "string", "description": "Name of the badge to award when this rule fires.", "example": "Gold Status Badge" }, { "name": "promotionRuleCode", "kind": "optional", "type": "string", "description": "Promotion rule to enroll the member in when this rule fires.", "example": "PROMO-2026-SUMMER" }, { "name": "redemptionRuleCode", "kind": "optional", "type": "string", "description": "Redemption rule to trigger when this rule fires.", "example": "FREE-NIGHT" }, { "name": "redemptionQuantity", "kind": "optional", "type": "integer", "description": "Number of redemptions to execute. Required when redemptionRuleCode is set.", "example": 1, "format": "int32" }, { "name": "communicationKey", "kind": "optional", "type": "string", "description": "Item key of the communication template to send when this rule fires.", "example": "ENROLL_WELCOME" }, { "name": "segmentCode", "kind": "optional", "type": "string", "description": "Segment to add the member to when this rule fires.", "example": "VIP-SEGMENT" }, { "name": "bonusRuleCode", "kind": "optional", "type": "string", "description": "

Secondary bonus rule to trigger when this rule fires (chained bonus).

", "example": "ENROLL-FOLLOW-UP" }, { "name": "cancellable", "kind": "optional", "type": "boolean", "description": "

When true, the result of this rule can be cancelled retroactively. Applicable to bonus rules only; not used for promo rules.

", "default": false }, { "name": "resultExternalCode", "kind": "optional", "type": "string", "description": "

Code identifying the external fulfillment target for this rule result. Values must match datacodes configured client-side. Client-specific — may not be available on all deployments.

", "example": "EXTERNAL_REWARD_CODE" }, { "name": "counters", "kind": "optional", "type": "array", "description": "

Tier-qualifying activity counters to award when this rule fires.

", "modelRef": "#/components/schemas/ProBonusResultCounter", "customType": "ProBonusResultCounter[]", "schema": [ { "name": "counterType", "kind": "optional", "type": "string", "description": "

The type of activity counter to award. Values for this field need to match datacodes setup with a CodeType of: CounterType. Determines which qualifying activity metric (e.g. Nights, Stays, Spend) is credited when the rule fires.

", "example": "Nights" }, { "name": "counterValue", "kind": "optional", "type": "number", "description": "

The number of counter units to award. Interpreted according to counterResultType — a fixed quantity, a percentage of the accrual's earned counter value, or the exact value provided by the transaction.

", "example": 10 }, { "name": "counterResultType", "kind": "optional", "type": "string", "description": "

How counterValue is applied to determine the awarded counter amount. Values for this field need to match datacodes setup with a CodeType of: CounterResultType. Fixed awards the exact counterValue; Percent awards counterValue percent of the accrual counter; Provided awards the counter value supplied by the transaction.

", "example": "Fixed" } ] } ] } ] } ] }, { "name": "preQualificationCounters", "kind": "optional", "type": "array", "description": "Counter targets that must be satisfied before a member becomes eligible to progress toward the main promotion targets.", "modelRef": "#/components/schemas/PromotionRulePreQualificationCounter", "customType": "PromotionRulePreQualificationCounter[]", "schema": [ { "name": "counterTypeCode", "kind": "optional", "type": "string", "description": "

The type of activity being counted. Values for this field need to match datacodes setup with a CodeType of: CounterType.

", "example": "Nights" }, { "name": "target", "kind": "optional", "type": "number", "description": "

Count at which the pre-qualification condition is met.

", "example": 2 }, { "name": "maxIncrement", "kind": "optional", "type": "integer", "description": "Maximum amount by which this counter can be incremented in a single transaction.", "example": 1, "format": "int32" } ] }, { "name": "counterExpression", "kind": "optional", "type": "string", "description": "

Boolean expression evaluated against the promotion counters to determine qualification. When present, overrides simple threshold logic.

", "example": "(C1 AND C2) OR C3" }, { "name": "activityPeriod", "kind": "optional", "type": "integer", "description": "Length of the activity window in days. Only transactions falling within this rolling window are counted toward promotion progress.", "example": 90, "format": "int32" }, { "name": "slidingQualificationPeriod", "kind": "optional", "type": "integer", "description": "

Period length in days within which the required number of qualifying transactions must occur. Used for sliding-window promotions.

", "example": 30, "format": "int64" }, { "name": "limitedTimeSegment", "kind": "optional", "type": "boolean", "description": "

When true, qualifying activity is restricted to a defined time segment rather than the full promotion period.

", "example": false }, { "name": "rewardThresholds", "kind": "optional", "type": "boolean", "description": "

When true, the promotion has one or more reward thresholds; members earn an incremental result each time a threshold is crossed rather than a single result at completion.

", "example": false }, { "name": "renewableCounters", "kind": "optional", "type": "boolean", "description": "

When true, promotion counters reset to zero after each qualifying accrual is processed, allowing the rule to fire repeatedly within a cycle.

", "example": false } ] } ], "modelRef": "#/components/schemas/PromotionRule", "isExpanded": true } ] }, { "statusCode": "400", "description": "Bad request", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "", "customType": "ErrorResponse", "schema": [ { "name": "errors", "kind": "optional", "type": "array", "description": "List of errors", "modelRef": "#/components/schemas/ValidationError", "customType": "ValidationError[]", "schema": [ { "name": "code", "kind": "optional", "type": "string", "description": "Error code assigned to this violation" }, { "name": "fieldName", "kind": "optional", "type": "string", "description": "

Name of field that violated validation constraint (optional)

" }, { "name": "message", "kind": "optional", "type": "string", "description": "Internal message describing the error" }, { "name": "messageParameters", "kind": "optional", "type": "array", "description": "Error message parameters", "example": "", "itemType": "object", "customType": "object[]", "schema": [] } ] } ], "modelRef": "#/components/schemas/ErrorResponse", "isExpanded": true } ] }, { "statusCode": "401", "description": "Unauthorized", "jsonExample": "", "isExpanded": true }, { "statusCode": "403", "description": "Forbidden", "jsonExample": "", "isExpanded": true }, { "statusCode": "500", "description": "Internal error", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "Y0GeYIZwWozvBXe4JWa_b", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.b.preview.loyaltyservices.io/api/v3/promotion-rules \\\n --header 'accept: application/json'" }, { "id": "60FxS1yiMiL6DxV4qw490", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.b.preview.loyaltyservices.io/api/v3/promotion-rules\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "sllfuzNsQWKHGbfBYfE3B", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.b.preview.loyaltyservices.io/api/v3/promotion-rules\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" }, { "id": "uAetM_wOGxwtjYZNZxCf4", "language": "java", "label": "Java", "code": "OkHttpClient client = new OkHttpClient().newBuilder()\n .build();\nMediaType mediaType = MediaType.parse(\"application/json\");\nRequestBody body = RequestBody.create(mediaType, \"\");\nRequest request = new Request.Builder()\n .url(\"https://api.b.preview.loyaltyservices.io/api/v3/promotion-rules\")\n .method(\"POST\", body)\n .addHeader(\"accept\", \"application/json\")\n .addHeader(\"content-type\", \"application/json\")\n .build();\nResponse response = client.newCall(request).execute();" } ], "selectedLanguageId": "Y0GeYIZwWozvBXe4JWa_b" }, "results": { "languages": [ { "id": "NT-yxEA1m4FQgrEMaGGsq", "language": "200", "code": "// Success\n{\n \"code\": \"PROMO-2026-SUMMER\",\n \"name\": \"Summer 2026 Promotion\",\n \"description\": \"Earn 500 bonus points on any qualifying stay.\",\n \"typeCode\": \"Points\",\n \"subTypeCode\": \"Standard\",\n \"statusCode\": \"A\",\n \"startDate\": \"2026-01-01\",\n \"endDate\": \"2026-12-31\",\n \"campaignName\": \"Q1 2026 Enrollment Campaign\",\n \"displayOnline\": true,\n \"displayOnlineUntilDate\": \"2026-12-31\",\n \"contentKey\": \"promo-summer-2026\",\n \"clientTag\": \"VIP\",\n \"workflowStatus\": \"WORKING\",\n \"rawExpression\": \"\",\n \"dataReleaseName\": \"Rules Release 2025\",\n \"dataReleaseItemStatus\": \"LIVE\",\n \"limits\": {\n \"occurrenceLimit\": 3,\n \"pointLimit\": 5000,\n \"graceLimit\": 30,\n \"uniqueProperty\": \"ace01\",\n \"uniqueAcrossAllCycles\": false,\n \"transactionsPerDay\": 1\n },\n \"invoicing\": {\n \"billable\": false,\n \"billableToTypeCode\": \"Hotel\",\n \"invoiceTypeCode\": \"Standard\",\n \"invoiceAmount\": 25,\n \"invoiceRate\": 0.15,\n \"ownerName\": \"Marketing Team\",\n \"taxable\": false\n },\n \"results\": {\n \"pointCategoryCode\": \"Base\",\n \"resultTypeCode\": \"Fixed\",\n \"resultAmount\": 500,\n \"resultSubTypeCode\": \"Base\",\n \"tierQualifier\": false,\n \"activityPointsMultiplier\": 2.5,\n \"activityPointCategoryCode\": \"Base\",\n \"activityCounterTypeCode\": \"Nights\",\n \"activityTierQualifier\": false,\n \"tierCode\": \"GOLD\",\n \"tierExpireDays\": 90,\n \"tierExpireDate\": \"2026-12-31\",\n \"tierPeriods\": 2,\n \"futureTierCode\": \"PLATINUM\",\n \"futureTierExpireDays\": 90,\n \"futureTierExpireDate\": \"2027-12-31\",\n \"futureTierPeriods\": 2,\n \"exactEndTierCode\": \"SILVER\",\n \"exactEndTierExpireDate\": \"2026-06-30\",\n \"couponAwardName\": \"Welcome Award\",\n \"badgeName\": \"Gold Status Badge\",\n \"promotionRuleCode\": \"PROMO-2026-SUMMER\",\n \"redemptionRuleCode\": \"FREE-NIGHT\",\n \"redemptionQuantity\": 1,\n \"communicationKey\": \"ENROLL_WELCOME\",\n \"segmentCode\": \"VIP-SEGMENT\",\n \"bonusRuleCode\": \"ENROLL-FOLLOW-UP\",\n \"cancellable\": false,\n \"resultExternalCode\": \"EXTERNAL_REWARD_CODE\",\n \"counters\": [\n {\n \"counterType\": \"Nights\",\n \"counterValue\": 10,\n \"counterResultType\": \"Fixed\"\n }\n ]\n },\n \"registration\": {\n \"startDate\": \"2025-12-01\",\n \"endDate\": \"2026-01-31\",\n \"processRetroAccruals\": true,\n \"trackRegistrationSource\": false,\n \"autoRegister\": false,\n \"awardOnRegistration\": false,\n \"registrationChannelCode\": \"CAL\",\n \"registrationChannelSmartGroupId\": 100200,\n \"minUserRoleCode\": \"SUPERVISOR\",\n \"restricted\": false\n },\n \"qualification\": {\n \"counters\": [\n {\n \"counterTypeCode\": \"Nights\",\n \"target\": 5,\n \"maxIncrement\": 1,\n \"sortOrder\": 1,\n \"counterThresholds\": [\n {\n \"triggerValue\": 3,\n \"results\": {\n \"pointCategoryCode\": \"Base\",\n \"resultTypeCode\": \"Fixed\",\n \"resultAmount\": 500,\n \"resultSubTypeCode\": \"Base\",\n \"tierQualifier\": false,\n \"activityPointsMultiplier\": 2.5,\n \"activityPointCategoryCode\": \"Base\",\n \"activityCounterTypeCode\": \"Nights\",\n \"activityTierQualifier\": false,\n \"tierCode\": \"GOLD\",\n \"tierExpireDays\": 90,\n \"tierExpireDate\": \"2026-12-31\",\n \"tierPeriods\": 2,\n \"futureTierCode\": \"PLATINUM\",\n \"futureTierExpireDays\": 90,\n \"futureTierExpireDate\": \"2027-12-31\",\n \"futureTierPeriods\": 2,\n \"exactEndTierCode\": \"SILVER\",\n \"exactEndTierExpireDate\": \"2026-06-30\",\n \"couponAwardName\": \"Welcome Award\",\n \"badgeName\": \"Gold Status Badge\",\n \"promotionRuleCode\": \"PROMO-2026-SUMMER\",\n \"redemptionRuleCode\": \"FREE-NIGHT\",\n \"redemptionQuantity\": 1,\n \"communicationKey\": \"ENROLL_WELCOME\",\n \"segmentCode\": \"VIP-SEGMENT\",\n \"bonusRuleCode\": \"ENROLL-FOLLOW-UP\",\n \"cancellable\": false,\n \"resultExternalCode\": \"EXTERNAL_REWARD_CODE\",\n \"counters\": [\n {\n \"counterType\": \"Nights\",\n \"counterValue\": 10,\n \"counterResultType\": \"Fixed\"\n }\n ]\n }\n }\n ]\n }\n ],\n \"preQualificationCounters\": [\n {\n \"counterTypeCode\": \"Nights\",\n \"target\": 2,\n \"maxIncrement\": 1\n }\n ],\n \"counterExpression\": \"(C1 AND C2) OR C3\",\n \"activityPeriod\": 90,\n \"slidingQualificationPeriod\": 30,\n \"limitedTimeSegment\": false,\n \"rewardThresholds\": false,\n \"renewableCounters\": false\n }\n}" }, { "id": "p3e0rypDF4iy5ZmCRptiM", "language": "400", "code": "// Bad request\n{\n \"errors\": [\n {\n \"code\": \"\",\n \"fieldName\": \"\",\n \"message\": \"\",\n \"messageParameters\": [\n {}\n ]\n }\n ]\n}" }, { "id": "PhvsfQlCvrda3l9sBz-Ps", "language": "401", "code": "// Unauthorized\n" }, { "id": "LaijhUmWBNRxxCawkDGgT", "language": "403", "code": "// Forbidden\n" }, { "id": "3687uMaR2YPfDtUXZR0_A", "language": "500", "code": "// Internal error\n" } ], "selectedLanguageId": "NT-yxEA1m4FQgrEMaGGsq" } }, "children": [ { "text": "" } ] }