FlintflintDocs

Customers

Customers are reusable buyer profiles: contact details, billing and shipping addresses, tax exemption, and your own cross-reference via merchant_customer_id. Attach a customer to orders, invoices, and subscriptions to keep purchase history connected to one identity, and to enable repeat billing with saved payment methods.

Email is the customer's stable identity: it must be unique per merchant and is immutable after creation. A customer can carry a default_payment_method_id, which marks the preferred saved payment method for flows like subscription billing.

Endpoints

List customers#

GET/v1/customers

Returns a paginated list of customers for the authenticated merchant.

Query parameters
page_sizeinteger

Page size, default 20, max 100.

page_tokenstring

Cursor returned by the previous list response.

querystring

Search across customer name, email, phone number, and external_reference_id.

external_reference_idstring

Exact-match filter on the caller-owned external reference ID.

emailstring

Exact-match filter on email address.

sort_byenum

Sort field.

nameemailcreated_atupdated_at
sort_directionenum

Sort direction.

ascdesc
created_afterstring

RFC3339 lower bound for created_at.

created_beforestring

RFC3339 upper bound for created_at.

updated_afterstring

RFC3339 lower bound for updated_at.

updated_beforestring

RFC3339 upper bound for updated_at.

Response · 200
dataarray of objectrequired
metaobject
next_page_tokenstring
request_idstring
Bash
curl https://api.withflintpay.com/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY"
JSON
{
  "data": [
    {
      "customer_id": "cus_123",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "metadata": {
        "crm_id": "crm_123"
      },
      "merchant_id": "mer_123",
      "billing_address": {
        "line1": "123 Main St",
        "country": "US",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001"
      },
      "phone": "+14155552671",
      "tax_exempt": true,
      "created_at": "2026-03-17T14:30:00Z",
      "updated_at": "2026-03-17T14:30:00Z"
    }
  ],
  "next_page_token": "Zm9yd2FyZC1vbmx5LW9wYXF1ZS1jdXJzb3I",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create customer#

POST/v1/customersIdempotent

Creates a customer for the authenticated merchant.

Request body
billing_addressobject
emailstringrequired
external_reference_idstring
internal_notestring
metadatamap of string
namestring
phonestring
shipping_addressobject
tax_exemptboolean
Response · 201
dataobjectrequired
metaobject
request_idstring
Bash
curl -X POST https://api.withflintpay.com/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "metadata": {
      "crm_id": "crm_123"
    },
    "billing_address": {
      "line1": "123 Main St",
      "country": "US",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001"
    }
  }'
JSON
{
  "data": {
    "customer_id": "cus_123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "metadata": {
      "crm_id": "crm_123"
    },
    "merchant_id": "mer_123",
    "billing_address": {
      "line1": "123 Main St",
      "country": "US",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001"
    },
    "phone": "+14155552671",
    "tax_exempt": true,
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Get customer#

GET/v1/customers/{customer_id}

Returns a single customer by ID.

Path parameters
customer_idstringrequired

Flint customer ID.

Query parameters
expandarray of enum

Supported expansions: default_payment_method. Expansion requires customers.customers.read plus payments.payment_methods.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Send repeated expand parameters as the canonical form, for example expand=default_payment_method&expand=default_payment_method. Comma-separated values, expand[]=default_payment_method, and numeric expand[0]=default_payment_method are accepted for common client compatibility.

default_payment_method
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl https://api.withflintpay.com/v1/customers/cus_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update customer#

PATCH/v1/customers/{customer_id}Idempotent

Applies a sparse update to a customer.

Path parameters
customer_idstringrequired

Flint customer ID.

Request body
billing_addressobject
external_reference_idstring
internal_notestring
metadatamap of string
namestring
phonestring
shipping_addressobject
tax_exemptboolean
Response · 200
dataobjectrequired
metaobject
request_idstring
Bash
curl -X PATCH https://api.withflintpay.com/v1/customers/cus_123 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "metadata": {
      "segment": "vip"
    },
    "phone": "+14155552671",
    "internal_note": "VIP buyer"
  }'
JSON
{
  "data": {
    "customer_id": "cus_123",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "metadata": {
      "crm_id": "crm_123"
    },
    "merchant_id": "mer_123",
    "billing_address": {
      "line1": "123 Main St",
      "country": "US",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001"
    },
    "phone": "+14155552671",
    "tax_exempt": true,
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}
Rate this doc