# 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

## Query parameters:

  - `status` (string)
    Filter subscriptions by status.
    Enum: "created", "active", "paused", "expired", "failed", "halted", "cancelled", "completed"

  - `customer_id` (string)
    Filter subscriptions by customer ID.
    Example: "cust_5JU9yv0lGSUP"

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

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

  - `before` (string)
    ISO-8601 timestamp in UTC to filter resources created before this time. Use this to avoid Page drift issue. See Pagination parameters for more details.
    Example: "2025-02-18T12:03:44Z"

  - `after` (string)
    ISO-8601 timestamp in UTC to filter resources created after this time. Use this to avoid Page drift issue. See Pagination parameters for more details.
    Example: "2025-01-18T12:03:44Z"

  - `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 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.
    Enum: "created", "active", "paused", "expired", "failed", "halted", "cancelled", "completed", "authorized"

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

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

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

  - `data.interval_count` (integer, required)
    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
    Enum: 1, 3, 6

  - `data.billing_cycles` (integer, required)
    Total number of billing cycles for the subscription.
    Example: 12

  - `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, required)
    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.
    Example: "https://checkout.glomopay.com/subscription/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.notes` (object)
    Any additional notes for the order
    Example: {"key1":"value1","key2":"value2"}

  - `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 fields (application/json):

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

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