---
title: "Get a subscription by ID"
method: GET
path: "/api/v3/subscriptions/{subscriptionId}"
tags: ["Subscriptions"]
---

# Get a subscription by ID

`GET /api/v3/subscriptions/{subscriptionId}`

## Path parameters

- `subscriptionId` string, uuid, required

## Response `200`

Subscription found.

- Subscription — Lifecycle: `PENDING` → (optional `TRIALING` before the first charge) → `ACTIVE` after checkout → `PAST_DUE` on a failed charge → terminal `CANCELED` / `EXPIRED`.
  - `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.

## Other responses

- `401` — Caller is unauthenticated.
- `403` — Caller is authenticated but not authorized for this resource.
- `404` — Resource not found.
- `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)