---
title: "Create a subscription"
method: POST
path: "/api/v3/subscriptions"
tags: ["Subscriptions"]
---

# Create a subscription

`POST /api/v3/subscriptions`

Subscribes a subscriber (by email) to one of your plans. Starts in
`PENDING` until the subscriber completes checkout. Pass
`customerProfile` to supply Travel Rule / AML customer data.

## Request body

- CreateSubscriptionRequest
  - `planId` string, uuid, required
  - `subscriber` SubscriberRef, required
    - `email` string, email, required — Subscriber's email.
  - `customerProfile` union — Optional customer profile, used to meet Travel Rule / AML obligations. `profileId` is returned as `Subscription.customerProfileId`; the rest of the profile is write-only and never returned by the API. **EU merchants:** merchants operating under the EU regulatory workflow must supply a complete customer profile with every subscription, to meet Travel Rule / AML obligations. The profile must be an `individual` (with `firstName`, `lastName`, `dateOfBirth`, and a full address — `streetAddress`, `city`, `postalCode`, `country`) or a `company` (with `registeredName`, `registrationNumber`, and a full address); a `reference` profile is not accepted. A missing or incomplete profile is rejected with HTTP 422 and error code `CUSTOMER_PROFILE_REQUIRED`. For other merchants the profile remains optional.
    - IndividualProfile
      - `type` 'individual' | 'company' | 'reference', required — Discriminator value for polymorphic CustomerProfile variants.
      - `profileId` string, required — Your customer id. Returned as `Subscription.customerProfileId` and accepted by the `customerProfileId` filter when listing subscriptions.
      - `streetAddress` string
      - `city` string
      - `postalCode` string
      - `country` string — ISO 3166-1 alpha-2.
      - `firstName` string
      - `lastName` string
      - `dateOfBirth` string, date
      - `placeOfBirth` string
    - CompanyProfile
      - `type` 'individual' | 'company' | 'reference', required — Discriminator value for polymorphic CustomerProfile variants.
      - `profileId` string, required — Your customer id. Returned as `Subscription.customerProfileId` and accepted by the `customerProfileId` filter when listing subscriptions.
      - `streetAddress` string
      - `city` string
      - `postalCode` string
      - `country` string — ISO 3166-1 alpha-2.
      - `registeredName` string
      - `registrationNumber` string
    - ReferenceProfile
      - `type` 'individual' | 'company' | 'reference', required — Discriminator value for polymorphic CustomerProfile variants.
      - `profileId` string, required — Your customer id. Returned as `Subscription.customerProfileId` and accepted by the `customerProfileId` filter when listing subscriptions.
      - `streetAddress` string
      - `city` string
      - `postalCode` string
      - `country` string — ISO 3166-1 alpha-2.
  - `amount` string — Per-subscription amount (value only; asset comes from the plan). Required when the plan is `VARIABLE`; must be omitted when the plan is `FIXED`.
  - `notifyUrl` string, uri — Webhook URL (http/https, max 2048 chars) for lifecycle and payment events.
  - `returnUrl` string, uri — Where the subscriber is redirected after completing or exiting checkout (http/https, max 2048 chars).

## Response `201`

Subscription created.

- 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

- `400` — Request is malformed or violates a validation rule.
- `401` — Caller is unauthenticated.
- `403` — Caller is authenticated but not authorized for this resource.
- `404` — Resource not found.
- `409` — Request conflicts with the current resource state.
- `422` — Request parsed but violates a business rule or invariant.
- `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)