Skip to main content

List Subscriptions

Overview​

Retrieve a paginated list of Subscription resources with filtering by status, merchant, and buyer. Use this endpoint to view all recurring billing subscriptions across your platform.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: GET /subscriptions

Arguments​

ParameterTypeRequiredDescription
limitintegerNoMaximum number of records to return (default: 10)
offsetintegerNoNumber of records to skip for pagination
linked_tostringNoFilter by Merchant ID
statestringNoFilter by state (ACTIVE, CANCELED, EXPIRED, NOT_STARTED, PAST_DUE)
buyer_identity_idstringNoFilter by Buyer Identity ID
subscription_plan_idstringNoFilter by Subscription Plan ID

Example Request​

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

Example Response​

{
  "_embedded": {
    "subscriptions": [
      {
        "id": "SUBsubscription001",
        "created_at": "2023-11-01T10:00:00Z",
        "updated_at": "2023-12-01T14:00:00Z",
        "amount": 19900,
        "currency": "USD",
        "linked_to": "MUmerchant123",
        "linked_type": "MERCHANT",
        "billing_interval": "MONTHLY",
        "nickname": "Basic Plan - John Doe",
        "first_charge_at": "2023-11-15T10:00:00Z",
        "next_billing_date": {
          "year": 2024,
          "month": 1,
          "day": 15
        },
        "subscription_phase": "EVERGREEN",
        "state": "ACTIVE",
        "subscription_plan_id": "SPsubscriptionPlan001",
        "start_subscription_at": null,
        "total_billing_intervals": null,
        "expires_at": null,
        "subscription_details": {
          "collection_method": "BILL_AUTOMATICALLY",
          "send_invoice": true,
          "send_receipt": true,
          "trial_details": null,
          "discount_phase_details": null
        },
        "buyer_details": {
          "identity_id": "IDidentityBuyer123",
          "instrument_id": "PIcreditCard456",
          "requested_delivery_methods": [
            {"type": "EMAIL", "destinations": ["john@example.com"]}
          ]
        },
        "tags": {
          "customer_tier": "basic",
          "ltv": "high"
        },
        "_links": {
          "self": {"href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription001"}
        }
      },
      {
        "id": "SUBsubscription002",
        "created_at": "2023-12-05T09:00:00Z",
        "updated_at": "2023-12-05T09:00:00Z",
        "amount": 49900,
        "currency": "USD",
        "linked_to": "MUmerchant123",
        "linked_type": "MERCHANT",
        "billing_interval": "MONTHLY",
        "nickname": null,
        "first_charge_at": "2023-12-19T09:00:00Z",
        "next_billing_date": {
          "year": 2023,
          "month": 12,
          "day": 19
        },
        "subscription_phase": "TRIAL",
        "state": "ACTIVE",
        "subscription_plan_id": "SPsubscriptionPlan002",
        "start_subscription_at": null,
        "total_billing_intervals": null,
        "expires_at": null,
        "subscription_details": {
          "collection_method": "BILL_AUTOMATICALLY",
          "send_invoice": false,
          "send_receipt": true,
          "trial_details": {
            "interval_type": "DAY",
            "interval_count": 14,
            "trial_start_at": "2023-12-05T09:00:00Z",
            "trial_end_at": "2023-12-19T09:00:00Z"
          },
          "discount_phase_details": null
        },
        "buyer_details": {
          "identity_id": "IDidentityBuyer789",
          "instrument_id": "PIcreditCard012"
        },
        "tags": {
          "signup_source": "landing_page_A"
        },
        "_links": {
          "self": {"href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription002"}
        }
      }
    ]
  },
  "page": {
    "offset": 0,
    "limit": 20,
    "count": 2
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions?state=ACTIVE&limit=20"
    }
  }
}

Additional Information​

  • State Filtering: View subscriptions by status
    • ACTIVE: Currently active, billing normally
    • CANCELED: Canceled by customer or admin
    • EXPIRED: Fixed-term subscriptions that completed
    • NOT_STARTED: Future-dated, hasn't started yet
    • PAST_DUE: Payment failed, in retry/grace period
  • Subscription Phases:
    • TRIAL: In free trial (not charged yet)
    • DISCOUNT: In discounted pricing period
    • EVERGREEN: Regular recurring billing
    • FIXED: Fixed-term subscription
    • NONE: No special phase
  • Use Cases:
    • Customer Dashboard: Show all customer's subscriptions
      • Filter by buyer_identity_id
      • Display active and canceled
      • Show next billing date
    • Merchant Dashboard: View all subscriptions for merchant
      • Filter by linked_to (merchant ID)
      • Track MRR (Monthly Recurring Revenue)
      • Monitor churn rate
    • Revenue Reporting: Calculate recurring revenue
      • Sum amounts for ACTIVE subscriptions
      • Group by billing_interval
      • Track by subscription_phase
    • Dunning Management: Handle failed payments
      • Filter by state=PAST_DUE
      • Retry failed charges
      • Send payment reminder emails
    • Trial Conversion: Monitor trial-to-paid
      • Filter by subscription_phase=TRIAL
      • Track trial end dates
      • Send trial ending reminders
    • Plan Analysis: See adoption by plan
      • Filter by subscription_plan_id
      • Compare plan popularity
      • Identify most profitable plans
  • Next Billing Date: When next charge occurs
    • Formatted as {year, month, day}
    • Use for reminder emails
    • Shows upcoming revenue
  • Collection Methods:
    • BILL_AUTOMATICALLY: Auto-charge subscriptions
    • SEND_INVOICE: Manual invoice payment
  • Pagination: Handle large subscription lists
    • Default limit: 10
    • Increase for bulk operations
    • Use offset for pages
  • Common Filtering Patterns:
    • Active paid subscriptions: 
      ?state=ACTIVE&subscription_phase=EVERGREEN
    • Trials ending soon: Filter TRIAL phase, check trial_end_at
    • Failed payments: 
      ?state=PAST_DUE
    • Specific customer's subscriptions: 
      ?buyer_identity_id=IDcustomer123
    • Merchant's revenue: 
      ?linked_to=MUmerchant456&state=ACTIVE
  • MRR Calculation (Monthly Recurring Revenue):
    • Filter: state=ACTIVE
    • For each subscription:
      • If MONTHLY: Add amount
      • If YEARLY: Add amount / 12
    • Sum all normalized amounts
    • Example:
      • Sub 1: $199/month = $199 MRR
      • Sub 2: $999/year = $83.25 MRR
      • Total MRR: $282.25
  • Churn Tracking:
    • Active subscriptions: state=ACTIVE
    • Canceled this month: state=CANCELED + filter by updated_at
    • Churn rate = Canceled / (Active + Canceled)
  • Related Endpoints:
    • POST /subscriptions: Create subscription
    • GET /subscriptions/{id}: Fetch details
    • PUT /subscriptions/{id}: Update subscription
    • DELETE /subscriptions/{id}: Cancel subscription