Global Promotions Management: End-to-End Workflow

Workflow Overview

The promotion lifecycle is divided into three distinct phases:

• Promotion Administration and Design—Define promotion definitions, eligibility constraints, rule logic, supported reward types, limits, and lifecycle state. All configuration created in this phase is persisted and reused by downstream discovery and execution APIs.
• Discovery and Enrollment—Identify and surface promotions relevant to a customer or product context and handle explicit enrollment when required by the promotion's eligibility rules.
• Transactional Execution—Evaluate promotions against cart data, resolve conflicts or prioritization, apply pricing adjustments, and generate transaction records for promotion rewards during checkout.

Phase 1: Promotion Administration and Design

In this phase, developers or business administrators define the structural and behavioral definition of a promotion. This includes promotion metadata, eligibility scope (customers, products, channels), rule logic, reward configuration, limits, and activation state. These definitions serve as inputs to runtime promotion APIs.

1. Create Promotion—Create or retrieve promotion definitions that act as the root container for all promotion behavior.
   • Make a POST request to /global-promotions-management/promotions to create a promotion. The Promotions API supports creating both promotion metadata and associated rule configurations in a single request using the promotionDetails and rules properties.
   • Make a GET request to /global-promotions-management/promotions to retrieve existing promotions for auditing, validation, or reuse.
   Result: A promotion definition is created or retrieved. When creating a promotion, the definition is established at this stage. Depending on the implementation approach, rule configuration can either be included in the creation request or configured separately using the Rule Configuration API.
2. Manage Promotion Details—Update promotion metadata and lifecycle status after creation.
   • Make a GET request to /global-promotions-management/promotions/${promotionId} to retrieve the current promotion configuration and state.
   • Make a PUT request to update values such as priority, eligibility scope, limits, or activation status.
   • Make a DELETE request to permanently remove the promotion and all associated configuration.
   Result: The promotion metadata and lifecycle state are updated. Changes directly impact whether the promotion is discoverable and eligible during runtime evaluation.
3. Configure Promotion Rules—Define qualification logic and what benefits it provides by associating rule templates and rule logic.
   • Make a POST request to /global-promotions-management/promotions/${promotionId}/rule-configuration to associate eligibility rules (for customers, products, channels, events), promotion templates, reward definitions (pricing and/or non-pricing), and rule sequencing and priorities.
   • Make a GET request to retrieve the configured rules for inspection or validation.

   Rule configuration determines which cart or customer attributes are evaluated, which conditions must be met, which reward actions are triggered, and how multiple rules are ordered or combined.

   Result: Rule configuration is attached to the promotion and becomes the authoritative logic used by eligibility and execution APIs.
4. Retrieve Promotion Configuration—Retrieve the engine-ready fully resolved view of the promotion.
   • Make a GET request to /global-promotions-management/promotions/${promotionId}/configuration.

   This response consolidates promotion metadata, eligibility definitions, rule parameters and conditions, reward configuration, limits and usage constraints, and associated rule library and version.

   Result: Developers can verify exactly how the promotion will behave at runtime, reducing configuration errors and debugging effort.

Phase 2: Discovery and Enrollment

These APIs are typically invoked from customer-facing experiences to surface promotions and manage explicit opt-in requirements.

1. Get Product Promotion Recommendations—Surface relevant promotions that are recommended for display, not yet applied, based on product and customer context.
   • Make a POST request to /promotions/recommendation/product-promotion with customer and channel context such as customer identifiers, channel, and personalization context.
   Result: A ranked list of recommended promotions is returned, including promotion details and coupon availability messages where applicable.
2. Enroll Member in Promotion—Enroll a customer when explicit enrollment is required.
   • Make a POST request to /global-promotions-management/promotion-enrollments with promotion and customer identifiers.
   Result: The customer is enrolled and becomes eligible for promotion evaluation and reward processing during transactions.

Phase 3: Transactional Execution

This phase executes promotion logic in real time during cart and checkout workflows. These APIs are commonly used by commerce applications and POS systems.

1. Evaluate Eligible Promotions—Evaluate cart and customer context without applying pricing changes.
   • Make a POST request to /global-promotions-management/eligible-promotions with cart, customer, and channel data.
   Result: A list of eligible promotions is returned, allowing applications to preview or select promotions prior to execution.
