Recurring billing with Subscriptions

A subscription binds one or more recurring-price items to a customer and bills them automatically on each renewal date. Your backend creates the subscription; Ionic creates each subsequent invoice. On Node, npm install @ionicfi/sdk gives you typed calls for every request below; the server SDK guide has details. Each example also shows raw curl.

Lifecycle

Create the subscription

Your server calls POST /v1/subscriptions with a customer ID, one or more recurring-price items, and a collection method. An initial invoice is issued immediately unless the subscription opens with a trial.

Trial period (optional)

When trial_end is set, the subscription starts in trialing and no invoice is issued. At trial_end, Ionic charges default_payment_method and advances the status to active.

Automatic renewals

At each current_period_end, Ionic issues a renewal invoice and advances the period. A failed renewal moves the subscription to past_due; exhausting the retry period moves it to unpaid.

Gate access with entitlement

Call GET /v1/subscriptions/{id}/entitlement on each access check. Listen for subscription.updated and subscription.canceled webhooks to react to state changes.

Create a subscription

import { Ionic } from "@ionicfi/sdk";

const ionic = new Ionic({ token: process.env.IONIC_SECRET_KEY });

const subscription = await ionic.subscriptions.create({
  "Idempotency-Key": "sub_create_cus_123",
  customer: "cus_000000000000000000000000",
  items: [
    {
      price: "price_000000000000000000000001",
      quantity: 1,
    },
  ],
  collection_method: "charge_automatically",
  default_payment_method: "pm_000000000000000000000000",
  metadata: {
    plan: "pro",
  },
});

curl https://api.ionicfi.com/v1/subscriptions \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: sub_create_cus_123" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_000000000000000000000000",
    "items": [
      {
        "price": "price_000000000000000000000001",
        "quantity": 1
      }
    ],
    "collection_method": "charge_automatically",
    "default_payment_method": "pm_000000000000000000000000",
    "metadata": {
      "plan": "pro"
    }
  }'

Request fields

Field	Type	Notes
`customer`	string	Required. Customer ID (`cus_…`).
`items`	array	Required. One or more price items. All items must share one currency and one billing cadence.
`collection_method`	string	Required. `charge_automatically` or `send_invoice`.
`default_payment_method`	string	Payment method ID (`pm_…`). Required for `charge_automatically` subscriptions that start with a trial.
`trial_start`	integer	Unix epoch seconds. Start of the trial. Defaults to creation time when `trial_end` is set.
`trial_end`	integer	Unix epoch seconds. End of the trial. No invoice is issued while `status` is `trialing`.
`metadata`	object	Key-value pairs stored on the subscription.

Item fields

Field	Type	Notes
`price`	string	Required. Recurring price ID (`price_…`).
`quantity`	integer	Required. Must be at least 1.
`id`	string	Subscription item ID (`si_…`). Provide when updating an existing item in place via `POST /{id}/items`.
`metadata`	object	Key-value pairs stored on the item.

For a charge_automatically subscription with a trial, provide default_payment_method at creation. If it is absent when the trial ends, the renewal invoice cannot be collected automatically.

The billing cycle

Each subscription exposes these period fields on the response object:

Field	Type	Notes
`current_period_start`	integer	Unix epoch seconds. Start of the current billing period.
`current_period_end`	integer	Unix epoch seconds. End of the current billing period. Renewal occurs here.
`billing_cycle_anchor`	integer	Unix epoch seconds. Reference point used to compute all period boundaries.
`trial_start`	integer	Unix epoch seconds. Null when no trial.
`trial_end`	integer	Unix epoch seconds. Null when no trial. Automatic billing begins at this time.

Status values

Status	Meaning
`incomplete`	Created; initial invoice not yet paid.
`trialing`	In free trial; no invoice issued yet.
`active`	Most recent invoice paid; in good standing.
`past_due`	Most recent renewal failed; in dunning.
`unpaid`	Dunning exhausted; service stopped. Terminal.
`canceled`	Terminated immediately or at period end. Terminal.

Cancel a subscription

Pass at_period_end: true to let the current period run out before canceling. Omit the field or pass false for an immediate cancellation.

