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

{
  "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.

{
  "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

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

• API Reference: Subscriptions