2. Execute Promotion—Apply promotion actions and calculate pricing adjustments during checkout.
   • Make a POST request to /global-promotions-management/promotion-execution with finalized cart details.

   The engine applies discount actions, resolves conflicts between promotions, honors promotion group evaluation methods, and produces detailed pricing adjustments. Promotions can be applied at line level, cross-line level, and order level depending on rule configuration.

   Result: The response contains the adjusted cart and line items with detailed breakdowns of applied promotions.
3. Issue Promotion Rewards—Persist promotion outcomes and issue pricing and non-pricing rewards.
   • Make a POST request to /global-promotions-management/promotion-reward with transaction journal inputs.
   Result: Promotion rewards are recorded in transaction journals, enabling auditability, reporting, and downstream processing.

Use Case: Segment-Based Promotion in E-Commerce

Offer customers in a Data Cloud segment (“High-Value Audio Shoppers”) 20% off selected Audio products and issue a non-pricing reward during checkout.

Phase 1: Setup (Admin)

Create the Promotion Definition

Call POST /global-promotions-management/promotions.

Request

1{
2  "promotionDetails": {
3    "name": "SummerTech20_2026",
4    "displayName": "Summer Tech 20",
5    "description": "20% off Audio for High-Value Audio Shoppers",
6    "startDateTime": "2026-06-01T00:00:00.000Z",
7    "endDateTime": "2026-08-31T23:59:59.000Z",
8    "priorityNumber": 10,
9    "isAutomatic": true,
10    "promotionCode": "SUMMER20",
11    "promotionEligibility": {
12      "eligibleSegments": [
13        {
14          "id": "SEG_HIGH_VALUE_AUDIO",
15          "name": "High-Value Audio Shoppers"
16        }
17      ],
18      "eligibleProductCategories": [
19        {
20          "id": "CAT_AUDIO",
21          "name": "Audio"
22        }
23      ]
24    }
25  }
26}

Result: A promotion definition is created and ready for rule configuration.

1{
2  "promotionDetails": {
3    "id": "0c8xx0000004WjzAAE",
4    "name": "SummerTech20_2026",
5    "displayName": "Summer Tech 20",
6    "priorityNumber": 10,
7    "startDateTime": "2026-06-01T00:00:00.000Z",
8    "endDateTime": "2026-08-31T23:59:59.000Z",
9    "isAutomatic": true,
10    "promotionCode": "SUMMER20",
11    "promotionEligibility": {
12      "eligibleSegments": [
13        { "id": "SEG_HIGH_VALUE_AUDIO", "name": "High-Value Audio Shoppers" }
14      ],
15      "eligibleProductCategories": [
16        { "id": "CAT_AUDIO", "name": "Audio" }
17      ]
18    }
19  },
20  "rules": [],
21  "promotionConfigurationWarnings": []
22}

Configure Promotion Rules

Call POST /global-promotions-management/promotions/0c8xx0000004WjzAAE/rule-configuration.

Request

1{
2  "rules": [
3    {
4      "templateName": "SimpleLineLevelRewards",
5      "ruleName": "Audio20PercentRule",
6      "priority": 1,
7      "eventConfiguration": [
8        {
9          "spendRange": {
10            "minimum": 1
11          }
12        }
13      ],
14      "rewardConfiguration": [
15        {
16          "type": "ProvideDiscount",
17          "rewardDetails": {
18            "discountValue": 20,
19            "discountType": "PercentageOff",
20            "discountLevel": "LineItem",
21            "discountedItems": [
22              {
23                "discountedItemType": "Product",
24                "discountedItemList": [
25                  {
26                    "id": "PROD_HEADPHONE_100"
27                  }
28                ]
29              }
30            ]
31          },
32          "targetAudience": {
33            "audienceType": "AllMembers"
34          },
35          "isPrimaryReward": true
36        },
37        {
38          "type": "IssueVoucher",
39          "rewardDetails": {
40            "voucherDefinition": {
41              "name": "SummerBonusVoucher"
42            }
43          },
44          "targetAudience": {
45            "audienceType": "AllMembers"
46          }
47        }
48      ]
49    }
50  ]
51}

Result: The promotion is fully configured and available for discovery and execution.

1{
2"promotionDetails": {
3"id": "0c8xx0000004WjzAAE",
4"name": "SummerTech20_2026"
5},
6"rules": [
7{
8"templateName": "SimpleLineLevelRewards",
9"ruleName": "Audio20PercentRule"
10}
11],
12"promotionConfigurationWarnings": []
13}

