---
title: "List Subscriptions"
method: GET
path: "/v5/subscriptions"
tags: ["Subscriptions"]
---

# List Subscriptions

`GET /v5/subscriptions`

## Request

- Base URL: `https://sandbox.nmi.com/api`
- URL: `https://sandbox.nmi.com/api/v5/subscriptions`
- Auth: API key in header `Authorization`

Retrieve a list of subscriptions for the merchant with optional filtering and cursor-based pagination.

To look up a single subscription, use **Get Subscription**.

## Query parameters

- `customer_vault_id` string
- `date_from` string, date
- `date_to` string, date
- `cursor` string
- `per_page` integer

## Response `200`

Success

- object
  - `subscriptions` SubscriptionResponse[]: Subscriptions on this page, newest first
    - `object` 'subscription', required: Resource type identifier
    - `id` string, required: Subscription ID
    - `created_date` string, date-time: Date the subscription was created, in UTC ISO 8601 format
    - `start_date` string, date-time, nullable: Subscription start date in UTC ISO 8601 format
    - `next_billing_date` string, date-time, nullable: Next billing date in UTC ISO 8601 format
    - `amount` string: Subscription amount
    - `customer_vault_id` string: Customer vault ID associated with the subscription
    - `delayed_condition` string: Delayed condition
    - `paused_subscription` 0 | 1: Whether the subscription is paused (0 = active, 1 = paused)
    - `plan` object, nullable: Associated plan
      - `id` string: Plan ID
      - `plan_name` string: Plan name
      - `plan_amount` string: Plan amount
      - `plan_payments` string: Number of payments (0 = until canceled)
      - `day_frequency` string: Day frequency (0 if not applicable)
      - `month_frequency` string: Month frequency (0 if not applicable)
      - `day_of_month` string: Day of month (empty if not applicable)
  - `per_page` integer: Number of subscriptions requested per page
  - `has_more` boolean: Whether another page is available
  - `next_cursor` string: Cursor for the next page. Pass it as the `cursor` parameter on the next request. Omitted when there are no more results.

## Other responses

- `400`: Bad Request. For example, `date_from` or `date_to` is not a valid calendar date (such as `2026-02-30`), or `cursor` is invalid, was altered, or was issued for different filters.
- `401`: Unauthorized
- `422`: Unprocessable request. Returned when a query parameter fails validation (an unsupported parameter, a date not in YYYY-MM-DD format, or `per_page` out of range), or when the search matched too many records to return. Narrow the results with filters such as a date range and try again.

---

[API](https://skmtc.dev/nmi/apis/payments-api.md) - [All operations](https://skmtc.dev/nmi/apis/payments-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nmi/apis/payments-api/revisions/c03727f27e27?raw)