---
title: "A subscription was created"
method: POST
path: "subscription.created"
tags: ["Webhooks"]
---

# A subscription was created

`POST subscription.created` (webhook)

Sent when a subscription is created. It usually starts in `PENDING`
while the subscriber completes checkout. `payload.data` is the full
`Subscription`.

## Payload

- SubscriptionCreatedEvent — The wrapper delivered for every webhook event. `payload.data` holds the event-specific resource — a `Subscription` or a `Payment`.
  - `id` string, uuid, required — Unique id of this event (UUIDv7). Stable across redeliveries — delivery is at-least-once and the same `id` is replayed on retry, so use it to dedupe.
  - `timestamp` string, date-time, required — When the event was produced (ISO-8601 UTC).
  - `entityId` string, uuid, required — The subscription this event concerns. Always the subscription id, even for payment events — which route to their parent subscription.
  - `version` integer, required — Monotonically increasing per subscription. Use it to order a subscription's events and discard stale redeliveries.
  - `payload` object, required — The inner event body. The `data` property — typed per event family — carries the affected resource.
    - `eventType` 'subscription.created', required — Identifies the event — one of the types listed under Webhooks.
    - `resourceType` 'subscription', required — The routed resource kind. Always `subscription`.
    - `entityId` string, uuid, required — The subscription id this event routes to (same as the envelope `entityId`).
    - `data` Subscription, required — 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.

## Acknowledgement `2XX`

Return any 2xx status to acknowledge receipt. Any other response
(or a timeout) is treated as a delivery failure and retried.

---

[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)