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 1 month ago