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

# Customers for connected accounts

> Create a connected account's customers, list their saved cards, and choose the card used for future charges.

A connected account's customers belong to that account. Your platform creates
and manages them with the platform secret key and the merchant's ID, then uses
the same merchant when it saves a card or takes a payment for that customer.
Store the merchant ID next to each customer's Ionic ID in your own records.

Customer fields and operations are the same as in
[Manage customers](/guides/customers).

## 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, update, delete, and restore customers, and set a default payment method | `customers:write` |
| List and retrieve customers | `customers:read` |
| Attach and revoke payment methods | `payment_methods:write` |
| List and retrieve payment methods | `payment_methods:read` |

* `@ionicfi/sdk` 0.4.1 or later for the TypeScript examples,
  [installed from npm](/sdks/server#install).

## Create the merchant's customer

<CodeGroup>
  ```ts TypeScript theme={null}
  import { Ionic } from "@ionicfi/sdk";

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

  const customer = await ionic.customers.create(
    {
      "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:customer:patient_481",
      email: "jane@example.com",
      first_name: "Jane",
      last_name: "Doe",
      metadata: {
        patient_id: "patient_481",
      },
    },
    { account: "mer_BBBBBBBBBBBBBB" },
  );
  ```

  ```bash curl theme={null}
  curl https://api.ionicfi.com/v1/customers \
    -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
    -H "Ionic-Account: mer_BBBBBBBBBBBBBB" \
    -H "Idempotency-Key: merchant:mer_BBBBBBBBBBBBBB:customer:patient_481" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "metadata": {
        "patient_id": "patient_481"
      }
    }'
  ```
</CodeGroup>

The customer belongs to that merchant and mode. Select the same merchant on
every later request for this customer.

## Save a card for the customer

Save a card with the customer's consent using a SetupIntent and a Payment Block
on your page. See [Save cards for connected accounts](/guides/connect-save-cards).
To offer saving during a payment instead, see
[Accept payments for connected accounts](/guides/connect-blocks#save-a-card-during-the-payment).

## List the customer's saved cards

<CodeGroup>
  ```ts TypeScript theme={null}
  const methods = await ionic.paymentMethods.list(
    { customer: "cus_2pXqAbc" },
    { account: "mer_BBBBBBBBBBBBBB" },
  );
  ```

  ```bash curl theme={null}
  curl "https://api.ionicfi.com/v1/payment_methods?customer=cus_2pXqAbc" \
    -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
    -H "Ionic-Account: mer_BBBBBBBBBBBBBB"
  ```
</CodeGroup>

Your application builds any saved-card selection on top of this list.

## Choose the default card

An invoice that collects automatically charges the customer's default payment
method when the invoice names none. A subscription that collects automatically
sets its own `default_payment_method`.

<CodeGroup>
  ```ts TypeScript theme={null}
  const updated = await ionic.customers.setDefaultPaymentMethod(
    {
      id: "cus_2pXqAbc",
      "Idempotency-Key": "merchant:mer_BBBBBBBBBBBBBB:default_pm:pm_abc123",
      default_payment_method: "pm_abc123",
    },
    { account: "mer_BBBBBBBBBBBBBB" },
  );
  ```

  ```bash curl theme={null}
  curl -X POST https://api.ionicfi.com/v1/customers/cus_2pXqAbc/default_payment_method \
    -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
    -H "Ionic-Account: mer_BBBBBBBBBBBBBB" \
    -H "Idempotency-Key: merchant:mer_BBBBBBBBBBBBBB:default_pm:pm_abc123" \
    -H "Content-Type: application/json" \
    -d '{
      "default_payment_method": "pm_abc123"
    }'
  ```
</CodeGroup>

To stop a saved card from being used for new charges, revoke it with
[Revoke a payment method](/api-reference/payment-methods/revoke-a-payment-method).
A revocation requires a `reason`.

## Customer events

A platform webhook endpoint receives a merchant's `customer.created`,
`customer.updated`, `customer.deleted`, and `customer.restored` events when that
merchant's connection grants `customers:read`. The event's `account` field names
the merchant. See [Webhooks for platforms](/guides/connect-webhooks).

## Keep customer data with the correct merchant

| Value | Owner or scope |
| - | - |
| Customer and its saved payment methods | The selected connected account, in one mode. |
| PaymentIntents and SetupIntents for the customer | The same merchant and mode. |
| `metadata` | Your application's correlation data for that merchant's customer. |

## What's next

<CardGroup cols={2}>
  <Card title="Save cards" icon="id-card" href="/guides/connect-save-cards">
    Save a card to a connected account's customer with consent.
  </Card>

  <Card title="Read subscriptions and invoices" icon="file-invoice-dollar" href="/guides/connect-billing">
    Read a connected account's billing and gate access with entitlement.
  </Card>
</CardGroup>


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