Retrieve a customer

Error

A valid request URL is required to generate request examples

{
  "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
    }
  ]
}

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

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

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

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "customer not found"
  }
}

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

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

GET

customers

{id}

Error

A valid request URL is required to generate request examples

{
  "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
    }
  ]
}

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

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

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

{
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "customer not found"
  }
}

{
  "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}$

Path Parameters

string

required

The customer id (cus_…).

Query Parameters

section_size

integer

Maximum items to return in payment_methods and recent_payments (1–100). Omit to return all.

Required range: 1 <= x <= 100

Response

The customer with full dashboard detail.

A customer enriched with payment summary data. The list endpoint returns summary, default_payment_method, and last_payment for each item. The retrieve endpoint additionally returns the full payment_methods and recent_payments arrays.

string

required

Unique customer identifier (cus_…).

object

enum<string>

required

Available options:

customer

merchant_id

string

required

ID of the account that owns the customer (mer_…).

livemode

boolean

required

Whether this customer was created with a live (true) or test (false) key.

test_clock

string | null

required

The immutable logical billing clock attached at creation; null when this customer uses wall-clock time.

string

required

Customer email address.

first_name

string

required

Empty string when not set.

last_name

string

required

Empty string when not set.

phone

string

required

Empty string when not set.

billing_address

object | null

required

Billing address; null when not set.

Show child attributes

shipping

object | null

required

Shipping details; null when not set.

Show child attributes

creation_source

enum<string>

required

How the customer was created (for example api).

Available options:

api,

checkout,

import,

dashboard,

platform

payment_settings

object

required

Payment configuration stored for the customer.

Show child attributes

metadata

object

required

Custom key-value pairs for your use.

Show child attributes

deleted

boolean

required

True when the customer has been soft-deleted.

created_at

integer

required

Unix epoch seconds.

updated_at

integer

required

Unix epoch seconds when the customer was last updated.

summary

object

Lifetime payment statistics for this customer.

Show child attributes

default_payment_method

object

The customer's default payment method; absent when none is set.

Show child attributes

last_payment

object

The customer's most recent payment; absent when there are none.

Show child attributes

payment_methods

object[]

All payment methods on file. Only returned by the retrieve endpoint.

Show child attributes

recent_payments

object[]

Recent payments. Only returned by the retrieve endpoint.

Show child attributes

Fundamentals

Payments

Checkout

In-person payments

Customers and catalog

Connect

Billing

Webhooks

Authorizations

Headers

Path Parameters

Query Parameters

Response