Promotion API handlers

5 min

HTTP Verb – POST

URL – /api/v1/carts//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//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//promotions/

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//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//promotions/

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.