# List subscriptions

Returns a list of subscriptions matching some criteria. The subscriptions are returned sorted by creation date, with the most recent subscriptions appearing first.

Endpoint: GET /subscriptions
Version: 1.0.0
Security: JWT

## Security:

  - `JWT` (unknown)
    http bearer JWT

## Query parameters:

  - `status` (string)
    Filter subscriptions by status. Uses the same values as the subscription's `status` field.

  - `customer_id` (string)
    Filter subscriptions by customer ID.

  - `start_date` (string)
    Filter subscriptions with a particular start date, in UTC timezone and ISO 8601 format (YYYY-MM-DD).

  - `end_date` (string)
    Filter subscriptions with a particular end date, in UTC timezone and ISO 8601 format (YYYY-MM-DD).

  - `before` (string)
    Return only resources created at or before this time. Send an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp with an offset, such as `2025-02-18T12:03:44Z` or `2025-02-18T17:33:44+05:30`. A timestamp without an offset is read as UTC. A bare date (`YYYY-MM-DD`) means the end of that day in UTC (`23:59:59.999999Z`). An invalid value returns `400 Bad Request`. Use this to avoid page drift. See [Pagination parameters](/platform/pagination#parameters) for more details.

  - `after` (string)
    Return only resources created at or after this time. Send an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp with an offset, such as `2025-01-18T12:03:44Z` or `2025-01-18T17:33:44+05:30`. A timestamp without an offset is read as UTC. A bare date (`YYYY-MM-DD`) means the start of that day in UTC (`00:00:00Z`). An invalid value returns `400 Bad Request`. Use this to avoid page drift. See [Pagination parameters](/platform/pagination#parameters) for more details.

  - `per_page` (integer)
    Number of resources per page. Should be between 1 and 100.

  - `page` (integer)
    Page number for pagination. Starts from 1. Get the next page number from the `next` field in the response.

## Response 200:

  - `200` (unknown)
    List of subscriptions matching the criteria.

## Response 200 fields (application/json):

  - `data` (array)

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

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

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

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

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

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

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

  - `data.status` (string, required)
    Current status of the subscription.
- `created` — the subscription exists and is waiting for the customer to authorise it.
- `authorized` — the customer has authorised the subscription and it has not become `active` yet.
- `active` — the subscription is charging on its schedule.
- `paused` — you paused the subscription. Resume it to continue charging.
- `halted` — charging stopped automatically; `halt_reason` says why. It returns to `active` after
its next successful payment, for example once the customer updates the card. The resume endpoint
applies only to `paused` subscriptions.
- `action_required` — Glomo needs more information before the subscription can proceed. Respond to
the open RFI to continue.
- `under_review` — the information you submitted is being reviewed. The subscription becomes
`active` if the review passes and `failed` if it does not.
- `completed` — every billing cycle has been charged. Terminal.
- `cancelled` — the subscription was cancelled. Terminal.
- `expired` — the customer did not authorise the subscription in time. Terminal.
- `failed` — the subscription could not be set up, or did not pass review. Terminal.
    Enum: "created", "authorized", "active", "paused", "halted", "action_required", "under_review", "completed", "cancelled", "expired", "failed"

  - `data.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

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

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

  - `data.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"

  - `data.billing_cycles` (integer | null)
    Total number of billing cycles for the subscription. Each cycle lasts `interval_count` units of `interval_type`, so 12 cycles with `interval_count` 1 and `interval_type` `month` span 12 months. `null` for `as_presented` subscriptions.
    Example: 12

  - `data.max_amount` (integer | null)
    Maximum allowed amount per payment, in the smallest unit of `currency` (cents for USD). `5000` is $50.00 when `currency` is USD. Present only for `as_presented` subscriptions, `null` for regular subscriptions.
    Example: 5000

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

  - `data.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

  - `data.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

  - `data.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

  - `data.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. The path is `/subscription-links/{id}`; in sandbox the URL ends with `?sandbox=true`. The host depends on your account, so share the URL exactly as returned rather than building it yourself.
    Example: https://your-dashboard-host.example/subscription-links/sub_5JU9yv0lGSUP

  - `data.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

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

  - `data.halt_reason.code` (string, required)
    Machine-readable halt reason code.
- `MAX_RETRIES_REACHED` — every retry of a failed charge was used up without a successful payment.
- `CARD_EXPIRED` — the card saved on the subscription has expired.
- `MIGRATION_INCOMPLETE` — the Visa card was not re-registered with Glomo's new card-processing
setup within the migration window.
    Enum: "MAX_RETRIES_REACHED", "CARD_EXPIRED", "MIGRATION_INCOMPLETE"

  - `data.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.

  - `data.notes` (object | null)
    Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. Your account may require some `notes` fields: Glomo configures custom field rules per account, and for beneficiaries they are checked when the beneficiary is created. Some fields are also validated by the beneficiary's country (for example, a PAN format for Indian beneficiaries). A missing required field returns `422` with `Validation failed: Notes <field> is required`, and type and validation errors (such as enum constraints) are returned the same way. The rule is set on your account, not by currency or rail. No API lists the fields, but the `422` names each missing one: add that key to `notes` with the value your account expects, and ask your Glomo account manager if you don't know what the field should hold. See [Custom fields](/payin/custom-fields). Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
    Example: {"invoice_ref":"INV-2026-001","project":"Alpha"}

  - `data.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"}}

  - `data.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"

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

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

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

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

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

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

  - `data.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

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

  - `page_meta` (object)

  - `page_meta.current` (integer)
    The current page number.
    Example: 2

  - `page_meta.previous` (integer | null)
    The previous page number.
    Example: 1

  - `page_meta.next` (integer | null)
    The next page number.
    Example: 3

  - `page_meta.per_page` (integer)
    The number of items per page.
    Example: 20

  - `page_meta.pages` (integer)
    The total number of pages.
    Example: 10

  - `page_meta.count` (integer)
    The total number of items.
    Example: 200

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `error` (string)
    Enum: "Bad Request"

  - `message` (string)
    Error message indicating why the request failed