Guides
Start typing to search…

Discounted Subscriptions

This guide demonstrates how to create discounted and free subscriptions using coupons.

Overview

The coupon system allows partners to:

  • Create subscriptions with discounted pricing
  • Create free subscriptions (100% discount)
  • Track both original and discounted prices for reporting
  • Integrate with Recurly for billing management

Prerequisites

  • Directory or Admin Token: The price parameter override is restricted to directory/admin tokens only
  • Valid Offering UID: You must have a validoffering_uid from the offerings API
  • External Payment Type: When using price override, payment_type must be set to 'external'

API Endpoint

POST /v3/license/subscriptions

Key Parameters

ParameterTypeRequiredDescription
offering_uidstringYesThe directory offering unique identifier
purchase_currencystringYesCurrency code (USD, EUR, or GBP)
pricenumberNoOverride the standard offering price (restricted to directory/admin tokens)
discount_code_namestringNoCoupon/discount type identifier (e.g., 'percent', 'fixed_amount')
coupon_codestringNoDiscount identifier for Recurly integration
payment_typestringNoMust be 'external' when price override is used
charged_bystringNoWho charges for the subscription ('partner' or 'platform')

Example 1: Creating a Free Subscription (100% Discount)

This example creates an entirely free subscription where the customer pays $0.

curl -X POST https://api.vcita.biz/v3/license/subscriptions \
  -H "Authorization: Bearer YOUR_DIRECTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
    "purchase_currency": "USD",
    "charged_by": "partner",
    "payment_type": "external",
    "price": 0.00,
    "discount_code_name": "fixed_amount",
    "coupon_code": "FREE-PLAN-EXAMPLE"
  }'

Response:

{
  "success": true,
  "data": {
    "uid": "c33f32c-95ae-4e8f-9f65-18bba589cb43",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T09:00:00Z",
    "display_name": "Premium 10",
    "is_active": true,
    "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
    "offering_type": "package",
    "purchase_state": "purchased",
    "business_uid": "biz_67890",
    "original_price": 99.99,
    "purchase_price": 0.00,
    "purchase_currency": "USD",
    "payment_type": "external",
    "charged_by": "partner",
    "discount_code_name": "fixed_amount",
    "coupon_code": "FREE-PLAN-EXAMPLE",
    "sku": "premium_10"
  }
}

Key Points:

  • price: 0.00 creates a free subscription
  • original_price shows the standard offering price ($99.99)
  • purchase_price shows the actual charged amount ($0.00)
  • Checkout is automatically skipped for free subscriptions
  • The subscription is immediately active (purchase_state: "purchased")

Example 2: Creating a Discounted Subscription (50% Off)

This example creates a subscription with a 50% discount.

curl -X POST https://api.vcita.biz/v3/license/subscriptions \
  -H "Authorization: Bearer YOUR_DIRECTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
    "purchase_currency": "USD",
    "charged_by": "partner",
    "payment_type": "external",
    "price": 49.99,
    "discount_code_name": "percent",
    "coupon_code": "SAVE50"
  }'

Response:

{
  "success": true,
  "data": {
    "uid": "c33f32c-95ae-4e8f-9f65-18bba589cb43",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T09:00:00Z",
    "display_name": "Premium 10",
    "is_active": true,
    "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
    "offering_type": "package",
    "purchase_state": "purchased",
    "business_uid": "biz_67890",
    "original_price": 99.99,
    "purchase_price": 49.99,
    "purchase_currency": "USD",
    "payment_type": "external",
    "charged_by": "partner",
    "discount_code_name": "percent",
    "coupon_code": "SAVE50",
    "sku": "premium_10"
  }
}

Key Points:

  • price: 49.99 sets the discounted price (50% off from $99.99)
  • discount_code_name: "percent" indicates this is a percentage-based discount
  • Both original_price and purchase_price are stored for reporting

Example 3: Fixed Amount Discount

This example creates a subscription with a fixed-dollar discount.

curl -X POST https://api.vcita.biz/v3/license/subscriptions \
  -H "Authorization: Bearer YOUR_DIRECTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
    "purchase_currency": "USD",
    "charged_by": "partner",
    "payment_type": "external",
    "price": 79.99,
    "discount_code_name": "fixed_amount",
    "coupon_code": "SAVE20"
  }'

Response:

{
  "success": true,
  "data": {
    "uid": "c33f32c-95ae-4e8f-9f65-18bba589cb43",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T09:00:00Z",
    "display_name": "Premium 10",
    "is_active": true,
    "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
    "offering_type": "package",
    "purchase_state": "purchased",
    "business_uid": "biz_67890",
    "original_price": 99.99,
    "purchase_price": 79.99,
    "purchase_currency": "USD",
    "payment_type": "external",
    "charged_by": "partner",
    "discount_code_name": "fixed_amount",
    "coupon_code": "SAVE20",
    "sku": "premium_10"
  }
}

Key Points:

  • price: 79.99 sets the discounted price ($20 off from $99.99)
  • discount_code_name: "fixed_amount" indicates this is a fixed dollar discount
  • The discount amount ($20) is calculated as original_price - purchase_price

Example 4: Creating Subscription Without Coupon (Standard Flow)

This example shows the standard subscription creation without any discounts.

curl -X POST https://api.vcita.biz/v3/license/subscriptions \
  -H "Authorization: Bearer YOUR_DIRECTORY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
    "purchase_currency": "USD",
    "charged_by": "platform"
  }'

Response:

{
  "success": true,
  "data": {
    "uid": "c33f32c-95ae-4e8f-9f65-18bba589cb43",
    "created_at": "2024-01-01T09:00:00Z",
    "updated_at": "2024-01-01T09:00:00Z",
    "display_name": "Premium 10",
    "is_active": true,
    "offering_uid": "bc33f12d-98ee-428f-9f65-18bba589cb95",
    "offering_type": "package",
    "purchase_state": "purchased",
    "business_uid": "biz_67890",
    "original_price": 99.99,
    "purchase_price": 99.99,
    "purchase_currency": "USD",
    "payment_type": "monthly",
    "charged_by": "platform",
    "sku": "premium_10"
  }
}

Key Points:

  • When no price is provided, the standard offering price is used
  • original_price and purchase_price will be the same
  • discount_code_name and coupon_code will be null

Important Notes

Security & Permissions

  • Token Requirement: The price parameter override requires a Directory or Admin token. Regular staff tokens cannot override prices.
  • Payment Type: When using price override, payment_type must be set to 'external'
  • Validation: The system validates that price overrides are only used with appropriate tokens

Price Tracking

  • Original Price: Always stored from the offering, even when discounted
  • Purchase Price: The actual amount charged (may differ from the original when discounted)
  • Reporting: Both prices are available for accurate revenue reporting and partner analytics

Free Subscriptions

  • Checkout Skipped: When price: 0.00, checkout is automatically skipped
  • Immediate Activation: Free subscriptions are immediately active (purchase_state: "purchased")
  • User Experience: Users are redirected directly to their account page

Coupon Codes

  • Recurly Integration: The coupon_code is passed to Recurly for billing management
  • Tracking: Both coupon_code and discount_code_name are stored for reporting
  • Reporting: You can filter reports by coupon code and partner

Error Handling

Invalid Token

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Price override is restricted to directory/admin tokens only"
  }
}

Invalid Payment Type

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "payment_type must be 'external' when price override is used"
  }
}

Invalid Offering

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Offering not found"
  }
}

Related Documentation

Support

For questions or issues related to coupon functionality, don't hesitate to contact the vcita support team or refer to the HLR document linked above.

Updated about 14 hours ago