Error

A valid request URL is required to generate request examples

{
  "data": [
    {
      "id": "<string>",
      "object": "customer",
      "merchant_id": "<string>",
      "livemode": true,
      "test_clock": "<string>",
      "email": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "billing_address": {
        "line1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>",
        "line2": "<string>"
      },
      "shipping": {
        "name": "<string>",
        "phone": "<string>",
        "address": {
          "line1": "<string>",
          "city": "<string>",
          "state": "<string>",
          "postal_code": "<string>",
          "country": "<string>",
          "line2": "<string>"
        }
      },
      "creation_source": "api",
      "payment_settings": {
        "default_payment_method": "<string>"
      },
      "metadata": {},
      "deleted": true,
      "created_at": 123,
      "updated_at": 123,
      "summary": {
        "payment_count": 123,
        "succeeded_payment_count": 123,
        "failed_payment_count": 123,
        "refunded_payment_count": 123,
        "payment_methods_count": 123,
        "active_payment_methods_count": 123,
        "first_paid_at": 123,
        "last_paid_at": 123,
        "net_spend_by_currency": {},
        "gross_spend_by_currency": {},
        "refunded_by_currency": {},
        "largest_payment_by_currency": {}
      },
      "default_payment_method": {
        "id": "<string>",
        "type": "<string>",
        "usage": "<string>",
        "status": "<string>",
        "brand": "<string>",
        "last4": "<string>",
        "exp_month": 123,
        "exp_year": 123,
        "bin": "<string>",
        "funding_type": "<string>",
        "issuer": "<string>",
        "country": "<string>",
        "fingerprint": "<string>",
        "billing_name": "<string>",
        "billing_email": "<string>",
        "billing_phone": "<string>",
        "billing_address": {
          "line1": "<string>",
          "line2": "<string>",
          "city": "<string>",
          "state": "<string>",
          "postal_code": "<string>",
          "country": "<string>"
        },
        "chargeable": true,
        "created_at": 123,
        "updated_at": 123
      },
      "last_payment": {
        "id": "<string>",
        "description": "<string>",
        "amount": 123,
        "currency": "<string>",
        "status": "<string>",
        "charge_id": "<string>",
        "payment_method_id": "<string>",
        "card_brand": "<string>",
        "last4": "<string>",
        "created_at": 123
      },
      "payment_methods": [
        {
          "id": "<string>",
          "type": "<string>",
          "usage": "<string>",
          "status": "<string>",
          "brand": "<string>",
          "last4": "<string>",
          "exp_month": 123,
          "exp_year": 123,
          "bin": "<string>",
          "funding_type": "<string>",
          "issuer": "<string>",
          "country": "<string>",
          "fingerprint": "<string>",
          "billing_name": "<string>",
          "billing_email": "<string>",
          "billing_phone": "<string>",
          "billing_address": {
            "line1": "<string>",
            "line2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "postal_code": "<string>",
            "country": "<string>"
          },
          "chargeable": true,
          "created_at": 123,
          "updated_at": 123
        }
      ],
      "recent_payments": [
        {
          "id": "<string>",
          "description": "<string>",
          "amount": 123,
          "currency": "<string>",
          "status": "<string>",
          "charge_id": "<string>",
          "payment_method_id": "<string>",
          "card_brand": "<string>",
          "last4": "<string>",
          "created_at": 123
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "invalid request body"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Customers

List customers

Returns a paginated list of customers, newest first. Each item includes a lifetime payment summary, the customer’s default payment method, and their most recent payment. The payment_methods and recent_payments arrays are not returned for list items; use the retrieve endpoint to fetch those.

Supports offset pagination (limit + offset) and cursor pagination (starting_after). 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. The two forms cannot be combined in one request.

GET

customers

Error

A valid request URL is required to generate request examples

{
  "data": [
    {
      "id": "<string>",
      "object": "customer",
      "merchant_id": "<string>",
      "livemode": true,
      "test_clock": "<string>",
      "email": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "phone": "<string>",
      "billing_address": {
        "line1": "<string>",
        "city": "<string>",
        "state": "<string>",
        "postal_code": "<string>",
        "country": "<string>",
        "line2": "<string>"
      },
      "shipping": {
        "name": "<string>",
        "phone": "<string>",
        "address": {
          "line1": "<string>",
          "city": "<string>",
          "state": "<string>",
          "postal_code": "<string>",
          "country": "<string>",
          "line2": "<string>"
        }
      },
      "creation_source": "api",
      "payment_settings": {
        "default_payment_method": "<string>"
      },
      "metadata": {},
      "deleted": true,
      "created_at": 123,
      "updated_at": 123,
      "summary": {
        "payment_count": 123,
        "succeeded_payment_count": 123,
        "failed_payment_count": 123,
        "refunded_payment_count": 123,
        "payment_methods_count": 123,
        "active_payment_methods_count": 123,
        "first_paid_at": 123,
        "last_paid_at": 123,
        "net_spend_by_currency": {},
        "gross_spend_by_currency": {},
        "refunded_by_currency": {},
        "largest_payment_by_currency": {}
      },
      "default_payment_method": {
        "id": "<string>",
        "type": "<string>",
        "usage": "<string>",
        "status": "<string>",
        "brand": "<string>",
        "last4": "<string>",
        "exp_month": 123,
        "exp_year": 123,
        "bin": "<string>",
        "funding_type": "<string>",
        "issuer": "<string>",
        "country": "<string>",
        "fingerprint": "<string>",
        "billing_name": "<string>",
        "billing_email": "<string>",
        "billing_phone": "<string>",
        "billing_address": {
          "line1": "<string>",
          "line2": "<string>",
          "city": "<string>",
          "state": "<string>",
          "postal_code": "<string>",
          "country": "<string>"
        },
        "chargeable": true,
        "created_at": 123,
        "updated_at": 123
      },
      "last_payment": {
        "id": "<string>",
        "description": "<string>",
        "amount": 123,
        "currency": "<string>",
        "status": "<string>",
        "charge_id": "<string>",
        "payment_method_id": "<string>",
        "card_brand": "<string>",
        "last4": "<string>",
        "created_at": 123
      },
      "payment_methods": [
        {
          "id": "<string>",
          "type": "<string>",
          "usage": "<string>",
          "status": "<string>",
          "brand": "<string>",
          "last4": "<string>",
          "exp_month": 123,
          "exp_year": 123,
          "bin": "<string>",
          "funding_type": "<string>",
          "issuer": "<string>",
          "country": "<string>",
          "fingerprint": "<string>",
          "billing_name": "<string>",
          "billing_email": "<string>",
          "billing_phone": "<string>",
          "billing_address": {
            "line1": "<string>",
            "line2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "postal_code": "<string>",
            "country": "<string>"
          },
          "chargeable": true,
          "created_at": 123,
          "updated_at": 123
        }
      ],
      "recent_payments": [
        {
          "id": "<string>",
          "description": "<string>",
          "amount": 123,
          "currency": "<string>",
          "status": "<string>",
          "charge_id": "<string>",
          "payment_method_id": "<string>",
          "card_brand": "<string>",
          "last4": "<string>",
          "created_at": 123
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "<string>"
}

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "invalid request body"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Ionic-Account

string

Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.

Pattern: ^mer_[0-9A-Za-z]{14}$

Query Parameters

limit

integer

default:20

Page size (default 20, max 100).

Required range: 1 <= x <= 100

offset

integer

default:0

Number of records to skip.

Required range: x >= 0

string

Filter customers by email or name prefix.

created_gte

string

Return customers created at or after this time (RFC 3339).

created_lte

string

Return customers created at or before this time (RFC 3339).

starting_after

string

Cursor: a customer id (typically the previous response's next_cursor). Returns results strictly after it, newest first. Cannot be combined with offset.

include_deleted

boolean

default:false

When true, soft-deleted customers are included in results.

Response

A paginated list of customers, newest first.

data

object[]

required

The customers on this page.

Show child attributes

has_more

boolean

required

True when more records exist beyond this page.

next_cursor

string

Present when has_more is true: the last returned customer's id. Pass it as starting_after on the next request.

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

List customers

Authorizations

Headers

Query Parameters

Response