# Retrieve a subscription by ID

Retrieves the details of a specific subscription by its unique identifier.

Endpoint: GET /subscriptions/{id}
Version: 1.0.0
Security: JWT

## Path parameters:

  - `id` (string, required)
    Unique identifier of the subscription

## Response 200 fields (application/json):

  - `id` (string, required)
    Unique identifier for the subscription.
    Example: sub_5JU9yv0lGSUP

  - `customer_id` (string, required)
    Unique identifier of the customer associated with this subscription.
    Example: cust_5JU9yv0lGSUP

  - `product_name` (string, required)
    Name of the product being subscribed to.
    Example: ShieldGuard Insurance

  - `product_description` (string, required)
    Description of the product.
    Example: Flexible, monthly insurance for belongings, travel, and digital assets, easy to manage

  - `plan_name` (string)
    Name of the subscription plan.
    Example: ShieldGuard Lite

  - `plan_description` (string)
    Description of the subscription plan.
    Example: Simple, monthly insurance plan that covers your basic belongings and key digital assets

  - `reference_number` (string)
    optional identifier to be sent for reconciliations
    Example: R0001

  - `status` (string, required)
    Current status of the subscription.
    Enum: "created", "active", "paused", "expired", "failed", "halted", "cancelled", "completed", "authorized"

  - `amount` (number, required)
    The amount in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in  this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, pass the value as 295.
    Example: 1000

  - `currency` (string, required)
    The currency code in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format.
    Example: USD

  - `interval_type` (string, required)
    Used in combination with interval_count to define the billing cycle frequency.
    Enum: "month", "year", "as_presented"

  - `interval_count` (integer | null)
    Number of intervals between a billing cycle, used in combination with interval_type.
Valid combinations:
- Monthly: interval_type='month', interval_count=1
- Quarterly: interval_type='month', interval_count=3
- Half-yearly: interval_type='month', interval_count=6
- Yearly: interval_type='year', interval_count=1
- As Presented: interval_type='as_presented', interval_count=null
    Enum: 1, 3, 6, null

  - `billing_cycles` (integer | null)
    Total number of billing cycles for the subscription. Null for 'as_presented' subscriptions.
    Example: 12

  - `max_amount` (integer | null)
    Maximum allowed amount per payment. Present only for 'as_presented' subscriptions, null for regular subscriptions.
    Example: 5000

  - `start_date` (string, required)
    Start date of the subscription in UTC timezone and ISO 8601 format (YYYY-MM-DD).
    Example: 2025-01-01

  - `end_date` (string | null)
    The date on which the subscription ends in UTC timezone and ISO 8601 format (YYYY-MM-DD).
    Example: 2025-12-01

  - `expires_at` (string, required)
    Expiration date for the subscription payment link in UTC timezone and ISO 8601 format (YYYY-MM-DD).
    Example: 2025-01-07

  - `next_payment_date` (string | null)
    Date of the next scheduled payment in UTC timezone and ISO 8601 format (YYYY-MM-DD).
    Example: 2025-02-01

  - `subscription_link_url` (string, required)
    URL for the subscription payment page. Your customer can use this URL to make the first payment and activate the subscription.
    Example: https://checkout.glomopay.com/subscription/sub_5JU9yv0lGSUP

  - `cancelled_at` (string | null)
    Date when the subscription was cancelled in UTC timezone and ISO 8601 format (YYYY-MM-DD). This field is null unless the subscription status is 'cancelled'.
    Example: 2025-01-15

  - `halt_reason` (object | null)
    Present only when `status` is `halted`. Describes why the subscription was halted. Absent for all other statuses.

  - `halt_reason.code` (string, required)
    Machine-readable halt reason code.
    Enum: "MAX_RETRIES_REACHED", "CARD_EXPIRED"

  - `halt_reason.description` (string, required)
    Human-readable explanation of the halt reason.
    Example: The maximum number of auto-debit retry attempts was reached without a successful payment.

  - `payment_method` (object | null)
    The active payment method on the subscription, derived from the most recent successful payment. Returns `null` if no successful payment has been made yet (e.g. a newly created subscription or one where the first payment attempt failed).
    Example: {"type":"card","details":{"card_network":"Visa","card_type":"credit","end_digits":"4242","country_code":"IN","card_holder_name":"John Doe","card_bin":"424242","issuer_name":"HDFC Bank"}}

  - `payment_method.type` (string)
    The type of payment method. Currently only `card` is supported for subscriptions. Additional types (e.g. UPI, wallets) will be added as subscription support is extended.
    Enum: "card"

  - `payment_method.details` (object)
    Details specific to the payment method type.

  - `payment_method.details.card_network` (string)
    The card network (e.g., Visa, Mastercard, American Express).
    Example: Visa

  - `payment_method.details.card_type` (string)
    The type of card (e.g., credit, debit).
    Example: credit

  - `payment_method.details.end_digits` (string)
    The last four digits of the card number.
    Example: 4242

  - `payment_method.details.country_code` (string)
    The country code associated with the card.
    Example: IN

  - `payment_method.details.card_holder_name` (string)
    The name of the cardholder.
    Example: John Doe

  - `payment_method.details.card_bin` (string)
    The IIN (also known as BIN) — the card-number prefix that identifies the network, card type, and issuing country.
    Example: 424242

  - `payment_method.details.issuer_name` (string)
    The name of the card issuing bank or financial institution.
    Example: HDFC Bank

## Response 404 fields (application/json):

  - `error` (string)
    Enum: "Not Found"

  - `message` (string)
    Example: Subscription not found