Subscriptions and invoices for connected accounts

Your platform can run a connected account’s billing with its own platform key. It creates the plan’s product and price, subscribes customers, invoices one-off charges, and credits paid invoices. It also reads that billing data, gates access with subscription entitlement, and reacts to billing events. Everything your platform creates belongs to the connected account. The merchant can also bill in the Dashboard or with its own keys, and those records appear to your platform the same way.

Before you begin

A platform secret key from Connect → API keys, kept on your server.
An active connection in the same mode. The platform key and the merchant’s connection both grant each permission an operation needs:

Operation	Permission
Create and update products and prices	`products:write`
Create the customer you bill	`customers:write`
Save the customer’s card for automatic collection	`setup_intents:write`
Create, change, cancel, and resume subscriptions; create and advance test clocks; arm a subscription’s next collection outcome	`subscriptions:write`
Create and change invoices and invoice items; finalize, collect, void, or write off an invoice	`invoices:write`
Issue, preview, and void credit notes	`credit_notes:write`
List and retrieve subscriptions, check entitlement, and retrieve test clocks	`subscriptions:read`
List and retrieve invoices, list their payment attempts, download their PDFs, and retrieve invoice items	`invoices:read`
List and retrieve credit notes, and download their PDFs	`credit_notes:read`

Bill a connected account

Pass the merchant ID as the server SDK’s account option, or send it in the Ionic-Account header. Every object you create belongs to that merchant, and every customer, price, payment method, and invoice you name must belong to it in the same mode. An object from another account returns 404.

Every write returns 403 MERCHANT_INACTIVE while the merchant is not active.
Subscription writes that start or change a charge (create, resume, items, collection method, and default payment method), collecting an invoice with POST /v1/invoices/{id}/pay, and changing an invoice’s card also 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 or 422 account_activation_failed while the merchant’s payment account is being set up.
Canceling a subscription, voiding an invoice, and issuing a credit note work even after the merchant’s payments are disabled.
Subscriptions and invoices your platform creates record your platform and the connection that created them.

The account option on products, prices, subscriptions, invoices, invoice items, and credit notes needs @ionicfi/sdk 0.4.4 or later. On an earlier version, pass { headers: { "Ionic-Account": "mer_..." } } instead.

const account = "mer_BBBBBBBBBBBBBB";

const product = await ionic.catalog.products.create(
  { name: "Pro plan", "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:product:pro" },
  { account },
);

const price = await ionic.catalog.prices.create(
  {
    product_id: product.id,
    unit_amount: 2900,
    currency: "usd",
    type: "recurring",
    recurring: { interval: "month", interval_count: 1, usage_type: "licensed" },
    "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:price:pro-monthly",
  },
  { account },
);

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

charge_automatically needs a card saved for that customer with a SetupIntent, which records the mandate renewals rely on. See Save cards for connected accounts. With send_invoice, the buyer pays each invoice on its hosted invoice page instead. The subscription issues and collects its own invoices: you need invoices:read to see them, and no invoice write permission.

Change or cancel a subscription

Change	Endpoint
Replace the billed items	Update items
Switch between `charge_automatically` and `send_invoice`	Update collection method
Charge a different saved card	Update default payment method
Store your plan or seat IDs	Update metadata
End now or at period end	Cancel
Undo a scheduled period-end cancellation	Resume

Invoice a one-off charge

This records a pending charge, creates an invoice that picks it up, and finalizes the invoice so the merchant’s customer can pay it on its hosted invoice page:

const account = "mer_BBBBBBBBBBBBBB";

await ionic.invoices.items.create(
  {
    customer: "cus_BBBBBBBBBBBBBB",
    description: "Setup fee",
    quantity: 1,
    unit_amount: 1500,
    currency: "usd",
    "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:item:order-123",
  },
  { account },
);

const invoice = await ionic.invoices.create(
  {
    customer: "cus_BBBBBBBBBBBBBB",
    currency: "usd",
    collection_method: "send_invoice",
    "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:invoice:order-123",
  },
  { account },
);

