---
title: "List your subscriptions"
method: GET
path: "/api/v3/subscriptions"
tags: ["Subscriptions"]
---

# List your subscriptions

`GET /api/v3/subscriptions`

Returns your subscriptions, newest first. Use the filters to
narrow by status, `customerProfileId`, or createdAt window.

## Query parameters

- `status` SubscriptionStatus[]
- `customerProfileId` string
- `createdFrom` integer
- `createdTo` integer
- `pageSize` integer
- `cursor` string

## Response `200`

Subscriptions matching the filter.

- SubscriptionPage
  - `items` Subscription[], required
    - `id` string, uuid, required
    - `planId` string, uuid, required
    - `planName` string, required — Current name of the plan.
    - `amount` Price, required — Monetary amount. `amount` is a decimal string. `asset` is an ISO 4217 code for fiat or an uppercase stablecoin symbol — e.g. `USD`, `EUR`, `USDC`, `USDT`.
      - `amount` string, required
      - `asset` string, required
    - `customerProfileId` string, nullable — Your customer profile id, as supplied at creation (customerProfile.profileId).
    - `email` string, email, nullable — Subscriber's email address. Null when the subscriber has no email on file.
    - `notifyUrl` string, uri, nullable — Webhook URL for lifecycle and payment events, as supplied at creation.
    - `returnUrl` string, uri, nullable — Where the subscriber is redirected after checkout, as supplied at creation.
    - `checkoutUrl` string, uri, nullable — Hosted checkout link to send the subscriber to. Present while the subscription is awaiting checkout (`PENDING`); null once checkout is complete or no longer applicable.
    - `status` 'PENDING' | 'TRIALING' | 'ACTIVE' | 'PAST_DUE' | 'CANCELED' | 'EXPIRED', required — Subscription lifecycle state. `PENDING` — created; awaiting subscriber checkout. `TRIALING` — in a trial period before the first charge. `ACTIVE` — checkout complete; billing on schedule. `PAST_DUE` — a charge failed; retrying within the grace period before a terminal state. `CANCELED` — stopped before its natural end (see `cancelReason`). `EXPIRED` — ended naturally or after retries were exhausted (see `expiryReason`).
    - `startDate` integer — Unix epoch seconds.
    - `cycleNumber` integer, required — How many billing cycles have started.
    - `currentPeriod` CurrentPeriod — The current billing period. Null before the subscription is `ACTIVE`.
      - `start` integer, required — Unix epoch seconds.
      - `end` integer, required — Unix epoch seconds.
    - `nextPaymentDate` integer — Unix epoch seconds.
    - `endsAt` integer — Unix epoch seconds.
    - `cancellation` Cancellation — Cancellation details. Null unless `status` is `CANCELED`.
      - `at` integer, required — Unix epoch seconds.
      - `reason` 'SUBSCRIBER' | 'MERCHANT' | 'MERCHANT_DISABLED' | 'ADMIN' | 'EXPIRED' | 'DUNNING_EXHAUSTED' | 'SANCTIONS_HIT' | 'CHECKOUT_TIMEOUT', required — Why a subscription was canceled. `SUBSCRIBER` — canceled by the subscriber. `MERCHANT` — canceled by you. `MERCHANT_DISABLED` — canceled because your account was disabled. `ADMIN` — canceled by Confirmo (e.g. for compliance reasons). `EXPIRED` — canceled as part of the subscription expiring. `DUNNING_EXHAUSTED` — automatically canceled after payment retries were exhausted. `SANCTIONS_HIT` — canceled automatically because a sanctions/risk screening blocked the payment. `CHECKOUT_TIMEOUT` — canceled automatically because the checkout was not completed before it timed out.
    - `expiration` Expiration — Expiration details. Null unless `status` is `EXPIRED`.
      - `at` integer, required — Unix epoch seconds.
      - `reason` 'TERM_REACHED' | 'PAYMENT_FAILED', required — Why a subscription expired. `TERM_REACHED` — the plan's fixed `termCycles` completed. `PAYMENT_FAILED` — automatically ended after payment retries were exhausted.
    - `createdAt` integer, required — Unix epoch seconds.
    - `updatedAt` integer, required — Unix epoch seconds.
  - `nextCursor` string — Opaque cursor for the next page. Present only when `hasMore` is true.
  - `hasMore` boolean, required

## Other responses

- `400` — Request is malformed or violates a validation rule.
- `401` — Caller is unauthenticated.
- `403` — Caller is authenticated but not authorized for this resource.
- `500` — Unexpected server error.

---

[API](https://skmtc.dev/confirmo/apis/confirmo-subscribe-api.md) · [All operations](https://skmtc.dev/confirmo/apis/confirmo-subscribe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/confirmo/confirmo-subscribe-api/revisions/105015030952/schema)