Global Promotions Management: End-to-End Workflow

Define, discover, evaluate, and execute promotions in real time by using Global Promotions Management APIs. This workflow shows how to configure promotions, surface them to customers, and apply pricing and reward outcomes during checkout.

The promotion lifecycle has three 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.

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: The API creates or retrieves a promotion definition. 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 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: The API attaches rule configuration 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 how the promotion behaves at runtime, which reduces configuration errors and debugging effort.

Customer-facing experiences use these APIs 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: The API returns a ranked list of recommended promotions, 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.

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: The response returns a list of eligible promotions so apps can preview or choose promotions before 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. The engine applies promotions at line, cross-line, or 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: The API records promotion rewards in transaction journals so downstream systems can track, report, and audit outcomes.

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

Result: The API creates a promotion definition that is ready for rule configuration.

Configure Promotion Rules

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

Request

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

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

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.

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

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.

Fulfillment (Checkout)

Execute Promotion Pricing

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

Request

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.

Issue Promotion Rewards

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

Request

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.

The voucher definition referenced in the promotion rule defines voucher characteristics such as value, expiration behavior, and redemption rules.

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.