await ionic.invoices.finalize(
  { id: invoice.id, tax: 0, "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:finalize:order-123" },
  { account },
);

To charge a saved card instead, create the invoice with charge_automatically and the card’s payment_method_id, then collect it with ionic.invoices.pay.

Credit a paid invoice

await ionic.creditNotes.create(
  {
    "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:credit:order-123",
    body: { invoice: "inv_000000000000000000000000", amount: 500, out_of_band_amount: 500, reason: "adjustment" },
  },
  { account: "mer_BBBBBBBBBBBBBB" },
);

A credit note moves no money. It records a refund you already created, or an amount settled outside Ionic (out_of_band_amount). When you refund an invoice’s payment, Ionic issues the matching credit note for you. See Subscriptions for connected merchants, Invoices for connected merchants, and Credit notes for connected merchants for the details of each.

Gate access with entitlement

Check entitlement on each access decision. Use entitled as the gate.

curl https://api.ionicfi.com/v1/subscriptions/sub_000000000000000000000000/entitlement \
  -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID"

See Check entitlement for the response fields.

Read billing records

Send Ionic-Account on each read to select the merchant.

Resource	Endpoints
Subscriptions	List, retrieve, check entitlement
Invoices	List, retrieve, list payment attempts, download PDF, retrieve an invoice item
Credit notes	List, retrieve, download PDF

To create and change these records, see Bill a connected account.

React to billing events

A platform webhook endpoint receives a merchant’s billing events when that merchant’s connection grants the matching read permission:

Events	Connection permission
`subscription.created`, `subscription.updated`, `subscription.canceled`	`subscriptions:read`
`invoice.paid`, `invoice.payment_failed`, `invoice.marked_uncollectible`	`invoices:read`
`credit_note.created`, `credit_note.voided`	`credit_notes:read`

The event’s account field names the merchant. A scheduled cancel-at-period-end arrives as subscription.updated, so keep access until the subscription is canceled. See Webhooks for platforms.

Test billing with clocks

Test clock operations accept Ionic-Account, so your platform can rehearse a connected test merchant’s renewals, retries, and cancellations. The clock, customer, and subscription must all belong to the selected merchant, and a clock is advanced only while operating that merchant.

curl https://api.ionicfi.com/v1/test_clocks \
  -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
  -H "Ionic-Account: $CONNECTED_ACCOUNT_ID" \
  -H "Idempotency-Key: merchant-clock-renewal-suite" \
  -H "Content-Type: application/json" \
  -d '{
    "frozen_time": 1788091200
  }'

To attach a customer, advance time, and arm collection outcomes, follow Test subscription lifecycles with clocks.

What’s next

Handle webhooks

Receive every connected account’s events on one endpoint and match each to its connected account.

Test billing with clocks

Advance test time through a connected test account’s renewals and retries.

Recurring billing with Subscriptions: the subscription lifecycle.
Invoices: drafting, finalizing, and collecting invoices.
Credit notes: crediting a paid invoice.

Connect

Onboard merchants

Set up your platform

Accept payments

After the payment

Launch

Subscriptions and invoices for connected accounts

Before you begin

Bill a connected account

Change or cancel a subscription

Invoice a one-off charge

Credit a paid invoice

Gate access with entitlement

Read billing records

React to billing events

Test billing with clocks

What’s next

Handle webhooks

Test billing with clocks

​Before you begin

​Bill a connected account

​Create a plan and subscribe a customer

​Change or cancel a subscription

​Invoice a one-off charge

​Credit a paid invoice

​Gate access with entitlement

​Read billing records

​React to billing events

​Test billing with clocks

​What’s next

Handle webhooks

Test billing with clocks

Before you begin

Bill a connected account

Create a plan and subscribe a customer

Change or cancel a subscription

Invoice a one-off charge

Credit a paid invoice

Gate access with entitlement

Read billing records

React to billing events

Test billing with clocks

What’s next