Skip to main content

Create a Subscription Plan

Overview​

Create a Subscription Plan template for recurring payments. Subscription Plans are reusable templates that define billing frequency, amount, trial periods, and discount phases for subscription-based services.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: POST /subscription_plans

Arguments​

ParameterTypeRequiredDescription
amountintegerYesThe base recurring amount in cents
currencystringYesCurrency code (e.g., "USD")
plan_namestringYesName of the subscription plan
descriptionstringNoDetailed description of the plan
nicknamestringNoUser-friendly nickname for the plan
linked_tostringYesThe Merchant ID this plan is linked to
linked_typestringYesType of linkage (always "MERCHANT")
billing_intervalstringYesFrequency: DAILY, WEEKLY, MONTHLY, YEARLY
duration_typestringNoEVERGREEN (default) or FIXED_DURATION
billing_defaultsobjectYesBilling configuration (see below)
trial_defaultsobjectNoTrial period configuration (see below)
discount_phase_defaultsobjectNoDiscount phase configuration (see below)
tagsobjectNoCustom key-value metadata

Billing Defaults Object​

FieldTypeRequiredDescription
collection_methodstringYesBILL_AUTOMATICALLY or SEND_INVOICE
send_invoicebooleanNoWhether to send invoice notifications
send_receiptbooleanNoWhether to send receipt notifications

Trial Defaults Object​

FieldTypeRequiredDescription
interval_typestringYesDAY, MONTH, or YEAR
interval_countintegerYesNumber of intervals for the trial

Discount Phase Defaults Object​

FieldTypeRequiredDescription
amountintegerYesDiscounted amount in cents
billing_interval_countintegerYesNumber of billing cycles with discount

Example Request​

curl -X POST \
'https://api.ahrvo.network/payments/na/subscription_plans' \
-u username:password \
-H 'Content-Type: application/json' \
-H 'Finix-Version: 2022-02-01' \
-d '{
"amount": 19900,
"currency": "USD",
"plan_name": "API Portal - Basic Plan",
"description": "Basic API portal account with essential features",
"nickname": "Basic",
"linked_to": "MUmerchant123",
"linked_type": "MERCHANT",
"billing_interval": "MONTHLY",
"duration_type": "EVERGREEN",
"billing_defaults": {
"collection_method": "BILL_AUTOMATICALLY",
"send_invoice": true,
"send_receipt": true
},
"trial_defaults": {
"interval_type": "DAY",
"interval_count": 14
},
"discount_phase_defaults": {
"amount": 9900,
"billing_interval_count": 3
},
"tags": {
"tier": "basic",
"department": "sales"
}
}'

Example Response​

{
"id": "SPsubscriptionPlan123",
"created_at": "2023-12-10T15:00:00Z",
"updated_at": "2023-12-10T15:00:00Z",
"amount": 19900,
"currency": "USD",
"plan_name": "API Portal - Basic Plan",
"description": "Basic API portal account with essential features",
"nickname": "Basic",
"linked_to": "MUmerchant123",
"linked_type": "MERCHANT",
"billing_interval": "MONTHLY",
"duration_type": "EVERGREEN",
"state": "ACTIVE",
"billing_defaults": {
"collection_method": "BILL_AUTOMATICALLY",
"send_invoice": true,
"send_receipt": true
},
"trial_defaults": {
"interval_type": "DAY",
"interval_count": 14
},
"discount_phase_defaults": {
"amount": 9900,
"billing_interval_count": 3
},
"tags": {
"tier": "basic",
"department": "sales"
},
"_links": {
"self": {
"href": "https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan123"
},
"merchant": {
"href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
}
}
}

Additional Information​

  • Subscription Plans: Reusable templates for recurring billing
    • Create once, use for many customers
    • Define pricing, billing frequency, trials, discounts
    • Link to merchant account
    • Can be updated to affect future subscriptions
  • Amount: Base recurring charge in cents
    • Example: 19900 = $199.00/month
    • Charged every billing interval
    • Can be discounted during discount phase
  • Billing Interval: How often customers are charged
    • DAILY: Every day (rare, for daily services)
    • WEEKLY: Every 7 days
    • MONTHLY: Every month (most common)
    • YEARLY: Every year (annual plans)
  • Duration Type:
    • EVERGREEN (default): Continues indefinitely until canceled
    • FIXED_DURATION: Ends after specific number of billing cycles
      • Useful for limited-time offers or contracts
  • Collection Method:
    • BILL_AUTOMATICALLY: Auto-charge payment method on file
      • Most common for SaaS/subscriptions
      • Charges happen automatically
      • Reduces churn from forgotten renewals
    • SEND_INVOICE: Manual payment via invoice
      • Send invoice to customer
      • Customer pays manually
      • Good for B2B, large contracts
  • Trial Defaults: Free or reduced trial period
    • interval_type: DAY, MONTH, or YEAR
    • interval_count: Number of intervals
    • Examples:
      • 14 days: interval_type: "DAY", interval_count: 14
      • 1 month: interval_type: "MONTH", interval_count: 1
      • 30 days: interval_type: "DAY", interval_count: 30
    • Trial is free (no charge during trial period)
    • After trial, regular billing begins
  • Discount Phase Defaults: Introductory pricing
    • amount: Discounted price in cents
    • billing_interval_count: How many billing cycles
    • Example: First 3 months at $99, then $199
      • amount: 9900 (discounted price)
      • billing_interval_count: 3 (3 months)
    • After discount phase, regular amount charged
  • State: Plan activation status
    • ACTIVE (default): Available for new subscriptions
    • INACTIVE: Archived, cannot create new subscriptions
      • Existing subscriptions continue
      • Good for phasing out old plans
  • Linked To: Merchant who owns the plan
    • All subscriptions from this plan go to this merchant
    • Payments settle to merchant's account
  • Tags: Custom metadata for organization
    • Track plan tier, department, version, etc.
    • Searchable and filterable
    • Not visible to end customers

