List Subscription Plans

Overview

Retrieve a paginated list of Subscription Plans with filtering options. Use this endpoint to view all available plan templates, filter by merchant, status, or pricing.

Resource Access

User Permissions: Admin users only
Endpoint: GET /subscription_plans

Arguments

Parameter	Type	Required	Description
limit	integer	No	Maximum number of records to return (default: 10)
offset	integer	No	Number of records to skip for pagination
linked_to	string	No	Filter plans linked to specific Merchant ID
state	string	No	Filter by plan state (ACTIVE or INACTIVE)
amount.gte	integer	No	Filter plans with amount ≥ value (in cents)
amount.lte	integer	No	Filter plans with amount ≤ value (in cents)
billing_interval	string	No	Filter by frequency (DAILY, WEEKLY, MONTHLY, YEARLY)

Example Request

curl -X GET \
  'https://api.ahrvo.network/payments/na/subscription_plans?state=ACTIVE&billing_interval=MONTHLY&limit=20' \
  -u username:password \
  -H 'Content-Type: application/json'

Example Response

{
  "_embedded": {
    "subscription_plans": [
      {
        "id": "SPsubscriptionPlan001",
        "created_at": "2023-11-01T10:00:00Z",
        "updated_at": "2023-11-01T10: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": null,
        "tags": {
          "tier": "basic",
          "version": "v2"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan001"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
          }
        }
      },
      {
        "id": "SPsubscriptionPlan002",
        "created_at": "2023-11-01T10:15:00Z",
        "updated_at": "2023-11-01T10:15:00Z",
        "amount": 49900,
        "currency": "USD",
        "plan_name": "API Portal - Pro Plan",
        "description": "Professional API portal account with advanced features",
        "nickname": "Pro",
        "linked_to": "MUmerchant123",
        "linked_type": "MERCHANT",
        "billing_interval": "MONTHLY",
        "duration_type": "EVERGREEN",
        "state": "ACTIVE",
        "billing_defaults": {
          "collection_method": "BILL_AUTOMATICALLY",
          "send_invoice": false,
          "send_receipt": true
        },
        "trial_defaults": {
          "interval_type": "DAY",
          "interval_count": 30
        },
        "discount_phase_defaults": {
          "amount": 29900,
          "billing_interval_count": 2
        },
        "tags": {
          "tier": "pro",
          "version": "v2"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan002"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
          }
        }
      },
      {
        "id": "SPsubscriptionPlan003",
        "created_at": "2023-11-01T10:30:00Z",
        "updated_at": "2023-11-01T10:30:00Z",
        "amount": 999900,
        "currency": "USD",
        "plan_name": "API Portal - Enterprise Annual",
        "description": "Enterprise API portal account billed annually",
        "nickname": "Enterprise",
        "linked_to": "MUmerchant123",
        "linked_type": "MERCHANT",
        "billing_interval": "YEARLY",
        "duration_type": "EVERGREEN",
        "state": "ACTIVE",
        "billing_defaults": {
          "collection_method": "SEND_INVOICE",
          "send_invoice": true,
          "send_receipt": true
        },
        "trial_defaults": null,
        "discount_phase_defaults": null,
        "tags": {
          "tier": "enterprise",
          "version": "v2"
        },
        "_links": {
          "self": {
            "href": "https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan003"
          },
          "merchant": {
            "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
          }
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 3
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscription_plans?state=ACTIVE&billing_interval=MONTHLY&limit=20"
    }
  }
}

Additional Information

Subscription Plans: View all plan templates
- Active and inactive plans
- Different tiers and pricing levels
- Various billing frequencies
- Trial and discount configurations
State Filtering:
- ACTIVE: Plans available for new subscriptions
  - Displayed to customers
  - Can create new subscriptions
- INACTIVE: Archived/deprecated plans
  - Hidden from customers
  - Existing subscriptions continue
  - Cannot create new subscriptions
  - Good for legacy plan management
