> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.fluveo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.fluveo.com/_mcp/server.

# Customers

> **Status: `contracted_test`.** Customers are in the generated
> [API Reference](/api-reference); only `sk_test_*` mode is promised.

A Customer represents a buyer you bill more than once. Create, retrieve, update,
delete (not available for US Stripe Connect stores), and list are all served. Attach `metadata` (a flat string map) to carry your
own identifiers, and reference the customer from a [Checkout Session](/checkout/checkout-sessions)
or a [Payment Intent](/resources/payments).

## Payment methods on a customer

A customer's saved [payment methods](/resources/payment-methods) are read through
the one contracted customer-scoped route:

* `GET /v1/customers/{id}/payment_methods` — nested list

The top-level `/v1/payment_methods` namespace, including its filtered-list alias,
is unavailable for merchant-public keys. See
[Payment methods](/resources/payment-methods).

The full request/response shape is in the [API Reference](/api-reference).

## Hidden from the public API

Each item below is hidden because it does not follow the Stripe parity ADR (ADR 0004 as amended). The [hidden public `/v1` registry](https://github.com/fluveohq/fluveo/blob/main/tests/api-contract/stripe/hidden-public-v1.json) lists every
hidden item. Public `/v1` answers a hidden operation as an unknown URL, refuses a hidden request
parameter or value with Stripe's `invalid_request_error`, and omits a hidden response key.

* the query parameter `search` of `GET /v1/customers` (HIDE0-046)