Guides
Sign In to Dashboard

Creating a Subscription

When a customer wants to subscribe, you create a subscription for them on one of your plans.

Step 1 — Create the subscription

POST /api/v3/subscriptions

Identify the subscriber by email. You can also attach a customerProfile. Its profileId comes back as customerProfileId, so you can match webhooks and filter lists against your own records.

curl -X POST https://api.confirmo.com/api/v3/subscriptions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "planId": "9f3a6e2c-1b7d-4c5e-9a0f-2d8b4e6c1a3f",
    "subscriber": { "email": "[email protected]" },
    "customerProfile": {
      "type": "individual",
      "profileId": "user-8421",
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1990-04-21",
      "streetAddress": "Musterstrasse 12",
      "city": "Mannheim",
      "postalCode": "68159",
      "country": "DE"
    },
    "notifyUrl": "https://your-platform.com/webhooks/subscriptions",
    "returnUrl": "https://your-platform.com/account/billing"
  }'

Request body parameters:

FieldRequiredDescription
planIdYesThe plan this subscription bills against.
subscriber.emailYesThe subscriber's email address.
amountConditionalThe per-subscription amount (value only; the currency comes from the plan). Required for a VARIABLE plan, omit it for FIXED.
customerProfileConditionalTravel Rule information for the customer who owns this account. Mandatory for Merchants operating in the EU.
notifyUrlNoWhere Confirmo sends all lifecycle and payment events. We recommend always setting it.
returnUrlNoWhere the subscriber lands after checkout.
📘

About customerProfile

Confirmo uses it to meet Travel Rule obligations on the underlying transfers. It's never shown to the subscriber, and only profileId is returned to you. If you are a merchant operating in the EU, you must supply a complete profile on every subscription — otherwise the request is rejected with 422 CUSTOMER_PROFILE_REQUIRED.

The response includes a checkoutUrl (e.g. https://checkout.confirmo.com/s/...). The subscription sits in PENDING until the subscriber completes checkout.

Step 2 — Send the subscriber to checkout

Redirect the subscriber to the checkoutUrl, or send it to them by email or link. The checkout is a Confirmo-hosted page that shows the subscriber exactly what they're signing up for — the plan name, amount, and frequency — before they authorise anything.

💡

A suggested integration

Let the subscriber pick their plan on your own site, redirect them to the hosted checkoutUrl, and send them straight back to your returnUrl once checkout is done. This creates a continuous checkout experience for the subscriber.

Here's what the subscriber does:

  1. Opens your checkout link and reviews the plan summary.
  2. Connects a wallet via WalletConnect.
  3. Chooses a chain and stablecoin from the options you've enabled.
  4. Approves a spending allowance for the subscription. This is a single signature, and the checkout shows clearly what's being authorised, including any network fees.
  5. The first charge confirms, the subscription becomes ACTIVE, and they're redirected to your returnUrl. Future payments are collected automatically, with nothing more for the subscriber to do.
📘

Network fees

Subscribers never pay network fees on recurring charges. The only exception is a small one-time fee at subscription creation, when the chosen token needs an on-chain approval (USDT on all chains except Polygon, and any token on Solana). Every other token and chain combination uses a free gasless signature.

Step 3 — Provision access

When the first payment confirms, Confirmo sends subscription.activated to your notifyUrl. Provision access on that event — not when you create the subscription, since a PENDING subscription hasn't been paid for yet. See Subscription Webhooks.

⚠️

A PENDING subscription can time out

If the subscriber never finishes checkout, the subscription is auto-canceled with cancellation.reason: CHECKOUT_TIMEOUT. Wait for subscription.activated before you provision access.