Coupons

Coupons are tightly integrated with Sylius Cart Promotions, allowing promotions to be activated by unique codes. Here’s how to create, apply, and generate coupons for promotions.

Coupon Parameters

Each coupon has the following attributes:

• Code: The unique identifier for the coupon.

• Expiration Date: The date when the coupon expires.

• Usage Limit: The maximum number of times it can be used.

• Usage Count: Tracks how many times the coupon has been used.

Creating a Coupon-Based Promotion

To create a coupon-based promotion, follow these steps:

1. Create a Promotion

   Begin by creating a new promotion and setting it as coupon-based. Only coupon-based promotions can hold multiple coupons.

   /** @var PromotionInterface $promotion */
   $promotion = $this->container->get('sylius.factory.promotion')->createNew();
   
   $promotion->setCode('free_shipping');
   $promotion->setName('Free Shipping');
   
   // Set the promotion's channel
   $promotion->addChannel($this->container->get('sylius.repository.channel')->findOneBy(['code' => 'US_Web_Store']));
   
   $promotion->setCouponBased(true);

2. Create a Coupon and Link It to the Promotion

   Next, create a coupon and associate it with your promotion:

   /** @var CouponInterface $coupon */
   $coupon = $this->container->get('sylius.factory.promotion_coupon')->createNew();
   
   $coupon->setCode('FREESHIPPING');
   
   $promotion->addCoupon($coupon);

3. Add a Promotion Action

   Define what action the promotion should take when applied. For a free shipping promotion, create a 100% shipping discount action:

   /** @var PromotionActionFactoryInterface $actionFactory */
   $actionFactory = $this->container->get('sylius.factory.promotion_action');
   
   // Use a float for percentage discounts (1 = 100%, 0.1 = 10%)
   $action = $actionFactory->createShippingPercentageDiscount(1);
   
   $promotion->addAction($action);
   
   // Save the promotion to the repository
   $this->container->get('sylius.repository.promotion')->add($promotion);

Applying a Coupon to an Order

To apply a promotion coupon we've just created to an order:

1. Ensure the order has shipments (as the above coupon applies a promotion on shipping).

2. Set the promotion coupon on the order (this simulates a customer applying the coupon code at checkout).

3. Process the order with the OrderProcessor to apply the promotion.

$order->setPromotionCoupon($coupon);
$this->container->get('sylius.order_processing.order_processor')->process($order);

Generating Multiple Coupons

For larger promotions, manually creating codes is tedious. Sylius offers the CouponGenerator service to automatically generate coupon codes in bulk.

1. Retrieve the Promotion

   First, find the promotion to which you want to add coupons.

   $promotion = $this->container->get('sylius.repository.promotion')->findOneBy(['code' => 'simple_promotion']);

2. Configure the Coupon Generator

   Use PromotionCouponGeneratorInstruction to specify the number of coupons, code length, expiration date, and usage limit.

   /** @var CouponGeneratorInterface $generator */
   $generator = $this->container->get('sylius.promotion_coupon_generator');
   
   /** @var PromotionCouponGeneratorInstructionInterface $instruction */
   $instruction = new PromotionCouponGeneratorInstruction();
   
   $instruction->setAmount(10); // Generate 10 coupons
   $instruction->setPrefix('NEW_YEAR_'); // Optional prefix
   $instruction->setSuffix('_SALE'); // Optional suffix
   
   $generator->generate($promotion, $instruction);

   This example generates 10 coupons with the prefix NEW_YEAR_ and suffix _SALE for the simple_promotion promotion.