Phase 2: Discovery (Customer App)

Surface Promotions to the Customer

Alex (Contact ID: 003ALEX001) belongs to the “High-Value Audio Shoppers” Data Cloud segment.

Call POST /promotions/recommendation/product-promotion.

Request

1{
2"individualId": "003ALEX001",
3"dataspace": "default",
4"personalizationPoint": "PDP_AUDIO",
5"eligibleChannel": {
6"channel": {
7"name": "WebStore"
8}
9}
10}

Result: The API returns the Summer Tech 20 as a recommended promotion for display. This step shows product recommendations based on segment membership and does not apply pricing.

1{
2  "recommendationCount": 1,
3  "recommendationList": [
4    {
5      "promotionId": "0c8xx0000004WjzAAE",
6      "promotionName": "Summer Tech 20",
7      "rank": 1
8    }
9  ]
10}

Phase 3: Evaluation (Cart) and Fulfillment (Checkout)

Evaluate Promotion Eligibility

Alex adds the headphones to the shopping cart.

Call POST /global-promotions-management/eligible-promotions.

Request

1{
2  "cart": {
3    "cartId": "CART10001",
4    "currencyIsoCode": "USD",
5    "lineItems": [
6      {
7        "lineId": "LINE1",
8        "productId": "PROD_HEADPHONE_100",
9        "productCategoryId": "CAT_AUDIO",
10        "quantity": 1,
11        "unitPrice": 200
12      }
13    ]
14  },
15  "individualId": "003ALEX001",
16  "channel": {
17    "name": "WebStore"
18  }
19}

Result: The response returns Summer Tech 20 as eligible. A 20% discount applies to the audio line item, and an associated non-pricing reward is available.

1{
2  "eligiblePromotions": [
3    {
4      "promotionId": "0c8xx0000004WjzAAE",
5      "promotionName": "Summer Tech 20",
6      "rewardDetails": [
7        {
8          "rewardType": "ProvideDiscount",
9          "discountPercent": 20,
10          "discountAmount": 40
11        },
12        {
13          "rewardType": "IssueVoucher",
14          "voucherDefinitionName": "SummerBonusVoucher"
15        }
16      ]
17    }
18  ]
19}

Fulfillment (Checkout)

Execute Promotion Pricing

Call POST /global-promotions-management/promotion-execution.

Request

1{
2  "cart": {
3    "cartId": "CART10001",
4    "currencyIsoCode": "USD",
5    "lineItems": [
6      {
7        "lineId": "LINE1",
8        "productId": "PROD_HEADPHONE_100",
9        "quantity": 1,
10        "unitPrice": 200
11      }
12    ]
13  },
14  "individualId": "003ALEX001"
15}

Result: The API applies a 20% discount to eligible audio products and resolves conflicts if multiple promotions exist. It then calculates the final cart total and returns a detailed discount breakdown.

1{
2  "cartId": "CART10001",
3  "originalTotal": 200,
4  "discountTotal": 40,
5  "finalTotal": 160,
6  "appliedPromotions": [
7    {
8      "promotionId": "0c8xx0000004WjzAAE",
9      "discountApplied": 40
10    }
11  ]
12}

Issue Promotion Rewards

Call POST /global-promotions-management/promotion-reward.

Request

1{
2  "journalCreationMode": "CreateTransactionJournal",
3  "transactionJournalList": [
4    {
5      "externalTransactionNumber": "ORDER10001",
6      "promotionId": "0c8xx0000004WjzAAE",
7      "individualId": "003ALEX001",
8      "amount": 40
9    }
10  ]
11}

Result: The API creates transaction journals, records the 20% discount, and issues the configured voucher reward. Promotion usage is logged for audit and reporting purposes.

1{
2  "transactionJournalId": "TJ100987",
3  "discountsAppliedList": [
4    {
5      "promotionId": "0c8xx0000004WjzAAE",
6      "amount": 40
7    }
8  ],
9  "voucherIssuedList": [
10    {
11      "voucherCode": "SUMMER-847392",
12      "expirationDate": "2026-09-30"
13    }
14  ]
15}

Voucher characteristics such as value, expiration behavior, and redemption rules are typically defined by the voucher definition referenced in the promotion rule.

This workflow demonstrates how promotions are defined, discovered, evaluated, and executed using Global Promotions Management APIs. Developers can integrate these APIs into commerce platforms, marketing systems, and POS environments to deliver consistent promotion experiences across channels.