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

Parameter	Type	Required	Description
amount	integer	Yes	The base recurring amount in cents
currency	string	Yes	Currency code (e.g., "USD")
plan_name	string	Yes	Name of the subscription plan
description	string	No	Detailed description of the plan
nickname	string	No	User-friendly nickname for the plan
linked_to	string	Yes	The Merchant ID this plan is linked to
linked_type	string	Yes	Type of linkage (always "MERCHANT")
billing_interval	string	Yes	Frequency: DAILY, WEEKLY, MONTHLY, YEARLY
duration_type	string	No	EVERGREEN (default) or FIXED_DURATION
billing_defaults	object	Yes	Billing configuration (see below)
trial_defaults	object	No	Trial period configuration (see below)
discount_phase_defaults	object	No	Discount phase configuration (see below)
tags	object	No	Custom key-value metadata

Billing Defaults Object

Field	Type	Required	Description
collection_method	string	Yes	BILL_AUTOMATICALLY or SEND_INVOICE
send_invoice	boolean	No	Whether to send invoice notifications
send_receipt	boolean	No	Whether to send receipt notifications

Trial Defaults Object

Field	Type	Required	Description
interval_type	string	Yes	DAY, MONTH, or YEAR
interval_count	integer	Yes	Number of intervals for the trial

Discount Phase Defaults Object

Field	Type	Required	Description
amount	integer	Yes	Discounted amount in cents
billing_interval_count	integer	Yes	Number 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

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

Promotional Campaign

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

Migrate Legacy Plans

Create new improved plans
Set old plans to INACTIVE
Existing customers stay on old plans
New customers only see new plans
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

Overview​

Resource Access​

Arguments​

Billing Defaults Object​

Trial Defaults Object​

Discount Phase Defaults Object​

Example Request​

Example Response​

Additional Information​

Use Cases​

SaaS Tiered Pricing​

Annual Plan with Discount​

Monthly Membership​

B2B Invoice-Based​

Best Practices​

Common Workflows​

Launch New SaaS Product​

Promotional Campaign​

Migrate Legacy Plans​

Related Endpoints​