About Promotion Engine API

The Promotion Engine API provides programmatic access to the functionalities of the Promotion Engine.

It is designed to calculate eligible promotions based on cart content, retrieve full promotion configurations, and finalize discount applications during the checkout process. This API enables the integration of dynamic, rule-based promotional logic into cart and order flows.

⚠️This API operates independently from the Loyalty Engine and its APIs and does not handle customer profiles or event tracking.

Key Features

• Retrieve promotions
  Query configured promotions in the UI, with full metadata and rule definitions. Useful for displaying offers or syncing promotion setups across systems.

  Use the GET /promotions or GET /promotions/{promotionId} endpoint.

• Update promotion status
  Modify the lifecycle status of a promotion (e.g., from draft to active or archived). Promotes better control over when promotions are available to customers.

  Use the POST /promotions/{promotionId}/status endpoint.

• Cart evaluation
  Submit a cart to calculate which promotions apply, how much discount is granted, and preview tax and pricing adjustments. Temporarily reserves promotions with application limits.

  Use the POST /cart endpoint.

• Checkout finalization
  Finalizes promotion usage for a submitted cart, consuming limits where applicable, and returning final adjusted totals.

  Use the POST /cart/finalize endpoint.

API Principles

The Promotion Engine API follows RESTful principles and uses standard HTTP methods. All requests and responses use JSON format. Each endpoint is stateless and scoped to a particular resource, such as a promotion or cart.

The system does not track customer identity or behavior. All logic is based purely on the contents and structure of the submitted cart and promotion configurations.

Security and Compliance

All server-to-server calls must comply with the API authentication requirements and adhere to the defined API rate limits.

The Async Events API uses Bearer token authentication, with access tokens issued by the /v1/auth/token endpoint of the Authentication API.