Error

A valid request URL is required to generate request examples

{
  "data": [
    {
      "id": "<string>",
      "object": "customer",
      "merchant_id": "<string>",
      "livemode": true,
      "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>"
  }
}

Customer endpoints

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,
      "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>.

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

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.

Start here

Checkout

Commerce

Checkout endpoints

Payment link endpoints

Catalog endpoints

Payments

Terminal locations

Terminal management

Terminal testing

Terminal payments

Invoices

Subscriptions

Setup intents

Credit notes

Webhook endpoints

Customer endpoints

API key endpoints

Payment method endpoints

List customers

Authorizations

Query Parameters

Response