{ "openapi": "3.1.0", "info": { "title": "Confirmo Subscribe API", "version": "3.0.0", "description": "Confirmo's subscription API. Create and manage subscription plans, track\nsubscriptions and payments.\n\nAuthenticate every request with a bearer API key from your Confirmo\ndashboard. Your account scope is determined by the key — you never\nsupply your merchant ID on individual requests.\n" }, "servers": [ { "url": "https://api.confirmo.com" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Plans", "description": "Subscription plans you offer to your subscribers." }, { "name": "Subscriptions", "description": "Your subscribers' active and past subscriptions." }, { "name": "Payments", "description": "Recurring-billing payment records." }, { "name": "Webhooks", "description": "Confirmo notifies you of subscription and payment events by POSTing a\nJSON envelope to the `notifyUrl` you set when creating a subscription.\n\n**Delivery.** At-least-once. Return any `2xx` status to acknowledge\nreceipt; a non-2xx response or a timeout is treated as a delivery\nfailure and retried. The same event may therefore arrive more than\nonce — dedupe on the envelope `id`, which is stable across\nredeliveries.\n\n**Ordering.** Events for a single subscription carry a monotonically\nincreasing `version`. Use it to order events for that subscription and\ndiscard stale redeliveries. Events across different subscriptions are\nnot ordered relative to one another.\n\n**Verification.** Every request is signed; verify the signature\nagainst the raw request body before trusting the payload. (Signing\nand header details are not finalized.)\n\nAll events share one envelope (see `WebhookEnvelope`). The\n`payload.data` object has the same shape as the corresponding REST\nresource: a `Subscription` for lifecycle events, a `Payment` for\npayment events.\n" } ], "paths": { "/api/v3/subscriptions/plans": { "post": { "operationId": "createPlan", "tags": [ "Plans" ], "summary": "Create a subscription plan", "description": "Create a plan your subscribers can subscribe to.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePlanRequest" } } } }, "responses": { "201": { "description": "Plan created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "listPlans", "tags": [ "Plans" ], "summary": "List your subscription plans", "description": "Returns all your plans, newest first, regardless of status. Use the\n`nextCursor` from the previous response to fetch the next page.\n", "parameters": [ { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "description": "Your plans, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v3/subscriptions/plans/{planId}": { "get": { "operationId": "getPlan", "tags": [ "Plans" ], "summary": "Get a subscription plan by ID", "parameters": [ { "$ref": "#/components/parameters/PlanIdPath" } ], "responses": { "200": { "description": "Plan found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v3/subscriptions/plans/{planId}/archive": { "post": { "operationId": "archivePlan", "tags": [ "Plans" ], "summary": "Archive a subscription plan", "description": "Archived plans can't be subscribed to, but existing subscriptions\non the plan continue billing unchanged. Archiving is one-way and\nidempotent.\n", "parameters": [ { "$ref": "#/components/parameters/PlanIdPath" } ], "responses": { "200": { "description": "Plan archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Plan" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v3/subscriptions": { "post": { "operationId": "createSubscription", "tags": [ "Subscriptions" ], "summary": "Create a subscription", "description": "Subscribes a subscriber (by email) to one of your plans. Starts in\n`PENDING` until the subscriber completes checkout. Pass\n`customerProfile` to supply Travel Rule / AML customer data.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSubscriptionRequest" } } } }, "responses": { "201": { "description": "Subscription created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "operationId": "listSubscriptions", "tags": [ "Subscriptions" ], "summary": "List your subscriptions", "description": "Returns your subscriptions, newest first. Use the filters to\nnarrow by status, `customerProfileId`, or createdAt window.\n", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Repeatable. Limits the result to subscriptions in any of the given statuses.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionStatus" } }, "style": "form", "explode": true }, { "name": "customerProfileId", "in": "query", "required": false, "description": "Look up a subscription by the `customerProfileId` you supplied when creating it.", "schema": { "type": "string", "maxLength": 128 } }, { "name": "createdFrom", "in": "query", "required": false, "description": "Inclusive lower bound on `createdAt`, Unix epoch seconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "createdTo", "in": "query", "required": false, "description": "Exclusive upper bound on `createdAt`, Unix epoch seconds.", "schema": { "type": "integer", "format": "int64" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "description": "Subscriptions matching the filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v3/subscriptions/{subscriptionId}": { "get": { "operationId": "getSubscription", "tags": [ "Subscriptions" ], "summary": "Get a subscription by ID", "parameters": [ { "$ref": "#/components/parameters/SubscriptionIdPath" } ], "responses": { "200": { "description": "Subscription found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v3/subscriptions/{subscriptionId}/cancel": { "post": { "operationId": "cancelSubscription", "tags": [ "Subscriptions" ], "summary": "Cancel a subscription", "description": "Stops future billing. Idempotent — canceling an already-canceled\nsubscription returns its current state. A subscription that has\nalready expired cannot be canceled (`409`).\n", "parameters": [ { "$ref": "#/components/parameters/SubscriptionIdPath" } ], "responses": { "200": { "description": "Subscription canceled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v3/subscriptions/payments": { "get": { "operationId": "listPayments", "tags": [ "Payments" ], "summary": "List payments", "description": "Returns payments across all your subscriptions, newest first. Use\nthe filters to scope to a single subscription, restrict by status,\nor restrict to a createdAt window.\n", "parameters": [ { "name": "subscriptionId", "in": "query", "required": false, "description": "Restrict to one subscription.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Repeatable. Limits the result to payments in any of the given statuses.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentStatus" } }, "style": "form", "explode": true }, { "name": "createdFrom", "in": "query", "required": false, "description": "Inclusive lower bound on `createdAt`, Unix epoch seconds.", "schema": { "type": "integer", "format": "int64" } }, { "name": "createdTo", "in": "query", "required": false, "description": "Exclusive upper bound on `createdAt`, Unix epoch seconds.", "schema": { "type": "integer", "format": "int64" } }, { "$ref": "#/components/parameters/PageSize" }, { "$ref": "#/components/parameters/PageCursor" } ], "responses": { "200": { "description": "Payments matching the filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v3/subscriptions/payments/{paymentId}": { "get": { "operationId": "getPayment", "tags": [ "Payments" ], "summary": "Get a payment by ID", "parameters": [ { "name": "paymentId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Payment found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "webhooks": { "subscription.created": { "post": { "operationId": "subscriptionCreatedEvent", "tags": [ "Webhooks" ], "summary": "A subscription was created", "description": "Sent when a subscription is created. It usually starts in `PENDING`\nwhile the subscriber completes checkout. `payload.data` is the full\n`Subscription`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Any other response\n(or a timeout) is treated as a delivery failure and retried.\n" } } } }, "subscription.activated": { "post": { "operationId": "subscriptionActivatedEvent", "tags": [ "Webhooks" ], "summary": "A subscription became active", "description": "Sent when a subscription becomes `ACTIVE` — the subscriber has\ncompleted checkout and billing is now on schedule. `payload.data` is\nthe full `Subscription`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionActivatedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Any other response\n(or a timeout) is treated as a delivery failure and retried.\n" } } } }, "subscription.past_due": { "post": { "operationId": "subscriptionPastDueEvent", "tags": [ "Webhooks" ], "summary": "A subscription became past due", "description": "Sent when a charge fails and the subscription enters `PAST_DUE`.\nBilling retries during the grace period before a terminal state.\n`payload.data` is the full `Subscription`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPastDueEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Any other response\n(or a timeout) is treated as a delivery failure and retried.\n" } } } }, "subscription.resumed": { "post": { "operationId": "subscriptionResumedEvent", "tags": [ "Webhooks" ], "summary": "A past-due subscription recovered", "description": "Sent when a `PAST_DUE` subscription recovers — a retry succeeded\nwithin the grace period and billing is `ACTIVE` again. `payload.data`\nis the full `Subscription`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionResumedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Any other response\n(or a timeout) is treated as a delivery failure and retried.\n" } } } }, "subscription.canceled": { "post": { "operationId": "subscriptionCanceledEvent", "tags": [ "Webhooks" ], "summary": "A subscription was canceled", "description": "Sent when a subscription is canceled before its natural end. See\n`payload.data.cancellation.reason` for who canceled it and why.\n`payload.data` is the full `Subscription`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCanceledEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Any other response\n(or a timeout) is treated as a delivery failure and retried.\n" } } } }, "subscription.expired": { "post": { "operationId": "subscriptionExpiredEvent", "tags": [ "Webhooks" ], "summary": "A subscription expired", "description": "Sent when a subscription ends naturally — its fixed term completed,\nor payment retries were exhausted. See `payload.data.expiration.reason`.\n`payload.data` is the full `Subscription`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionExpiredEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Any other response\n(or a timeout) is treated as a delivery failure and retried.\n" } } } }, "subscription.payment.succeeded": { "post": { "operationId": "subscriptionPaymentSucceededEvent", "tags": [ "Webhooks" ], "summary": "A recurring charge succeeded", "description": "Sent when a recurring charge settles successfully. `payload.data` is\nthe `Payment` record; `payload.entityId` is the parent subscription.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPaymentSucceededEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Any other response\n(or a timeout) is treated as a delivery failure and retried.\n" } } } }, "subscription.payment.failed": { "post": { "operationId": "subscriptionPaymentFailedEvent", "tags": [ "Webhooks" ], "summary": "A recurring charge failed", "description": "Sent when a recurring charge fails to settle. `payload.data` is the\n`Payment` record; see `payload.data.failureReason`.\n`payload.entityId` is the parent subscription.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionPaymentFailedEvent" } } } }, "responses": { "2XX": { "description": "Return any 2xx status to acknowledge receipt. Any other response\n(or a timeout) is treated as a delivery failure and retried.\n" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer API key issued from your Confirmo dashboard. The key\nidentifies your account — you don't supply a merchant ID on\nindividual requests.\n" } }, "parameters": { "PageSize": { "name": "pageSize", "in": "query", "required": false, "description": "Maximum items per page. Defaults to 20, capped at 100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "PlanIdPath": { "name": "planId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "SubscriptionIdPath": { "name": "subscriptionId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, "PageCursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } }, "schemas": { "CreatePlanRequest": { "type": "object", "description": "A `FIXED` plan carries a `price` (every subscription bills it) and must omit\n`asset`. A `VARIABLE` plan carries only an `asset` — the amount is supplied\nper subscription at creation — and must omit `price`.\n", "required": [ "name", "type", "billingInterval", "gracePeriod" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256 }, "type": { "$ref": "#/components/schemas/PlanType" }, "price": { "$ref": "#/components/schemas/Price", "description": "Required for `FIXED` plans; must be omitted for `VARIABLE` plans." }, "asset": { "type": "string", "pattern": "^[A-Z0-9]{3,16}$", "example": "USD", "description": "Billing asset for a `VARIABLE` plan (the amount is supplied per\nsubscription). Required when `type` is `VARIABLE`; ignored for `FIXED`\n(asset is taken from `price.asset`).\n" }, "billingInterval": { "$ref": "#/components/schemas/BillingInterval" }, "termCycles": { "type": "integer", "minimum": 1, "nullable": true, "description": "Number of billing cycles before the subscription term ends. Unit follows `billingInterval`. Null or omitted means the subscription renews indefinitely.\n" }, "gracePeriod": { "$ref": "#/components/schemas/TimePeriod", "description": "How long failed payments are retried while the subscription is `PAST_DUE` before it reaches a terminal state. Must be a whole number of days between 1 and 7 (`P1D`–`P7D`).\n" } } }, "Plan": { "type": "object", "required": [ "id", "name", "type", "asset", "billingInterval", "gracePeriod", "status", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/PlanType" }, "asset": { "type": "string", "pattern": "^[A-Z0-9]{3,16}$", "example": "USD", "description": "The plan's billing asset. Always present (equals `price.asset` for `FIXED` plans)." }, "price": { "$ref": "#/components/schemas/Price", "description": "The fixed price for `FIXED` plans; absent for `VARIABLE` plans." }, "billingInterval": { "$ref": "#/components/schemas/BillingInterval" }, "termCycles": { "type": "integer", "minimum": 1, "nullable": true, "description": "Number of billing cycles in the plan's term; null means it renews indefinitely." }, "gracePeriod": { "$ref": "#/components/schemas/TimePeriod", "description": "How long failed payments are retried while the subscription is `PAST_DUE` before it reaches a terminal state. Always a whole number of days between 1 and 7 (`P1D`–`P7D`).\n" }, "status": { "$ref": "#/components/schemas/PlanStatus" }, "createdAt": { "$ref": "#/components/schemas/EpochSeconds" }, "updatedAt": { "$ref": "#/components/schemas/EpochSeconds" } } }, "PlanPage": { "type": "object", "required": [ "items", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Plan" } }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page. Present only when `hasMore` is true." }, "hasMore": { "type": "boolean" } } }, "Price": { "type": "object", "description": "Monetary amount. `amount` is a decimal string. `asset` is an\nISO 4217 code for fiat or an uppercase stablecoin symbol —\ne.g. `USD`, `EUR`, `USDC`, `USDT`.\n", "required": [ "amount", "asset" ], "properties": { "amount": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "example": "29.00" }, "asset": { "type": "string", "pattern": "^[A-Z0-9]{3,16}$", "example": "USD" } } }, "BillingInterval": { "type": "string", "description": "How often the subscription is billed.", "enum": [ "MONTHLY", "ANNUAL" ] }, "EpochSeconds": { "type": "integer", "format": "int64", "description": "Unix epoch seconds.", "example": 1748513400 }, "CurrentPeriod": { "type": "object", "description": "The current billing period. Null before the subscription is `ACTIVE`.", "required": [ "start", "end" ], "properties": { "start": { "$ref": "#/components/schemas/EpochSeconds", "description": "Start of the current billing period." }, "end": { "$ref": "#/components/schemas/EpochSeconds", "description": "End of the current billing period." } } }, "Cancellation": { "type": "object", "description": "Cancellation details. Null unless `status` is `CANCELED`.", "required": [ "at", "reason" ], "properties": { "at": { "$ref": "#/components/schemas/EpochSeconds", "description": "When the subscription was canceled." }, "reason": { "$ref": "#/components/schemas/CancelReason", "description": "Why the subscription was canceled." } } }, "Expiration": { "type": "object", "description": "Expiration details. Null unless `status` is `EXPIRED`.", "required": [ "at", "reason" ], "properties": { "at": { "$ref": "#/components/schemas/EpochSeconds", "description": "When the subscription expired." }, "reason": { "$ref": "#/components/schemas/ExpiryReason", "description": "Why the subscription expired." } } }, "PaymentFailure": { "type": "object", "description": "Failure details. Null unless `status` is `FAILED`.", "required": [ "reason" ], "properties": { "reason": { "type": "string", "description": "Classification of the failure. One of a fixed set of values: `INSUFFICIENT_BALANCE`, `INSUFFICIENT_ALLOWANCE`, `ON_CHAIN_REVERT`, `DROPPED_BY_BLOCKCHAIN`, `REJECTED_BY_COMPLIANCE`, `PROVIDER_ERROR`, `UNKNOWN`." } } }, "PlanStatus": { "type": "string", "description": "`ACTIVE` — open for new subscriptions.\n`ARCHIVED` — closed to new subscriptions; existing subscriptions keep billing.\n", "enum": [ "ACTIVE", "ARCHIVED" ] }, "PlanType": { "type": "string", "description": "How a plan's billed amount is determined.\n`FIXED` — the plan carries a fixed `price`; every subscription bills it.\n`VARIABLE` — the plan carries only an `asset`; the amount is set per\nsubscription at creation.\n", "enum": [ "FIXED", "VARIABLE" ] }, "TimePeriod": { "type": "string", "description": "ISO-8601 calendar period. Examples: `P7D` (7 days), `P1M`\n(1 month), `P1Y` (1 year). Sub-day precision is not supported.\n", "pattern": "^P(\\d+Y)?(\\d+M)?(\\d+W)?(\\d+D)?$", "example": "P3D" }, "CreateSubscriptionRequest": { "type": "object", "required": [ "planId", "subscriber" ], "properties": { "planId": { "type": "string", "format": "uuid" }, "subscriber": { "$ref": "#/components/schemas/SubscriberRef" }, "customerProfile": { "$ref": "#/components/schemas/CustomerProfile" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "example": "49.00", "description": "Per-subscription amount (value only; asset comes from the plan).\nRequired when the plan is `VARIABLE`; must be omitted when the plan is `FIXED`.\n" }, "notifyUrl": { "type": "string", "format": "uri", "description": "Webhook URL (http/https, max 2048 chars) for lifecycle and payment events." }, "returnUrl": { "type": "string", "format": "uri", "description": "Where the subscriber is redirected after completing or exiting checkout (http/https, max 2048 chars)." } } }, "SubscriberRef": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "Subscriber's email." } } }, "Subscription": { "type": "object", "description": "Lifecycle: `PENDING` → (optional `TRIALING` before the first charge) →\n`ACTIVE` after checkout → `PAST_DUE` on a failed charge → terminal\n`CANCELED` / `EXPIRED`.\n", "required": [ "id", "planId", "planName", "status", "cycleNumber", "amount", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "planId": { "type": "string", "format": "uuid" }, "planName": { "type": "string", "description": "Current name of the plan." }, "amount": { "$ref": "#/components/schemas/Price", "description": "Resolved per-cycle charge in the plan's asset — the plan `price` for\n`FIXED` plans, or this subscription's amount for `VARIABLE` plans.\n" }, "customerProfileId": { "type": "string", "nullable": true, "description": "Your customer profile id, as supplied at creation (customerProfile.profileId)." }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Subscriber's email address. Null when the subscriber has no email on file." }, "notifyUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Webhook URL for lifecycle and payment events, as supplied at creation." }, "returnUrl": { "type": "string", "format": "uri", "nullable": true, "description": "Where the subscriber is redirected after checkout, as supplied at creation." }, "checkoutUrl": { "type": "string", "format": "uri", "nullable": true, "description": "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.\n" }, "status": { "$ref": "#/components/schemas/SubscriptionStatus" }, "startDate": { "$ref": "#/components/schemas/EpochSeconds", "nullable": true, "description": "When the subscription started its first cycle. Null until it becomes `ACTIVE`." }, "cycleNumber": { "type": "integer", "minimum": 0, "description": "How many billing cycles have started." }, "currentPeriod": { "allOf": [ { "$ref": "#/components/schemas/CurrentPeriod" } ], "nullable": true, "description": "Current billing period. Null before the subscription is `ACTIVE`." }, "nextPaymentDate": { "$ref": "#/components/schemas/EpochSeconds", "nullable": true, "description": "When the next charge is due. Null when no further charge is scheduled." }, "endsAt": { "$ref": "#/components/schemas/EpochSeconds", "nullable": true, "description": "When the subscription's fixed term ends, for plans with a finite `termCycles`. Null for subscriptions that renew indefinitely.\n" }, "cancellation": { "allOf": [ { "$ref": "#/components/schemas/Cancellation" } ], "nullable": true, "description": "Cancellation details. Null unless `status` is `CANCELED`." }, "expiration": { "allOf": [ { "$ref": "#/components/schemas/Expiration" } ], "nullable": true, "description": "Expiration details. Null unless `status` is `EXPIRED`." }, "createdAt": { "$ref": "#/components/schemas/EpochSeconds" }, "updatedAt": { "$ref": "#/components/schemas/EpochSeconds" } } }, "SubscriptionPage": { "type": "object", "required": [ "items", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page. Present only when `hasMore` is true." }, "hasMore": { "type": "boolean" } } }, "SubscriptionStatus": { "type": "string", "description": "Subscription lifecycle state.\n`PENDING` — created; awaiting subscriber checkout.\n`TRIALING` — in a trial period before the first charge.\n`ACTIVE` — checkout complete; billing on schedule.\n`PAST_DUE` — a charge failed; retrying within the grace period before a terminal state.\n`CANCELED` — stopped before its natural end (see `cancelReason`).\n`EXPIRED` — ended naturally or after retries were exhausted (see `expiryReason`).\n", "enum": [ "PENDING", "TRIALING", "ACTIVE", "PAST_DUE", "CANCELED", "EXPIRED" ] }, "CancelReason": { "type": "string", "description": "Why a subscription was canceled.\n`SUBSCRIBER` — canceled by the subscriber.\n`MERCHANT` — canceled by you.\n`MERCHANT_DISABLED` — canceled because your account was disabled.\n`ADMIN` — canceled by Confirmo (e.g. for compliance reasons).\n`EXPIRED` — canceled as part of the subscription expiring.\n`DUNNING_EXHAUSTED` — automatically canceled after payment retries were exhausted.\n`SANCTIONS_HIT` — canceled automatically because a sanctions/risk screening blocked the payment.\n`CHECKOUT_TIMEOUT` — canceled automatically because the checkout was not completed before it timed out.\n", "enum": [ "SUBSCRIBER", "MERCHANT", "MERCHANT_DISABLED", "ADMIN", "EXPIRED", "DUNNING_EXHAUSTED", "SANCTIONS_HIT", "CHECKOUT_TIMEOUT" ] }, "ExpiryReason": { "type": "string", "description": "Why a subscription expired.\n`TERM_REACHED` — the plan's fixed `termCycles` completed.\n`PAYMENT_FAILED` — automatically ended after payment retries were exhausted.\n", "enum": [ "TERM_REACHED", "PAYMENT_FAILED" ] }, "Payment": { "type": "object", "description": "A single recurring-billing charge. One record per attempted cycle;\nstarts as `PENDING` and settles to `SUCCEEDED` or `FAILED`.\n", "required": [ "id", "subscriptionId", "billedAmount", "paidAmount", "status", "cycleNumber", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "subscriptionId": { "type": "string", "format": "uuid" }, "billedAmount": { "$ref": "#/components/schemas/Price", "description": "Amount billed, in the subscription's billing asset." }, "paidAmount": { "$ref": "#/components/schemas/Price", "description": "Amount settled on chain, in the asset paid." }, "balance": { "allOf": [ { "$ref": "#/components/schemas/PaymentBalance" } ], "nullable": true, "description": "What the merchant is credited in, with the fee broken down in that asset. Null for non-SUCCEEDED payments." }, "status": { "$ref": "#/components/schemas/PaymentStatus" }, "paidAt": { "$ref": "#/components/schemas/EpochSeconds", "nullable": true, "description": "When the payment settled. Null until `status` is `SUCCEEDED`." }, "failure": { "allOf": [ { "$ref": "#/components/schemas/PaymentFailure" } ], "nullable": true, "description": "Failure details. Null unless `status` is `FAILED`." }, "cycleNumber": { "type": "integer", "minimum": 0, "description": "Which billing cycle this payment belongs to." }, "createdAt": { "$ref": "#/components/schemas/EpochSeconds" } } }, "PaymentPage": { "type": "object", "required": [ "items", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "nextCursor": { "type": "string", "description": "Opaque cursor for the next page. Present only when `hasMore` is true." }, "hasMore": { "type": "boolean" } } }, "PaymentStatus": { "type": "string", "description": "`PENDING` — charge initiated, not yet settled.\n`SUCCEEDED` — charge settled successfully.\n`FAILED` — charge did not settle.\n", "enum": [ "PENDING", "SUCCEEDED", "FAILED" ] }, "PaymentBalance": { "type": "object", "required": [ "asset", "amount", "feeBase", "feeProvider", "feeNetwork", "feeTotal" ], "description": "Balance view of a succeeded payment. `asset` is the fiat code for a\nconversion, or the paid stablecoin for \"same crypto as paid\".\n`feeTotal == feeBase + feeProvider + feeNetwork`.\n", "properties": { "asset": { "type": "string", "description": "AnyAsset code (fiat or stablecoin)." }, "amount": { "type": "string", "description": "Gross credited, in `asset`." }, "feeBase": { "type": "string" }, "feeProvider": { "type": "string" }, "feeNetwork": { "type": "string" }, "feeTotal": { "type": "string" } } }, "WebhookEnvelope": { "type": "object", "description": "The wrapper delivered for every webhook event. `payload.data` holds\nthe event-specific resource — a `Subscription` or a `Payment`.\n", "required": [ "id", "timestamp", "entityId", "version", "payload" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique id of this event (UUIDv7). Stable across redeliveries —\ndelivery is at-least-once and the same `id` is replayed on retry,\nso use it to dedupe.\n" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the event was produced (ISO-8601 UTC)." }, "entityId": { "type": "string", "format": "uuid", "description": "The subscription this event concerns. Always the subscription id,\neven for payment events — which route to their parent subscription.\n" }, "version": { "type": "integer", "format": "int64", "description": "Monotonically increasing per subscription. Use it to order a\nsubscription's events and discard stale redeliveries.\n" }, "payload": { "$ref": "#/components/schemas/WebhookPayload" } } }, "WebhookPayload": { "type": "object", "description": "The inner event body. The `data` property — typed per event family —\ncarries the affected resource.\n", "required": [ "eventType", "resourceType", "entityId" ], "properties": { "eventType": { "type": "string", "description": "Identifies the event — one of the types listed under Webhooks.", "example": "subscription.activated" }, "resourceType": { "type": "string", "const": "subscription", "description": "The routed resource kind. Always `subscription`." }, "entityId": { "type": "string", "format": "uuid", "description": "The subscription id this event routes to (same as the envelope `entityId`)." } } }, "SubscriptionEventPayload": { "description": "Webhook payload whose `data` is a `Subscription`.", "allOf": [ { "$ref": "#/components/schemas/WebhookPayload" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Subscription" } } } ] }, "PaymentEventPayload": { "description": "Webhook payload whose `data` is a `Payment`.", "allOf": [ { "$ref": "#/components/schemas/WebhookPayload" }, { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } } ] }, "SubscriptionCreatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "payload": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEventPayload" }, { "type": "object", "properties": { "eventType": { "const": "subscription.created" } } } ] } } } ] }, "SubscriptionActivatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "payload": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEventPayload" }, { "type": "object", "properties": { "eventType": { "const": "subscription.activated" } } } ] } } } ] }, "SubscriptionPastDueEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "payload": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEventPayload" }, { "type": "object", "properties": { "eventType": { "const": "subscription.past_due" } } } ] } } } ] }, "SubscriptionResumedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "payload": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEventPayload" }, { "type": "object", "properties": { "eventType": { "const": "subscription.resumed" } } } ] } } } ] }, "SubscriptionCanceledEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "payload": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEventPayload" }, { "type": "object", "properties": { "eventType": { "const": "subscription.canceled" } } } ] } } } ] }, "SubscriptionExpiredEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "payload": { "allOf": [ { "$ref": "#/components/schemas/SubscriptionEventPayload" }, { "type": "object", "properties": { "eventType": { "const": "subscription.expired" }, "reason": { "$ref": "#/components/schemas/ExpiryReason", "nullable": true, "description": "Why the subscription expired. May be null for events that predate this field. The same value is also available as `payload.data.expiration.reason`.\n" } } } ] } } } ] }, "SubscriptionPaymentSucceededEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "payload": { "allOf": [ { "$ref": "#/components/schemas/PaymentEventPayload" }, { "type": "object", "properties": { "eventType": { "const": "subscription.payment.succeeded" } } } ] } } } ] }, "SubscriptionPaymentFailedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEnvelope" }, { "type": "object", "properties": { "payload": { "allOf": [ { "$ref": "#/components/schemas/PaymentEventPayload" }, { "type": "object", "properties": { "eventType": { "const": "subscription.payment.failed" } } } ] } } } ] }, "CustomerProfile": { "oneOf": [ { "$ref": "#/components/schemas/IndividualProfile" }, { "$ref": "#/components/schemas/CompanyProfile" }, { "$ref": "#/components/schemas/ReferenceProfile" } ], "discriminator": { "propertyName": "type", "mapping": { "individual": "#/components/schemas/IndividualProfile", "company": "#/components/schemas/CompanyProfile", "reference": "#/components/schemas/ReferenceProfile" } }, "description": "Optional customer profile, used to meet Travel Rule / AML obligations.\n`profileId` is returned as `Subscription.customerProfileId`; the rest\nof the profile is write-only and never returned by the API.\n\n**EU merchants:** merchants operating under the EU regulatory workflow\nmust supply a complete customer profile with every subscription, to meet\nTravel Rule / AML obligations. The profile must be an `individual` (with\n`firstName`, `lastName`, `dateOfBirth`, and a full address —\n`streetAddress`, `city`, `postalCode`, `country`) or a `company` (with\n`registeredName`, `registrationNumber`, and a full address); a\n`reference` profile is not accepted. A missing or incomplete profile is\nrejected with HTTP 422 and error code `CUSTOMER_PROFILE_REQUIRED`. For\nother merchants the profile remains optional.\n" }, "CustomerProfileType": { "type": "string", "enum": [ "individual", "company", "reference" ], "description": "Discriminator value for polymorphic CustomerProfile variants." }, "CustomerProfileBase": { "type": "object", "required": [ "type", "profileId" ], "properties": { "type": { "$ref": "#/components/schemas/CustomerProfileType" }, "profileId": { "type": "string", "maxLength": 128, "description": "Your customer id. Returned as `Subscription.customerProfileId` and accepted by the `customerProfileId` filter when listing subscriptions." }, "streetAddress": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "postalCode": { "type": "string", "maxLength": 64 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2." } } }, "IndividualProfile": { "allOf": [ { "$ref": "#/components/schemas/CustomerProfileBase" }, { "type": "object", "properties": { "firstName": { "type": "string", "maxLength": 255 }, "lastName": { "type": "string", "maxLength": 255 }, "dateOfBirth": { "type": "string", "format": "date" }, "placeOfBirth": { "type": "string", "maxLength": 255 } } } ] }, "CompanyProfile": { "allOf": [ { "$ref": "#/components/schemas/CustomerProfileBase" }, { "type": "object", "properties": { "registeredName": { "type": "string", "maxLength": 255 }, "registrationNumber": { "type": "string", "maxLength": 255 } } } ] }, "ReferenceProfile": { "allOf": [ { "$ref": "#/components/schemas/CustomerProfileBase" } ] }, "ErrorResponse": { "type": "object", "description": "Canonical error envelope. Every non-2xx response uses this shape.", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code.", "example": "SUBSCRIPTION_NOT_FOUND" }, "message": { "type": "string", "description": "Human-readable summary." }, "details": { "type": "object", "additionalProperties": true, "description": "Optional error-specific context." } } } }, "responses": { "BadRequest": { "description": "Request is malformed or violates a validation rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Caller is unauthenticated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "Caller is authenticated but not authorized for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalServerError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnprocessableEntity": { "description": "Request parsed but violates a business rule or invariant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "Request conflicts with the current resource state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }