> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscriptions and invoices for connected accounts

> Bill a connected account's customers with plans, subscriptions, invoices, and credit notes, gate access with entitlement, and test billing with clocks.

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](/guides/authentication) 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.

### Create a plan and subscribe a customer

```ts theme={null}
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](/guides/connect-save-cards). 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](/api-reference/subscriptions/update-subscription-items) |
| Switch between `charge_automatically` and `send_invoice` | [Update collection method](/api-reference/subscriptions/update-collection-method) |
| Charge a different saved card | [Update default payment method](/api-reference/subscriptions/update-default-payment-method) |
| Store your plan or seat IDs | [Update metadata](/api-reference/subscriptions/update-metadata) |
| End now or at period end | [Cancel](/api-reference/subscriptions/cancel-a-subscription) |
| Undo a scheduled period-end cancellation | [Resume](/api-reference/subscriptions/resume-a-subscription) |

### 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:

```ts theme={null}
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

```ts theme={null}
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](/guides/subscriptions#subscriptions-for-connected-merchants),
[Invoices for connected merchants](/guides/invoices#invoices-for-connected-merchants),
and [Credit notes for connected merchants](/guides/credit-notes#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.

```bash theme={null}
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](/guides/subscriptions#check-entitlement) for the
response fields.

## Read billing records

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

| Resource | Endpoints |
| - | - |
| Subscriptions | [List](/api-reference/subscriptions/list-subscriptions), [retrieve](/api-reference/subscriptions/retrieve-a-subscription), [check entitlement](/api-reference/subscriptions/check-subscription-entitlement) |
| Invoices | [List](/api-reference/invoices/list-invoices), [retrieve](/api-reference/invoices/retrieve-an-invoice), [list payment attempts](/api-reference/invoices/list-an-invoices-payment-attempts), [download PDF](/api-reference/invoices/download-an-invoice-pdf), [retrieve an invoice item](/api-reference/invoice-items/retrieve-an-invoice-item) |
| Credit notes | [List](/api-reference/credit-notes/list-credit-notes), [retrieve](/api-reference/credit-notes/retrieve-a-credit-note), [download PDF](/api-reference/credit-notes/download-a-credit-note-as-pdf) |

To create and change these records, see [Bill a connected account](#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](/guides/connect-webhooks).

## 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.

```bash theme={null}
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](/guides/test-clocks).

## What's next

<CardGroup cols={2}>
  <Card title="Handle webhooks" icon="tower-broadcast" href="/guides/connect-webhooks">
    Receive every connected account's events on one endpoint and match each to its connected account.
  </Card>

  <Card title="Test billing with clocks" icon="clock-rotate-left" href="/guides/test-clocks">
    Advance test time through a connected test account's renewals and retries.
  </Card>
</CardGroup>

* [Recurring billing with Subscriptions](/guides/subscriptions): the
  subscription lifecycle.
* [Invoices](/guides/invoices): drafting, finalizing, and collecting invoices.
* [Credit notes](/guides/credit-notes): crediting a paid invoice.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.