const canceled = await ionic.subscriptions.cancel({
  id: "sub_000000000000000000000000",
  "Idempotency-Key": "cancel_sub_000000000000000000000000",
  at_period_end: true,
});

curl -X POST https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000/cancel \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: cancel_sub_000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "at_period_end": true
  }'

An immediate cancellation transitions the subscription to canceled. A period-end cancellation sets cancel_at_period_end: true on the subscription; the status remains unchanged until the period ends, when the subscription is canceled automatically.

A period-end cancellation fires subscription.updated, not subscription.canceled. Do not revoke access when cancel_at_period_end flips to true. Revoke access only when you receive subscription.canceled.

Resume a scheduled cancellation

Reverses a period-end cancellation that has not yet taken effect. Only valid when cancel_at_period_end is true.

const resumed = await ionic.subscriptions.resume({
  id: "sub_000000000000000000000000",
  "Idempotency-Key": "resume_sub_000000000000000000000000",
});

curl -X POST https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000/resume \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: resume_sub_000000000000000000000000"

Update items

Replaces the subscription’s billed items. Items with a known id (si_…) are updated in place; items without an id are added as new items. All items must share the subscription’s existing currency and billing cadence.

const withUpdatedItems = await ionic.subscriptions.updateItems({
  id: "sub_000000000000000000000000",
  "Idempotency-Key": "items_sub_000000000000000000000000_v2",
  items: [
    {
      id: "si_000000000000000000000000",
      price: "price_000000000000000000000001",
      quantity: 2,
    },
    {
      price: "price_000000000000000000000002",
      quantity: 1,
    },
  ],
});

curl -X POST https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000/items \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: items_sub_000000000000000000000000_v2" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "id": "si_000000000000000000000000",
        "price": "price_000000000000000000000001",
        "quantity": 2
      },
      {
        "price": "price_000000000000000000000002",
        "quantity": 1
      }
    ]
  }'

Update collection method

const withNewCollectionMethod = await ionic.subscriptions.updateCollectionMethod({
  id: "sub_000000000000000000000000",
  "Idempotency-Key": "collmethod_sub_000000000000000000000000",
  collection_method: "send_invoice",
});

curl -X POST https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000/collection_method \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: collmethod_sub_000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_method": "send_invoice"
  }'

Update default payment method

Pass null for default_payment_method to clear it.

const withNewDefaultPaymentMethod = await ionic.subscriptions.updateDefaultPaymentMethod({
  id: "sub_000000000000000000000000",
  "Idempotency-Key": "pm_sub_000000000000000000000000",
  default_payment_method: "pm_000000000000000000000001",
});

curl -X POST https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000/default_payment_method \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: pm_sub_000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "default_payment_method": "pm_000000000000000000000001"
  }'

Update metadata

Replaces the metadata map entirely. Keys absent from the request are removed.

const withNewMetadata = await ionic.subscriptions.updateMetadata({
  id: "sub_000000000000000000000000",
  "Idempotency-Key": "meta_sub_000000000000000000000000",
  metadata: {
    plan: "pro",
    seat_count: "5",
  },
});

curl -X POST https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000/metadata \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: meta_sub_000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "plan": "pro",
      "seat_count": "5"
    }
  }'

Check entitlement

Call the entitlement endpoint to check whether the subscription currently includes access. Use entitled as the gate.

const entitlement = await ionic.subscriptions.checkEntitlement({
  id: "sub_000000000000000000000000",
});

curl https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000/entitlement \
  -H "Authorization: Bearer sk_v1_test_..."

{
  "entitled": true,
  "reason": "Subscription is active.",
  "access_until": "2026-08-01T00:00:00Z"
}

Gate access on entitled, not on access_until. The access_until timestamp is informational — it can be null or in the past while entitled is true, for example during a dunning retry or when a renewal sweep is pending.

Retrieve and list

const subscription = await ionic.subscriptions.retrieve({
  id: "sub_000000000000000000000000",
});

const subscriptions = await ionic.subscriptions.list({
  customer: "cus_000000000000000000000000",
  status: "active",
  limit: 20,
});

curl https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000 \
  -H "Authorization: Bearer sk_v1_test_..."

