Fetch a Subscription Plan

Overview

Fetch the details of a single Subscription Plan by its unique ID. Use this endpoint to retrieve complete information about a specific plan template, including pricing, billing frequency, trial, and discount configurations.

Resource Access

User Permissions: Admin users only
Endpoint: GET /subscription_plans/\{subscription_plan_id}

Arguments

Parameter	Type	Required	Description
subscription_plan_id	string	Yes (path)	The unique ID of the Subscription Plan

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan001' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "id": "SPsubscriptionPlan001",
  "created_at": "2023-11-01T10:00:00Z",
  "updated_at": "2023-12-01T14:30:00Z",
  "amount": 19900,
  "currency": "USD",
  "plan_name": "API Portal - Basic Plan",
  "description": "Basic API portal account with essential features including 10,000 API calls per month, email support, and access to standard endpoints.",
  "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": null,
  "tags": {
    "tier": "basic",
    "version": "v2",
    "department": "sales",
    "api_calls": "10000"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan001"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
    },
    "subscriptions": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions?subscription_plan_id=SPsubscriptionPlan001"
    }
  }
}

Additional Information

Plan Details: Complete template configuration
- Pricing and billing frequency
- Trial period setup
- Discount phase configuration
- Billing and notification preferences
- Current state (active/inactive)
Amount: Base recurring price in cents
- Example: 19900 = $199.00
- Charged every billing_interval
- May be overridden during discount phase
- Currency always specified (typically USD)
Billing Interval: Charging frequency
- MONTHLY: Charged once per month
  - Most common for SaaS
  - Lower commitment
- YEARLY: Charged once per year
  - Better for retention
  - Often discounted vs monthly
- WEEKLY: Charged every 7 days
  - Useful for short-term services
- DAILY: Charged daily
  - Rare, for very specific use cases
Duration Type:
- EVERGREEN: Renews indefinitely
  - Standard for subscriptions
  - Continues until canceled
  - Most common
- FIXED_DURATION: Ends after set period
  - For limited-time offers
  - Contract-based services
  - Specified number of billing cycles
State: Plan availability
- ACTIVE: Available for new subscriptions
  - Visible to customers
  - Can create subscriptions
  - Default for new plans
- INACTIVE: Archived/deprecated
  - Not visible to customers
  - Cannot create new subscriptions
  - Existing subscriptions unaffected
  - Good for legacy plan management
Billing Defaults: Payment collection settings
- collection_method:
  - BILL_AUTOMATICALLY: Auto-charge on billing date
    - Credit card on file charged automatically
    - Reduces churn, improves cash flow
    - Standard for B2C, small B2B
  - SEND_INVOICE: Manual invoice payment
    - Invoice sent to customer
    - Customer pays via wire, ACH, check
    - Common for enterprise, large contracts
- send_invoice: Email invoice notification
  - true: Send invoice even if auto-charging
  - false: Skip invoice email
- send_receipt: Email receipt after payment
  - true: Send receipt confirmation
  - false: No receipt email
Trial Defaults: Free trial configuration
- interval_type: DAY, MONTH, or YEAR
- interval_count: Number of intervals
- null if no trial offered
- Examples:
  - 14-day trial: {interval_type: "DAY", interval_count: 14}
  - 1-month trial: {interval_type: "MONTH", interval_count: 1}
  - No trial: null
- Customer not charged during trial
- After trial, regular billing begins
Discount Phase Defaults: Introductory pricing
- amount: Discounted price in cents
- billing_interval_count: Number of billing cycles
- null if no discount phase
- Example:
  - First 3 months at $99:
    { "amount": 9900, "billing_interval_count": 3 }
  - After 3 months, regular amount ($199) charged
- Cannot combine with trial (discount starts after trial)
Linked To: Merchant owner
- Merchant ID who receives payments
- All subscriptions from this plan go to this merchant
- Cannot be changed after creation
Tags: Custom metadata
- Organize and categorize plans
- Track features, limits, versions
- Examples:
  - tier: basic, pro, enterprise
  - api_calls: monthly API limit
  - version: v1, v2 (for plan versioning)
  - department: sales, marketing
- Searchable and filterable
- Not visible to end customers
Use Cases:
- Display Plan Details to Customer:
  - Fetch plan before checkout
  - Show pricing, features, trial info
  - Display "14-day free trial" if trial_defaults present
  - Show discount: "$99 for 3 months, then $199/month"
- Subscription Creation Validation:
  - Check plan state (must be ACTIVE)
  - Verify plan exists and accessible
  - Retrieve pricing for payment processing
  - Get billing defaults for subscription config
- Plan Comparison:
  - Fetch multiple plans
  - Compare amounts, intervals, features
  - Show side-by-side comparison
  - Highlight differences
- Customer Support:
  - Customer asks about their plan
  - Fetch plan details
  - Explain pricing, billing frequency
  - Confirm trial or discount phase
- Reporting & Analytics:
  - Fetch plan to get pricing info
  - Calculate MRR (Monthly Recurring Revenue)
  - Track plan popularity
  - Analyze pricing effectiveness
Subscription Link: View active subscriptions
- _links.subscriptions: List subscriptions using this plan
- See how many customers on this plan
- Track plan adoption
- Identify popular plans
Updated At: Track plan changes
- Last modification timestamp
- Compare to created_at to see if updated
- Audit trail for plan changes
- Important for pricing history
Common Workflows:
- Customer Selects Plan:
  1. Display list of plans (GET /subscription_plans)
  2. Customer clicks "Select Basic Plan"
  3. Fetch plan details (GET /subscription_plans/{id})
  4. Verify plan is ACTIVE
  5. Display plan details and trial info
  6. Create subscription (POST /subscriptions)
- Plan Verification:
  1. Subscription references plan ID
  2. Fetch plan to verify still valid
  3. Check state is ACTIVE
  4. Confirm pricing hasn't changed
  5. Proceed with billing
- Feature Gate Check:
  1. User tries to access feature
  2. Look up user's subscription
  3. Fetch subscription plan
  4. Check tags for feature limits
  5. Allow or deny based on plan tier
Pricing Calculation Examples:
- Standard Monthly:
  - Amount: $199/month
  - No trial, no discount
  - Customer pays $199 every month
- With Trial:
  - Amount: $199/month
  - Trial: 14 days
  - Timeline:
    - Days 1-14: $0 (trial)
    - Day 15+: $199/month
- With Discount Phase:
  - Amount: $199/month (regular)
  - Discount: $99 for 3 months
  - Timeline:
    - Months 1-3: $99/month
    - Month 4+: $199/month
- With Trial + Discount:
  - Amount: $199/month (regular)
  - Trial: 14 days
  - Discount: $99 for 3 months
  - Timeline:
    - Days 1-14: $0 (trial)
    - Months 1-3: $99/month (discount)
    - Month 4+: $199/month (regular)
Best Practices:
- Cache plan details to reduce API calls
- Verify plan state before creating subscriptions
- Display trial and discount info prominently
- Use tags to store plan features/limits
- Check updated_at to detect price changes
- Follow subscriptions link to track adoption
Related Endpoints:
- GET /subscription_plans: List all plans
- PUT /subscription_plans/{id}: Update plan
- POST /subscriptions: Create subscription from plan
- GET /subscriptions?subscription_plan_id={id}: List subscriptions on this plan

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​