--- title: Promotion API handlers slug: configured-commerce/docs/promotion-api-handlers docTags: createdAt: 2026-08-13T10:46:21.000Z --- ### POST Promotion (Add) **HTTP Verb** – POST **URL** – /api/v1/carts//promotions **Description** – Apply a promotion code to a cart **Base** – HandlerBase\ **Handlers** – | Order | Handler | Description | | ----- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 500 | `GetCart` | Retrieves the cart using the `CartId` parameter via the `CartService`. Returns error if the cart is not found. | | 600 | `ValidatePromotionCode` | Checks if the promotion code is already applied to the cart. Validates the promotion code against the promotion engine. Returns appropriate error messages for already-applied, expired, or invalid codes. | | 700 | `ApplyPromotion` | Creates an `OrderPromotionCode` entity and adds it to the cart. If `AllowMultiplePromotions` setting is false, removes existing promotion codes first. Calls the promotion engine to apply promotions and saves changes. | | 800 | `ValidateAppliedPromotion` | Verifies the promotion was successfully applied by checking `CustomerOrderPromotions`. If the promotion was not applied, removes the promotion code and returns an error with the specific reason (for example, customer limit exceeded or order total requirement not met). | | 900 | `CreatePromotionDto` | Creates a `PromotionDto` from the applied `CustomerOrderPromotion`. Formats the display message with translation support and adds a result message indicating the promotion was applied. Adds a warning if the promotion is not yet live. | ### GET Promotion Collection **HTTP Verb** – GET **URL** – /api/v1/carts//promotions **Description** – Get all promotions applied to a cart **Base** – HandlerBase\ **Handlers** – | Order | Handler | Description | | ----- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 500 | `GetCart` | Retrieves the cart using the `CartId` parameter via the `CartService`. Returns error if the cart is not found. | | 600 | `CreatePromotionDtos` | Creates a list of `PromotionDto` objects from the cart's `CustomerOrderPromotions` collection, using the currency format provider, promotion amount provider, and entity translation service. | ### GET Promotion **HTTP Verb** – GET **URL** – /api/v1/carts//promotions/ **Description** – Get a single promotion applied to a cart **Base** – HandlerBase\ **Handlers** – | Order | Handler | Description | | ----- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 500 | `GetCart` | Retrieves the cart using the `CartId` parameter via the `CartService`. Returns error if the cart is not found. | | 600 | `CreatePromotionDto` | Finds the `CustomerOrderPromotion` matching the specified `PromotionId`. Returns `NotFound` error if not found. Creates a `PromotionDto` from the matched promotion. | ### DELETE Promotion Collection (Remove All) **HTTP Verb** – DELETE **URL** – /api/v1/carts//promotions **Description** – Remove all promotions from a cart **Base** – HandlerBase\ **Handlers** – | Order | Handler | Description | | ----- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 500 | `GetCart` | Retrieves the cart for modification using the `CartId` parameter. Returns early (without error) if the cart is empty or voided. Returns error if the cart is not found. | | 600 | `RemovePromotions` | Deletes all `OrderPromotionCode` entities from the cart. Clears promotions via the promotion engine. Flags the cart for recalculation of promotions, shipping, and tax. Saves changes. | ### DELETE Promotion (Remove Single) **HTTP Verb** – DELETE **URL** – /api/v1/carts//promotions/ **Description** – Remove a specific promotion from a cart **Base** – HandlerBase\ **Handlers** – | Order | Handler | Description | | ----- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 500 | `GetCart` | Retrieves the cart for modification using the `CartId` parameter. Returns early (without error) if the cart is empty or voided. Returns error if the cart is not found. | | 600 | `GetPromotion` | Queries `CustomerOrderPromotion` entities matching the `CartId` and `PromotionId` parameter. Returns `NotFound` error if no matching promotions exist. | | 700 | `RemovePromotion` | For each matched `CustomerOrderPromotion`, removes the associated `OrderPromotionCode` (respecting case sensitivity settings), clears promotion results via the promotion result service, removes the `CustomerOrderPromotion` entity, and saves. | | 800 | `RecalculatePromotions` | Flags the cart for recalculation of promotions, shipping, and tax. Calls the promotion engine to reapply remaining promotions and saves changes. |