Use Cases​

SaaS Tiered Pricing​

{
"plan_name": "Pro Plan",
"amount": 49900,
"billing_interval": "MONTHLY",
"trial_defaults": {
"interval_type": "DAY",
"interval_count": 30
}
}
  • 30-day free trial
  • Then $499/month
  • Evergreen (renews indefinitely)

Annual Plan with Discount​

{
"plan_name": "Enterprise Annual",
"amount": 999900,
"billing_interval": "YEARLY",
"discount_phase_defaults": {
"amount": 799900,
"billing_interval_count": 1
}
}
  • First year: $7,999
  • Subsequent years: $9,999
  • 20% discount on first year

Monthly Membership​

{
"plan_name": "Gym Membership",
"amount": 5900,
"billing_interval": "MONTHLY",
"billing_defaults": {
"collection_method": "BILL_AUTOMATICALLY",
"send_receipt": true
}
}
  • $59/month gym membership
  • Auto-charge monthly
  • Send receipt after each payment

B2B Invoice-Based​

{
"plan_name": "Enterprise Support",
"amount": 500000,
"billing_interval": "MONTHLY",
"billing_defaults": {
"collection_method": "SEND_INVOICE",
"send_invoice": true
}
}
  • $5,000/month support plan
  • Invoice sent monthly
  • Customer pays via wire/ACH

Best Practices​

  • Naming Conventions: Use clear, descriptive names
    • Include tier level: "Basic", "Pro", "Enterprise"
    • Include billing frequency if multiple options: "Pro Monthly", "Pro Annual"
    • Include version for tracking: "Pro v2", "Pro 2024"
  • Trial Periods: Industry standards
    • SaaS: 14 or 30 days
    • Media/Content: 7 days
    • B2B: 30 days or custom
    • No trial for low-priced plans (under $10/month)
  • Discount Phases: Attract new customers
    • First month 50% off
    • First 3 months at reduced rate
    • Annual discount (vs monthly price)
    • Limited-time promotional pricing
  • Billing Intervals: Choose wisely
    • Monthly: Lower commitment, higher churn
    • Yearly: Higher commitment, better retention, offer discount
    • Quarterly: Good middle ground for B2B
  • Collection Methods:
    • BILL_AUTOMATICALLY: For B2C, small B2B (under $500/month)
    • SEND_INVOICE: For B2B, large contracts (over $5,000/month)
  • Tags for Organization:
    • tier: basic, pro, enterprise
    • version: v1, v2, 2024
    • department: sales, marketing, product
    • status: active, legacy, promotional
  • Versioning Plans: Instead of updating, create new
    • Grandfather existing customers on old plan
    • New customers get new plan
    • Allows side-by-side comparison
    • Better for compliance and auditing

Common Workflows​

Launch New SaaS Product​

  1. Create subscription plans for each tier
  2. Basic: $19/month, 14-day trial
  3. Pro: $49/month, 14-day trial
  4. Enterprise: Custom pricing (contact sales)
  5. Offer discount on annual plans (2 months free)

Promotional Campaign​

  1. Create temporary promotional plan
  2. First 3 months at 50% off
  3. Set discount_phase_defaults
  4. Tag with campaign ID
  5. After campaign, set to INACTIVE
  6. Existing subscribers continue at promo rate for 3 months

Migrate Legacy Plans​

  1. Create new improved plans
  2. Set old plans to INACTIVE
  3. Existing customers stay on old plans
  4. New customers only see new plans
  5. Optionally offer migration incentive
  • GET /subscription_plans: List all plans
  • GET /subscription_plans/{id}: Fetch plan details
  • PUT /subscription_plans/{id}: Update plan
  • POST /subscriptions: Create subscription from plan
  • GET /subscriptions: List subscriptions using plan