> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cello.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Apply Discounts

> Learn how to apply discounts to referred users when the purchase a subscription

## Implementation steps

Implementing automated discounts for referred users follows a consistent pattern across all subscription platforms. Here's the complete workflow:

**1. Configure discounts in your subscription platform**

Create discount coupons in your subscription platform (Stripe, Chargebee, Paddle, Recurly, etc.):

**Platform Setup:**

* Configure discounts at the plan/price level
* Create multiple variations for different subscription plans:
  * Monthly plans: e.g., 25% off for 3 months
  * Annual plans: e.g., 50% off first year
* Store provider coupon IDs in application configuration. You will need them later to apply the correct coupon at subscription time based on plan/price and referral status.

> [!NOTE]
>
> Once you’ve set up discounts in your subscription platform, a potential next step would be to [display the discount information on your pricing or landing page](https://docs.cello.so/guides/user-experience/new-user-discounts.md).

**2. Subscription step: Check if new user is a Cello referral**

During subscription creation, check if the new user is a Cello referral and discount needs to be assigned:

* New ⭐: Use our [New User Reward API](https://docs.cello.so/api-reference/new-users/get-reward.md) to validate the eligibility for a new user reward (discount)

or

* **Using Stripe or Chargebee only:** Check your Stripe/Chargebee Customer if a `cello_ucc` is present in the [**Customer Object**](https://apidocs.chargebee.com/docs/api/customers)**.**
* **Using CelloAPI to track signups and Stripe/Chargebee to track purchases:** Check your Stripe/Chargebee customer if a `cello_ucc` is present in the [**Customer Object**](https://apidocs.chargebee.com/docs/api/customers)
* **Cello API to track all conversion events:** Check if the new user with this id has a `cello_ucc` in your profile you stored during [signup tracking](https://docs.cello.so/attribution/tracking-signups.md).

**3. Subscription step: Apply discount**

During subscription creation, pass the determined coupon code to your subscription platform:

**Required Data for Subscription:**

* Plan/Price information
* Coupon/discount code

**Platform-Specific Application:**

* **Stripe**: Use `discounts` array or `coupon` parameter on Checkout Session
* **Chargebee**: Apply `coupon_ids` on Subscription or via Hosted Pages (not at customer creation)

### Key Implementation Notes

* **Timing**: Discounts must be applied during initial subscription creation, not afterward
* **Validation**: Always verify the user is eligible for referral discounts
* **Fallback**: Handle cases where discount codes are invalid or expired
* **Configuration**: Maintain an application-level mapping of coupon IDs to plan type and referral status so the correct coupon can be applied at subscription time

## Stripe implementation

Stripe offers flexible discount mechanisms through **coupons**. For referral discounts, apply coupons during Subscription creation or Checkout. You cannot attach discounts at customer creation.

### Overview

There are two ways to apply coupons in Stripe, depending on your integration style:

* Server-side Subscription API (apply during `subscriptions.create`) - best for custom UIs. See [Stripe documentation](https://stripe.com/docs/billing/subscriptions/discounts).
* Prebuilt Checkout Session (apply during `checkout.sessions.create`) - best for hosted checkout. See [Stripe documentation](https://stripe.com/docs/payments/checkout/discounts).

Stripe's discount system works through:

* **Coupons**: Define the discount structure (percentage, duration, limits)
* **Application methods**: Apply coupons to Subscriptions or Checkout Sessions

**1. Create referral coupons in Stripe**

Set up discount coupons for your referral program:

**Via Stripe Dashboard:**

1. Go to [Stripe Dashboard > Coupons](https://dashboard.stripe.com/coupons)
2. Click "Create coupon"
3. Configure discount parameters:
   * **Name**: e.g., `Referral Discount - Monthly 25%`
   * **Type**: Percentage
   * **Percent off**: 25%
   * **Duration**: Repeating (3 months)
   * After creation, store the returned coupon ID in your config

**Via Stripe API:**

```javascript theme={null}
const stripe = require('stripe')('sk_live_...');

const coupon = await stripe.coupons.create({
  name: 'Referral Discount - Monthly 25%',
  percent_off: 25,
  duration: 'repeating',
  duration_in_months: 3,
  metadata: {
    campaign_type: 'user-referrals',
    plan_type: 'monthly'
  }
});
// Save coupon.id to your configuration
```

**2. Apply coupon during subscription creation**

```javascript theme={null}
const subscription = await stripe.subscriptions.create({
  customer: user.customerId,
  items: [{
    price: 'price_monthly_plan'
  }],
  discounts: [{
    coupon: couponId
  }]
});
```

### Handle checkout sessions with discounts

For Stripe Checkout, include discounts in session creation:

```javascript theme={null}
const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{
    price: 'price_monthly_plan',
    quantity: 1
  }],
  customer: user.customerId,
  discounts: [{
    coupon: couponId
  }],
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel'
});
```

The Stripe UI automatically displays the discount during checkout:

![Stripe checkout with discount visualization](https://uploads.developerhub.io/prod/d316/daczbjcm0yz4eegxj4jewsjgh5rxu5e301ene35zmtdx9ds9tcna8zv9g4e447i7.png)

### Manual discount application (not recommended)

For testing or special cases, you can manually attach coupons on a Subscription in the Stripe Dashboard:

1. Navigate to the subscription in [Stripe Dashboard](https://dashboard.stripe.com/subscriptions)
2. Click **Update subscription** → **Add coupon**
3. Select the appropriate referral coupon

![Stripe Console apply coupon action](https://uploads.developerhub.io/prod/d316/j4xfvr2jdxctb929xv4h4kqy5mf4hf5ecx6az5pjhc4tptm5qrnh2pm5bake2okl.png)

> [!WARNING]
>
> Manual application is not scalable for automated referral programs. Use the API methods above for production implementations.

## Chargebee implementation

Chargebee uses **coupons** to apply discounts on subscriptions. For referral discounts, apply coupons during subscription creation or via Hosted Pages.

### Overview

There are two ways to apply coupons in Chargebee:

* Subscription API (apply during `subscription.create`) - for server-side subscription creation. See [Chargebee documentation](https://apidocs.chargebee.com/docs/api/subscriptions?prod_cat_ver=2#create_a_subscription).
* Hosted Pages (apply via `coupon_ids` during checkout) - for provider-hosted checkout. See [Chargebee documentation](https://apidocs.chargebee.com/docs/api/hosted_pages?prod_cat_ver=2#checkout_new_subscription).

Chargebee's discount system works through:

* **Coupons**: Define discount rules (percentage, amount, duration)
* **Application methods**: Apply to subscriptions or via Hosted Pages

**1. Create referral coupons in Chargebee**

Set up discount coupons for your referral program:

**Via Chargebee Dashboard:**

1. Go to [Chargebee Dashboard > Coupons](https://www.chargebee.com/docs/2.0/coupons.html#creating-coupons)
2. Click "Create Coupon"
3. Configure discount parameters:
   * **Coupon Name**: e.g., `Referral Discount - Monthly 25%`
   * **Discount Type**: Percentage
   * **Discount**: 25%
   * **Duration Type**: Limited Period (3 months)
   * After creation, store the coupon ID in your config

**Via Chargebee API:**

```javascript theme={null}
const chargebee = require('chargebee');
chargebee.configure({
  site: 'your-site',
  api_key: 'your-api-key'
});

const coupon = await chargebee.coupon.create({
  id: 'YOUR_COUPON_ID',
  name: 'Referral Discount - Monthly 25%',
  discount_type: 'percentage',
  discount_percentage: 25,
  duration_type: 'limited_period',
  period: 3,
  period_unit: 'month'
});
```

**2. Apply coupons during subscription creation**

```javascript theme={null}
const subscription = await chargebee.subscription.create({
  customer_id: user.id,
  plan_id: 'monthly_plan',
  coupon_ids: [couponId]
});
```

### Handle Hosted Pages with discounts

For Chargebee Hosted Pages, include coupons in checkout URLs:

```javascript theme={null}
const hostedPage = await chargebee.hosted_page.checkout_new({
  subscription: {
    plan_id: 'monthly_plan',
    coupon_ids: [couponId]
  },
  customer: {
    id: user.id,
    email: user.email
  }
});

// Redirect user to hostedPage.url
```

## Cello API integration (for other platforms)

If you use another billing platform (for example, Paddle, Recurly, Braintree) or a home-grown system, follow the same general approach described above:

1. Create and manage coupons/discounts in your billing system.
2. Keep an application-level mapping of coupon IDs by plan and referral status.
3. Apply the correct coupon at subscription/checkout creation time.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.