---
updatedAt: 2026-01-29T12:54:25.000Z
agentTools:
  projectIndex: https://developers.intandem.tech/llms.txt
---

# Subscription Coupons

How to set up and use coupons to discount the price of Plans, Apps, and Add-ons

This guide provides developers with a comprehensive overview of how to implement, manage, and apply coupons within the vcita billing ecosystem.

There are two primary ways to handle discounts:

1. **Recurly-Managed Coupons**: Validated and calculated by Recurly’s engine.
2. **External Coupons (Price Override)**: Managed by the Partner, where vcita only records the final price defined by the Partner.

***

# Developer Guide: Coupon Implementation for vcita

## 1. Prerequisites & Setup

### Token Requirements

* **Directory or Admin Token**: Required for any API request that uses the `price` override parameter.
* **Business Token**: Sufficient for applying standard `coupon_code` discounts that are already configured in Recurly.

### Recurly Configuration (For Recurly Coupons)

For coupons to work with apps and add-ons, they must be set up in Recurly as follows:

* **Subscription-Level**: Coupons must be set to the "Subscription-level" (not Account-level).
* **Add-on Support**: To discount SMS or other one-time add-ons, you must enable **"one-time charges discount"** in Recurly's global coupon settings.
* **Plan Eligibility**: Ensure the Recurly `PLAN CODE` matches the vcita `SKU`.

***

## 2. Applying Coupons via API

### Flow A: Recurly-Managed Coupons

Use this flow when the discount logic is defined in Recurly. vcita will call Recurly to calculate the final price.

**Endpoint:** `POST /v3/license/subscriptions`

```json
{
  "offering_uid": "offering_id_here",
  "purchase_currency": "USD",
  "coupon_code": "SAVE50"
}
```

### Flow B: External Coupons (Price Override)

Use this flow if you (the Partner) charge the user directly or manage the discount in your own system. This requires a **Directory/Admin token**.

**Important Requirements:**

* `payment_type` must be set to `external`.
* `price` must be provided.

```json
{
  "offering_uid": "offering_id_here",
  "purchase_currency": "USD",
  "price": 0.00,
  "payment_type": "external",
  "charged_by": "partner",
  "discount_code_name": "fixed_amount",
  "coupon_code": "PARTNER-COUPON-CODE"
}
```

***

## 3. Applying Coupons via URL Injection

URL injection is ideal for partner pricing pages that redirect users to the vcita checkout.

### Base URL Structure

`https://{domain}/checkout?offering_id={OFFERING_ID}&coupon_code={YOUR_CODE}`

### Advanced URL Parameters

| Parameter           | Description                                            |
| :------------------ | :----------------------------------------------------- |
| `coupon_code`       | The Recurly coupon code will be applied automatically. |
| `show_coupon_field` | Set to `true` to show the coupon input box in the UI.  |

### The "Free Plan" Experience

When a coupon results in a **$0.00 price** (100% discount):

* The checkout form automatically skips the "Credit Card" collection step.
* The user sees a "Purchase" or "Activate" button.
* Upon clicking, the subscription is created, and the user is redirected to the account/onboarding page.

***

## 4. Specific Product Handling

### Marketplace Apps

To apply a coupon to an app, you must use the app's specific `offering_uid`.

* **Note**: Ensure the app has a corresponding **Plan** in Recurly.

### SMS & Add-ons

* **One-time vs Recurring**: Apps/Plans are recurring subscriptions. SMS packages are one-time charges.
* **Recurly Eligibility**: Your Recurly coupon must be explicitly configured to be **"eligible for one-time charges"** for SMS discounts to apply correctly via the API.

***

## 5. Reporting & Webhooks

### Data Tracking

Vcita stores two prices for every subscription to ensure accurate revenue reporting:

* `original_price`: The standard MSRP of the offering.
* `purchase_price` (or `price`): The actual amount the user was charged after the coupon.

### UI Display

In the user's **My Account** page and during **Checkout**, vcita will automatically display the discount using the following format:

* ~~$20.00~~ **$10.00**
* ~~$20.00~~ **FREE** (for 100% discounts)

***

### Reference Documentation

* <Anchor label="API Reference: Subscriptions" target="_blank" href="https://developers.intandem.tech/reference/post_v3-license-subscriptions">API Reference: Subscriptions</Anchor>

<br />