Manage customers

A customer (cus_…) is a stable identity stored under your merchant account. Attach payment methods to a customer to enable off-session charges, subscriptions, and invoice delivery from a single profile. 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.

Customers on a Connect platform

A customer belongs to one merchant and one mode. To create or retrieve a connected account’s customer, send Ionic-Account with your platform secret key, or pass the server SDK’s { account: connectedMerchantId } request option. The platform key and the merchant’s connection both need customers:write to create and customers:read to retrieve. Store the merchant ID alongside the customer’s Ionic ID, and select the same merchant when accepting a payment or saving a card for that customer.

Create a customer

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

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

const customer = await ionic.customers.create({
  "Idempotency-Key": "create_cus_jane_doe",
  email: "[email protected]",
  first_name: "Jane",
  last_name: "Doe",
  phone: "+14155552671",
  billing_address: {
    line1: "123 Main St",
    city: "San Francisco",
    state: "CA",
    postal_code: "94103",
    country: "US",
  },
  metadata: {
    plan: "premium",
  },
});

curl https://api.ionicfi.com/v1/customers \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: create_cus_jane_doe" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+14155552671",
    "billing_address": {
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94103",
      "country": "US"
    },
    "metadata": {
      "plan": "premium"
    }
  }'

Email must be unique per merchant per mode. billing_address and shipping are optional and can be added or updated after creation.

Request fields

Field	Type	Notes
`email`	string	Required. Unique per merchant and mode.
`first_name`	string
`last_name`	string
`phone`	string
`billing_address`	object	Nullable. Requires `line1`, `city`, `state`, `postal_code`, and `country` when present.
`shipping`	object	Nullable. Requires `name` and `address`; `phone` is optional.
`creation_source`	string	Defaults to `api` when omitted.
`metadata`	object	Up to 50 key-value pairs. Keys ≤ 40 characters; values ≤ 500 characters.

Retrieve a customer

const retrieved = await ionic.customers.retrieve({ id: "cus_2pXqAbc" });

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

The retrieve endpoint returns the full customer object plus dashboard detail: all payment methods on file (payment_methods), recent payments (recent_payments), and a lifetime spend summary (summary) with counts and amounts by currency. Use the section_size query parameter to cap the number of items returned in payment_methods and recent_payments (1–100).

Update a customer

const updated = await ionic.customers.update({
  id: "cus_2pXqAbc",
  "Idempotency-Key": "update_cus_jane_smith",
  last_name: "Smith",
  phone: "+14155552672",
  metadata: {
    plan: "enterprise",
  },
});

curl -X POST https://api.ionicfi.com/v1/customers/cus_2pXqAbc \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: update_cus_jane_smith" \
  -H "Content-Type: application/json" \
  -d '{
    "last_name": "Smith",
    "phone": "+14155552672",
    "metadata": {
      "plan": "enterprise"
    }
  }'

All body fields are optional. Only fields present in the body are changed. Pass null for billing_address or shipping to remove the address. Updating a deleted customer returns 422.

Update fields

Field	Type	Notes
`email`	string	Must be unique per merchant and mode.
`first_name`	string
`last_name`	string
`phone`	string
`billing_address`	object or null	Pass `null` to clear the billing address.
`shipping`	object or null	Pass `null` to clear shipping details.
`metadata`	object	Replaces the customer’s metadata map in full.

List customers

const customers = await ionic.customers.list({ limit: 20 });

curl "https://api.ionicfi.com/v1/customers?limit=20" \
  -H "Authorization: Bearer sk_v1_test_..."

The list returns customers newest first. Each item includes a lifetime payment summary (summary), the customer’s default payment method, and their most recent payment. Full payment_methods and recent_payments arrays are not included in list items — use the retrieve endpoint for those. When has_more is true, the response includes next_cursor, the last returned customer’s id. Pass it as starting_after to fetch the next page; iterating the SDK’s list with for await does this automatically.

const nextPage = await ionic.customers.list({
  limit: 20,
  starting_after: "cus_2pXqAbc",
});

curl "https://api.ionicfi.com/v1/customers?limit=20&starting_after=cus_2pXqAbc" \
  -H "Authorization: Bearer sk_v1_test_..."

The list also accepts offset for offset-based pagination, search to filter by email or name prefix, created_gte and created_lte as RFC 3339 timestamps, and include_deleted=true to include soft-deleted records.

Attach a payment method

Attach a vaulted payment method to a customer to make it available for off-session charges and subscriptions.

await ionic.paymentMethods.attach({
  id: "pm_abc123",
  "Idempotency-Key": "attach_pm_abc123_cus_2pXqAbc",
  customer: "cus_2pXqAbc",
});

curl -X POST https://api.ionicfi.com/v1/payment_methods/pm_abc123/attach \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: attach_pm_abc123_cus_2pXqAbc" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_2pXqAbc"
  }'

The method must be active and not already attached to a customer. Attachment is write-once. The customer field on the payment method response reflects the attached customer id after the call. To make the attached method the customer’s default, set it explicitly. Pass null for default_payment_method to clear the default.

const withDefault = await ionic.customers.setDefaultPaymentMethod({
  id: "cus_2pXqAbc",
  "Idempotency-Key": "set_default_pm_abc123",
  default_payment_method: "pm_abc123",
});

curl -X POST https://api.ionicfi.com/v1/customers/cus_2pXqAbc/default_payment_method \
  -H "Authorization: Bearer sk_v1_test_..." \
  -H "Idempotency-Key: set_default_pm_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "default_payment_method": "pm_abc123"
  }'

The payment_settings.default_payment_method field on the customer response always reflects the current default. An invoice that collects automatically uses this method when it is created without one. A subscription that collects automatically sets its own default_payment_method.

Delete and restore

Deleting a customer is a soft-delete. The record is retained with deleted: true and cannot be modified until restored.

await ionic.customers.delete({ id: "cus_2pXqAbc" });

curl -X DELETE https://api.ionicfi.com/v1/customers/cus_2pXqAbc \
  -H "Authorization: Bearer sk_v1_test_..."

To undo the deletion:

await ionic.customers.restore({ id: "cus_2pXqAbc" });

curl -X POST https://api.ionicfi.com/v1/customers/cus_2pXqAbc/restore \
  -H "Authorization: Bearer sk_v1_test_..."

A customer.deleted webhook fires on deletion and a customer.restored webhook fires on restore. See webhook events for the full event catalog.

Pass include_deleted=true on the list endpoint to include soft-deleted customers in results. Deleted customers are excluded by default.

Operational guidance

Email must be unique per merchant per mode. A 409 with code CUSTOMER_EMAIL_ALREADY_EXISTS means a record already exists for that email. Use the search parameter on the list endpoint to locate it rather than creating a duplicate.
The metadata map is replaced in full on every update. Read the current values before writing if you need to preserve existing keys.
Attach a payment method before creating subscriptions or off-session payment intents. An operation that targets payment_settings.default_payment_method requires the attachment to be in place at the time of the call.
Soft-delete customers instead of abandoning records. Deleted customers retain their payment method and invoice history and can be restored when a customer reactivates.
Use the same Idempotency-Key on every retry for create, update, and attach calls. A unique key per logical operation prevents duplicates from network retries.

What’s next

Save a card for later

Collect a payment method with Ionic Blocks and attach it to a customer.

Start a subscription

Bill a customer automatically each period.