Skip to main content

Fetch a Subscription

Overview​

Fetch the details of a single Subscription by its unique ID. Use this endpoint to retrieve complete information about a customer's recurring billing subscription.

Resource Access​

  • User Permissions: Admin users only
  • Endpoint: GET /subscriptions/\{subscription_id}

Arguments​

ParameterTypeRequiredDescription
subscription_idstringYes (path)The unique ID of the Subscription

Example Request​

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

Example Response​

{
  "id": "SUBsubscription123",
  "created_at": "2023-12-10T17:00:00Z",
  "updated_at": "2023-12-10T17:00:00Z",
  "amount": 19900,
  "currency": "USD",
  "linked_to": "MUmerchant123",
  "linked_type": "MERCHANT",
  "billing_interval": "MONTHLY",
  "nickname": "Basic Plan - Customer Name",
  "first_charge_at": "2023-12-24T17:00:00Z",
  "next_billing_date": {
    "year": 2023,
    "month": 12,
    "day": 24
  },
  "subscription_phase": "TRIAL",
  "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": {
      "interval_type": "DAY",
      "interval_count": 14,
      "trial_start_at": "2023-12-10T17:00:00Z",
      "trial_end_at": "2023-12-24T17:00:00Z"
    },
    "discount_phase_details": null
  },
  "buyer_details": {
    "identity_id": "IDidentityBuyer456",
    "instrument_id": "PIcreditCard789",
    "requested_delivery_methods": [
      {
        "type": "EMAIL",
        "destinations": ["customer@example.com"]
      }
    ],
    "shipping_address": null
  },
  "tags": {
    "customer_tier": "premium",
    "signup_source": "website",
    "campaign_id": "summer2023"
  },
  "_links": {
    "self": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123"
    },
    "merchant": {
      "href": "https://api.ahrvo.network/payments/na/merchants/MUmerchant123"
    },
    "subscription_plan": {
      "href": "https://api.ahrvo.network/payments/na/subscription_plans/SPsubscriptionPlan001"
    },
    "buyer_identity": {
      "href": "https://api.ahrvo.network/payments/na/identities/IDidentityBuyer456"
    },
    "payment_instrument": {
      "href": "https://api.ahrvo.network/payments/na/payment_instruments/PIcreditCard789"
    },
    "balance_entries": {
      "href": "https://api.ahrvo.network/payments/na/subscriptions/SUBsubscription123/subscription_balance_entries"
    }
  }
}

Additional Information​

  • State: Current subscription status
    • ACTIVE: Billing normally
    • NOT_STARTED: Future-dated, hasn't begun
    • PAST_DUE: Payment failed, in retry
    • CANCELED: No future charges
    • EXPIRED: Fixed-term completed
  • Subscription Phase: Current billing phase
    • TRIAL: Free trial period (not charged)
    • DISCOUNT: Discounted pricing
    • EVERGREEN: Standard recurring billing
    • FIXED: Fixed-length subscription
    • NONE: No special phase
  • Next Billing Date: When next charge occurs
    • {year, month, day} format
    • First charge after trial ends (if trial)
    • Use for customer notifications
  • Trial Details: Free trial information
    • trial_start_at: Trial began
    • trial_end_at: When first charge occurs
    • Customer notcharged during trial
    • null if no trial
  • Discount Phase: Promotional pricing
    • Reduced price for X billing cycles
    • After trial (if both configured)
    • null if no discount
  • Total Billing Intervals: Fixed-length subscriptions
    • Number of billing cycles total
    • null = evergreen (indefinite)
    • Subscription expires after final payment
  • Expires At: End date for fixed subscriptions
    • null for evergreen subscriptions
    • When state changes to EXPIRED
  • Use Cases:
    • Customer Account Page: Display subscription details
    • Billing Support: Answer customer questions
    • Trial Reminder: Check trial_end_at, send reminder
    • Update Payment Method: Get current instrument_id
    • Cancel Flow: Show what customer is canceling
    • Upgrade/Downgrade: Get current plan to compare
  • Related Endpoints:
    • PUT /subscriptions/{id}: Update subscription
    • DELETE /subscriptions/{id}: Cancel subscription
    • GET /subscription_plans/{id}: View plan details
    • POST /subscriptions/{id}/subscription_balance_entries: Apply credit