---
title: "List subscriptions"
method: GET
path: "/billing/subscriptions"
---

# List subscriptions

`GET /billing/subscriptions`

## Request

- Base URL: `https://api-sandbox.ezypay.com/v2`
- URL: `https://api-sandbox.ezypay.com/v2/billing/subscriptions`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `https://identity-sandbox.ezypay.com/token`

Get a list of subscriptions for a specific merchant by customer, status and/or null payment methods. The subscriptions are returned sorted by creation date, with the most recently created subscription appearing first.

By default only 10 record will be listed, if the limit is not set when the API is being triggered.

## Query parameters

- `customerId` string
- `status` string
- `filterNullPaymentMethods` boolean
- `limit` integer
- `cursor` integer

## Headers

- `merchant` string, required

## Response `200`

200

- object
  - `data` object[]
    - `id` string
    - `customerId` string
    - `planId` string
    - `name` string
    - `status` string
    - `startDate` string
    - `endDate` unknown
    - `paymentMethodToken` string
    - `accountingCode` string
    - `amount` object
      - `currency` string
      - `value` integer
      - `type` unknown
    - `tax` object
      - `rate` integer
    - `nextBillingDate` string
    - `nextFutureInvoice` object
      - `subscriptionId` string
      - `date` string
      - `cycleStartDate` string
      - `cycleEndDate` string
      - `items` object[]
        - `description` string
        - `amount` object
          - `currency` string
          - `value` integer
          - `type` unknown
        - `tax` object
          - `rate` integer
        - `type` string
        - `accountingCode` string
      - `amount` object
        - `currency` string
        - `value` number
        - `type` unknown
      - `totalTax` object
        - `currency` string
        - `value` integer
        - `type` unknown
    - `interval` integer
    - `intervalUnit` string
    - `totalPaid` object
      - `currency` string
      - `value` integer
      - `type` unknown
    - `totalBillingCycles` integer
    - `remainingToPay` unknown
    - `remainingBillingCycles` unknown
    - `endTargetAmount` unknown
    - `endTargetBillingCycles` unknown
    - `cancelledDate` unknown
    - `failedPaymentHandling` unknown
    - `failedAttemptsCount` integer
    - `totalPastDue` object
      - `currency` string
      - `value` integer
      - `type` unknown
    - `totalDiscounted` object
      - `currency` string
      - `value` integer
      - `type` unknown
    - `metadata` unknown
    - `createdOn` string
    - `autoPayment` boolean
    - `setupPayments` unknown
    - `paymentMethodInvalidReason` unknown
    - `paymentMethodInvalidDescription` unknown
    - `paymentMethodInvalid` boolean
  - `paging` object
    - `nextUrl` unknown
    - `nextCursor` integer
    - `limit` integer
    - `totalCount` integer

## Other responses

- `400`: 400

## Changes

- **2026-11-03** `924be4030f56`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ezypay/apis/vault/changes/billing/subscriptions/get.md)

---

[API](https://skmtc.dev/ezypay/apis/vault.md) - [All operations](https://skmtc.dev/ezypay/apis/vault/llms.txt) - [OpenAPI document](https://skmtc.dev/ezypay/apis/vault/revisions/924be4030f56?raw)