Amount Filtering: Find plans by price range
- amount.gte=10000: Plans $100+ per billing cycle
- amount.lte=50000: Plans $500 or less
- Combine both for range: $100-$500
- Amount in cents (10000 = $100.00)
Billing Interval Filtering: Group by frequency
- MONTHLY: Monthly subscription plans
- YEARLY: Annual plans
- WEEKLY: Weekly plans (less common)
- DAILY: Daily plans (rare, for specific use cases)
Linked To Filtering: View plans by merchant
- Filter by merchant ID
- See all plans for specific merchant
- Useful for multi-merchant platforms
Use Cases:
- Display Pricing Page:
  - List all ACTIVE plans
  - Filter by billing_interval (show monthly vs yearly)
  - Sort by amount (low to high)
  - Display to customers on pricing page
- Plan Management Dashboard:
  - List all plans (ACTIVE and INACTIVE)
  - View plan details, pricing, trials
  - Identify legacy plans to phase out
  - Monitor plan performance
- Multi-Merchant Platform:
  - Filter plans by linked_to (merchant ID)
  - Each merchant has their own plans
  - Platform operators view all merchants' plans
- Price Analysis:
  - Filter plans by amount range
  - Identify pricing gaps
  - Compare competitive pricing
  - Optimize pricing strategy
- Billing Frequency Analysis:
  - Compare monthly vs annual plans
  - Calculate annual discount percentages
  - Encourage annual upgrades
Plan Details in Response:
- amount: Base recurring price
- billing_interval: How often charged
- trial_defaults: Free trial configuration (if any)
- discount_phase_defaults: Introductory pricing (if any)
- billing_defaults: Auto-charge vs invoice
- tags: Custom metadata for filtering/organization
Pagination: Handle large plan catalogs
- Use limit and offset for pagination
- Default limit: 10 plans
- Increase for full catalogs
- Typical SaaS: 3-5 plans
- Large platforms: 10-50+ plans
Sorting (via query parameters):
- Sort by amount (ascending/descending)
- Sort by created_at (newest/oldest)
- Sort by plan_name (alphabetical)
Common Filtering Examples:
- Active Monthly Plans:
```
?state=ACTIVE&billing_interval=MONTHLY
```
- Plans Under $100/month:
```
?amount.lte=10000&billing_interval=MONTHLY
```
- Specific Merchant's Plans:
```
?linked_to=MUmerchant123
```
- Annual Plans with Trials:
```
?billing_interval=YEARLY&state=ACTIVE
```
  (Then filter client-side for trial_defaults != null)
- Enterprise Plans ($500+):
```
?amount.gte=50000
```
Plan Comparison Logic:
- List all ACTIVE plans
- Group by billing_interval
- Calculate annual equivalent:
  - Monthly: amount × 12
  - Yearly: amount
- Show annual savings: (monthly × 12) - yearly
- Example:
  - Monthly: $49/month = $588/year
  - Annual: $499/year
  - Savings: $89 (15% discount)
Trial Period Display:
- Check trial_defaults field
- If present: "X-day free trial"
- Convert to customer-friendly format:
  - {interval_count: 14, interval_type: "DAY"} → "14-day free trial"
  - {interval_count: 1, interval_type: "MONTH"} → "1-month free trial"
Discount Phase Display:
- Check discount_phase_defaults field
- If present: Show promotional pricing
- Example:
  - Regular: $199/month
  - Discount: $99/month for first 3 months
  - Format: "$99/month for 3 months, then $199/month"
Legacy Plan Management:
- Filter by state=INACTIVE
- View deprecated plans
- See which plans are no longer offered
- Existing subscribers still on these plans
- Cannot create new subscriptions
Related Endpoints:
- POST /subscription_plans: Create new plan
- GET /subscription_plans/{id}: Fetch plan details
- PUT /subscription_plans/{id}: Update plan
- GET /subscriptions: List subscriptions using plans
- POST /subscriptions: Create subscription from plan

Overview​

Resource Access​

Arguments​

Example Request​

Example Response​

Additional Information​

Overview

Resource Access

Arguments

Example Request

Example Response

Additional Information