Create Cart Rule

Creates a cart rule — the Create Rule action on the admin Marketing → Promotions → Cart Rules screen. A cart rule discounts the shopper's cart at checkout and can optionally be gated by a coupon code.

TIP

New here? Read the Cart Rules overview for what a cart rule does and how its fields behave.

Endpoint

Endpoint	Method
/api/admin/marketing/cart-rules	POST

Details

• Requires an admin Bearer token and the marketing.promotions.cart_rules.create permission.
• When coupon_type is 1 and use_auto_generation is 0, coupon_code is required and must be unique. With use_auto_generation set to 1, codes are generated for you.
• Returns the full rule payload, including the resolved conditions, channels, and customerGroups.

Request body

Field	Type	Required	Notes
name	string	yes	Rule name
description	string	no	Free-text description
channels	int[]	yes	Non-empty list of channel ids
customer_groups	int[]	yes	Non-empty list of customer-group ids
coupon_type	int	no	0 auto-apply when conditions match / 1 specific code
use_auto_generation	int	no	1 to auto-generate coupon codes
coupon_code	string	conditional	Required + unique when coupon_type is 1 and use_auto_generation is 0
action_type	string	yes	by_percent, by_fixed, cart_fixed, buy_x_get_y
discount_amount	number	yes	Discount value; capped at 100 when action_type is by_percent
discount_quantity	int	no	Quantity for buy_x_get_y
discount_step	string	no	Step for buy_x_get_y
apply_to_shipping	int	no	1 applies the discount to shipping
free_shipping	int	no	1 grants free shipping
condition_type	int	no	1 match all conditions / 0 match any
conditions	array	no	Cart / product filters
end_other_rules	int	no	1 stops lower-priority rules from also applying
uses_attribute_conditions	int	no	1 when conditions use product attributes
usage_per_customer	int	no	Per-customer usage cap (0 = unlimited)
uses_per_coupon	int	no	Per-coupon usage cap (0 = unlimited)
sort_order	int	no	Priority — lower runs first
status	int	no	0 inactive / 1 active
starts_from	string	no	Start date (YYYY-MM-DD) or null
ends_till	string	no	End date (YYYY-MM-DD) or null; must be >= starts_from