curl "https://api.ionicfi.com/v1/subscriptions?customer=cus_000000000000000000000000&status=active&limit=20" \
  -H "Authorization: Bearer sk_v1_test_..."

The list endpoint accepts customer, status, limit (default 20, max 100), and offset.

Webhooks

Event	When it fires
`subscription.created`	Once, when the subscription is first created.
`subscription.updated`	Any state change: status transition, item update, period advance, or `cancel_at_period_end` flip.
`subscription.canceled`	When the subscription reaches a terminal `canceled` state — immediately or at period end.

Read data.object on every event for the full subscription snapshot. Do not infer access from the event type alone.

A period-end cancellation fires subscription.updated with cancel_at_period_end: true. The subscription.canceled event arrives later, when the period ends. Keep the subscriber’s access open between these two events.

See Webhook events for the full event catalog and delivery guarantees.

Subscriptions for connected merchants

A platform creates and manages subscriptions for a connected merchant with its platform secret key. Send the merchant ID in the Ionic-Account header, or pass the account request option to the server SDK (@ionicfi/sdk 0.4.4 or later). The subscription belongs to that merchant.

const subscription = await ionic.subscriptions.create(
  {
    "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:subscription:cus_123",
    customer: "cus_000000000000000000000000",
    items: [{ price: "price_000000000000000000000001", quantity: 1 }],
    collection_method: "charge_automatically",
    default_payment_method: "pm_000000000000000000000000",
  },
  { account: "mer_BBBBBBBBBBBBBB" },
);

The platform key and the merchant’s connection must both grant subscriptions:write. To create the plan’s product and price for the merchant, both also need products:write.
The customer, prices, and payment method must belong to the selected merchant in the same mode. An object from another merchant returns 404.
Creating, resuming, and changing items, collection method, or default payment method need the merchant to be ready to take payments in that mode. Until then they return 403 PAYMENTS_NOT_ENABLED (403 LIVE_PAYMENTS_NOT_ENABLED in live mode), or 422 account_not_yet_active while the merchant’s payment account is still being set up. Cancel and metadata updates don’t need payments to be ready, so you can stop billing after a merchant’s payments are disabled. Every write returns 403 MERCHANT_INACTIVE while the merchant is not active.
The subscription issues and collects its own invoices, including renewals. Your platform reads them with invoices:read and needs no invoice write permission. See Connect billing.
Your platform webhook endpoint receives the merchant’s subscription events when the connection grants subscriptions:read. Each event names the merchant in event.account.

Operational guidance

Always send an Idempotency-Key on write requests. Network retries can otherwise create duplicate subscriptions, double item updates, or duplicate cancellations.
A 409 Conflict response means the subscription was modified concurrently. Retry the same request with the same Idempotency-Key.
For charge_automatically subscriptions, keep default_payment_method current. An expired card causes the renewal to fail and moves the subscription to past_due.
Store your plan IDs, seat counts, or feature flags in metadata. Update metadata from your application layer; do not derive access decisions from it.
Use the entitlement endpoint for runtime access checks. Use webhooks to react to state changes asynchronously in your provisioning and access-control systems.

What’s next

Test a subscription lifecycle

Advance test time to verify trials, renewals, retries, and cancellations.

Review renewal invoices

Follow how each period’s invoice is issued and collected.

Read billing for connected accounts

Read a connected account’s subscriptions and gate access with entitlement.

​Lifecycle

​Create a subscription

​Request fields

​Item fields

​The billing cycle

​Status values

​Cancel a subscription

​Resume a scheduled cancellation

​Update items

​Update collection method

​Update default payment method

​Update metadata

​Check entitlement

​Retrieve and list

​Webhooks

​Subscriptions for connected merchants

​Operational guidance

​What’s next

Test a subscription lifecycle

Review renewal invoices

Read billing for connected accounts

Lifecycle

Create a subscription

Request fields

Item fields

The billing cycle

Status values

Cancel a subscription

Resume a scheduled cancellation

Update items

Update collection method

Update default payment method

Update metadata

Check entitlement

Retrieve and list

Webhooks

Subscriptions for connected merchants

Operational guidance

What’s next