Promotion API handlers

Manage promotions (promo codes) applied to shopping carts.

HTTP Verb – POST

URL – /api/v1/carts/{cartId}/promotions

Description – Apply a promotion code to a cart

Base – HandlerBase<AddPromotionParameter, AddPromotionResult>

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.

HTTP Verb – GET

URL – /api/v1/carts/{cartId}/promotions

Description – Get all promotions applied to a cart

Base – HandlerBase<GetPromotionCollectionParameter, GetPromotionCollectionResult>

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.

HTTP Verb – GET

URL – /api/v1/carts/{cartId}/promotions/{promotionId}

Description – Get a single promotion applied to a cart

Base – HandlerBase<GetPromotionParameter, GetPromotionResult>

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.

HTTP Verb – DELETE

URL – /api/v1/carts/{cartId}/promotions

Description – Remove all promotions from a cart

Base – HandlerBase<RemovePromotionCollectionParameter, RemovePromotionCollectionResult>

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.

HTTP Verb – DELETE

URL – /api/v1/carts/{cartId}/promotions/{promotionId}

Description – Remove a specific promotion from a cart

Base – HandlerBase<RemovePromotionParameter, RemovePromotionResult>

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.

Updated about 7 hours ago