Customers

Customers are reusable buyer profiles: contact details, billing and shipping addresses, tax exemption, and your own cross-reference via external_reference_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 and must be unique per merchant. PATCH /v1/customers/{customer_id} cannot change it. The buyer changes their own email from their account by confirming possession of both the current and the new address; see customer accounts.

A customer can carry a default_payment_method_id, which marks the preferred saved payment method for flows like subscription billing. It is set only through set-default; see Save a card and charge it later.

There is no endpoint that deletes a customer outright. To honor a deletion or privacy request, create a customer deletion request and approve it; see Customer deletion requests.

The Customer object#

Every field on a customer, as returned by retrieve and carried by the endpoints below.

Attributes

billing_addressobject

created_atstring

RFC3339 timestamp.

customer_idstringRequired

default_invoice_payment_term_idstring

default_payment_methodobject or null

default_payment_method_idstring

emailstringRequired

external_reference_idstring

Caller-owned identifier for this resource in an external system.

group_idstring

internal_notestring

is_verifiedboolean

merchant_idstring

metadatamap of string

namestring

phonestring

receivablesobject

shipping_addressobject

tax_exemptboolean

tax_identityobject or null

Merchant-provided legal identity displayed on invoices and credit notes. Does not verify IDs or change tax treatment. Tax IDs are an owned collection in display order; replacing the array requires the parent's expected_version. Existing entries retain their document_tax_id; omit an entry to remove it, or omit its ID to add one.

updated_atstring

RFC3339 timestamp.

versionintegerRequired

JSON

{
  "billing_address": {
    "city": "New York",
    "country": "US",
    "line1": "123 Main St",
    "postal_code": "10001",
    "state": "NY"
  },
  "created_at": "2026-03-17T14:30:00Z",
  "customer_id": "cus_123",
  "email": "jane@example.com",
  "group_id": "vip",
  "is_verified": true,
  "merchant_id": "mer_123",
  "metadata": {
    "crm_id": "crm_123"
  },
  "name": "Jane Doe",
  "phone": "+14155552671",
  "tax_exempt": true,
  "tax_identity": null,
  "updated_at": "2026-03-17T14:30:00Z",
  "version": 0
}

List customer deletion requests#

GET/v1/customer-deletion-requests

Requires scope customers.read or customers.write

Lists deletion requests across the selected merchant environment so a merchant can discover and review buyer-created requests.

Query parameters

statusenum

Only return requests in this lifecycle state.

pending_review
processing
completed
rejected
failed

customer_idstring

Only return requests for this Flint customer ID.

page_sizeinteger

Number of deletion requests to return.

page_tokenstring

Opaque token returned by the previous page.

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

curl https://api.withflintpay.com/v1/customer-deletion-requests \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resolve a customer deletion request#

POST/v1/customer-deletion-requests/{customer_deletion_request_id}/resolveIdempotent

Requires scope customers.write

Approves or rejects a pending deletion request. Approval returns processing while account data and buyer credentials are deleted asynchronously. A failed deletion can be approved again but cannot be rejected. Approval is blocked while the customer has non-canceled subscriptions or usable saved payment methods.

Path parameters

customer_deletion_request_idstringRequired

Flint customer deletion request ID.

Request body

decisionenumRequired

approve
reject

Response · 200

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/customer-deletion-requests/{customer_deletion_request_id}/resolve \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "decision": "approve"
  }'

Create a customer email verification#

POST/v1/customer-verificationsIdempotent

Requires scope customers.write

Sends the buyer a Flint verification code for linking guest purchases. Set purpose to link_guest_purchases. The only channel is email, which is also the default. The response has the same shape whether a code was sent. Enter the code through the confirm operation before linking purchases.

Request body

channelenum

Defaults to email when omitted. Explicit null and an empty value are not accepted.

email

customer_idstringRequired

emailstringRequired

purposeenumRequired

link_guest_purchases

Response · 201

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/customer-verifications \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "customer_id": "",
    "email": "",
    "purpose": "link_guest_purchases"
  }'

Confirm a customer email verification#

POST/v1/customer-verifications/{customer_verification_id}/confirmIdempotent

Requires scope customers.write

Confirms the Flint-sent code and returns a verification that can link guest purchases for its customer. A confirmed verification expires in 15 minutes and can be redeemed once.

Path parameters

customer_verification_idstringRequired

Flint customer verification ID.

Request body

codestringRequired

Response · 200

Same response as Create a customer email verification.

curl -X POST https://api.withflintpay.com/v1/customer-verifications/cscv_01K6ZQ4TE3M8Q2N7W5V1R9X0YB/confirm \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "code": ""
  }'

List customers#

GET/v1/customers

Requires scope customers.read or customers.write

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_id, name, email, phone number, and external_reference_id. Text fields match any part of the value, and %, _ and \ are ordinary characters, not wildcards. IDs match from the start and need the type prefix, such as ord_01.

external_reference_idstring

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

emailstring

Exact-match filter on email address.

sort_byenum

Sort field.

name
email
created_at
updated_at

sort_directionenum

Sort direction.

asc
desc

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.

expandarray of enum

Supported expansions: receivables. Supported expansion: receivables. Limits: at most 10 unique expand paths per request; path depth at most 2. Repeat expand, for example expand=receivables&expand=receivables, or pass one comma-separated value.

receivables

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

curl https://api.withflintpay.com/v1/customers \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": [
    {
      "billing_address": {
        "city": "New York",
        "country": "US",
        "line1": "123 Main St",
        "postal_code": "10001",
        "state": "NY"
      },
      "created_at": "2026-03-17T14:30:00Z",
      "customer_id": "cus_123",
      "email": "jane@example.com",
      "group_id": "vip",
      "is_verified": true,
      "merchant_id": "mer_123",
      "metadata": {
        "crm_id": "crm_123"
      },
      "name": "Jane Doe",
      "phone": "+14155552671",
      "tax_exempt": true,
      "tax_identity": null,
      "updated_at": "2026-03-17T14:30:00Z",
      "version": 0
    }
  ],
  "next_page_token": "example",
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Create customer#

POST/v1/customersIdempotent

Requires scope customers.write

Creates a customer for the authenticated merchant.

Request body

billing_addressobject

default_invoice_payment_term_idstring

emailstringRequired

external_reference_idstring

Caller-owned identifier for this resource in an external system.

group_idstring

internal_notestring

is_verifiedboolean

metadatamap of string

namestring

phonestring

shipping_addressobject

tax_exemptboolean

tax_identityobject

Response · 201

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/customers \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "billing_address": {
      "city": "New York",
      "country": "US",
      "line1": "123 Main St",
      "postal_code": "10001",
      "state": "NY"
    },
    "email": "jane@example.com",
    "metadata": {
      "crm_id": "crm_123"
    },
    "name": "Jane Doe"
  }'

Get customer#

GET/v1/customers/{customer_id}

Requires scope customers.read or customers.write

Returns a single customer by ID.

Path parameters

customer_idstringRequired

Flint customer ID.

Query parameters

expandarray of enum

Supported expansions: default_payment_method, receivables. Expanding the default payment method requires customers.read plus payments.payment_methods.read. Limits: at most 10 unique expand paths per request; path depth at most 2. Repeat expand, for example expand=default_payment_method&expand=receivables, or pass one comma-separated value.

default_payment_method
receivables

Response · 200

Same response as Create customer.

curl https://api.withflintpay.com/v1/customers/cus_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

JSON

{
  "data": {
    "billing_address": {
      "city": "New York",
      "country": "US",
      "line1": "123 Main St",
      "postal_code": "10001",
      "state": "NY"
    },
    "created_at": "2026-03-17T14:30:00Z",
    "customer_id": "cus_123",
    "email": "jane@example.com",
    "group_id": "vip",
    "is_verified": true,
    "merchant_id": "mer_123",
    "metadata": {
      "crm_id": "crm_123"
    },
    "name": "Jane Doe",
    "phone": "+14155552671",
    "tax_exempt": true,
    "tax_identity": null,
    "updated_at": "2026-03-17T14:30:00Z",
    "version": 0
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Update customer#

PATCH/v1/customers/{customer_id}Idempotent

Requires scope customers.write

Applies a sparse update to a customer. Writing billing_address or shipping_address clears the corresponding saved-address default, so that field remains effective until another saved default is selected.

Path parameters

customer_idstringRequired

Flint customer ID.

Request body

billing_addressobject

default_invoice_payment_term_idstring

expected_versioninteger

Required when replacing tax_ids or clearing tax_identity. Stale versions return a conflict.

external_reference_idstring

Caller-owned identifier for this resource in an external system.

group_idstring

internal_notestring

is_verifiedboolean

metadatamap of string or null

Caller-owned metadata. Omit this field to leave metadata unchanged. Send an object to merge by key, set a key to null to remove it, or set metadata to null to clear all metadata. An empty object makes no change. Empty strings are stored. Keys starting with flint_ are reserved and cannot be written through the public API.

namestring

phonestring

shipping_addressobject

tax_exemptboolean

tax_identityobject or null

Response · 200

Same response as Create customer.

curl -X PATCH https://api.withflintpay.com/v1/customers/cus_123 \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "internal_note": "VIP buyer",
    "metadata": {
      "segment": "vip"
    },
    "phone": "+14155552671"
  }'

List customer addresses#

GET/v1/customers/{customer_id}/addresses

Requires scope customers.read or customers.write

Lists the customer's saved addresses with billing and shipping default flags.

Path parameters

customer_idstringRequired

Flint customer ID.

Query parameters

page_sizeinteger

Number of addresses to return.

page_tokenstring

Opaque token returned by the previous page.

Response · 200

dataarray of objectRequired

metaobject

next_page_tokenstring

request_idstring

curl https://api.withflintpay.com/v1/customers/cus_123/addresses \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a customer address#

POST/v1/customers/{customer_id}/addressesIdempotent

Requires scope customers.write

Creates a stable saved address. The first address becomes both the billing and shipping default. A saved default becomes the customer's effective address for the corresponding role.

Path parameters

customer_idstringRequired

Flint customer ID.

Request body

addressobjectRequired

is_default_billingboolean

is_default_shippingboolean

labelstring

phonestring

recipient_namestringRequired

Response · 201

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/customers/cus_123/addresses \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "address": {
      "city": "",
      "country": "US",
      "line1": "",
      "postal_code": "",
      "state": ""
    },
    "recipient_name": ""
  }'

Get a customer address#

GET/v1/customers/{customer_id}/addresses/{customer_address_id}

Requires scope customers.read or customers.write

Returns one saved address owned by the customer.

Path parameters

customer_idstringRequired

Flint customer ID.

customer_address_idstringRequired

Flint customer address ID.

Response · 200

Same response as Create a customer address.

curl https://api.withflintpay.com/v1/customers/cus_123/addresses/{customer_address_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a customer address#

PATCH/v1/customers/{customer_id}/addresses/{customer_address_id}Idempotent

Requires scope customers.write

Applies a sparse update to a saved address. Updating a default address also updates the customer's effective address for that role.

Path parameters

customer_idstringRequired

Flint customer ID.

customer_address_idstringRequired

Flint customer address ID.

Request body

addressobject

labelstring

phonestring

recipient_namestring

Response · 200

Same response as Create a customer address.

curl -X PATCH https://api.withflintpay.com/v1/customers/cus_123/addresses/{customer_address_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "address": {
      "city": "",
      "country": "US",
      "line1": "",
      "postal_code": "",
      "state": ""
    },
    "label": "",
    "phone": "",
    "recipient_name": ""
  }'

Delete a customer address#

DELETE/v1/customers/{customer_id}/addresses/{customer_address_id}Idempotent

Requires scope customers.write

Deletes a saved address and moves any default designation to the newest remaining address.

Path parameters

customer_idstringRequired

Flint customer ID.

customer_address_idstringRequired

Flint customer address ID.

Response · 200

dataobjectRequired

metaobject

request_idstring

curl -X DELETE https://api.withflintpay.com/v1/customers/cus_123/addresses/{customer_address_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Set a default customer address#

POST/v1/customers/{customer_id}/addresses/{customer_address_id}/set-defaultIdempotent

Requires scope customers.write

Sets the address as the billing default, shipping default, or both and makes it the customer's effective address for each selected role.

Path parameters

customer_idstringRequired

Flint customer ID.

customer_address_idstringRequired

Flint customer address ID.

Request body

default_forenumRequired

billing
shipping
both

Response · 200

Same response as Create a customer address.

curl -X POST https://api.withflintpay.com/v1/customers/cus_123/addresses/{customer_address_id}/set-default \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "default_for": "billing"
  }'

Request customer account deletion#

POST/v1/customers/{customer_id}/deletion-requestsIdempotent

Requires scope customers.write

Creates or returns the pending tracked deletion request. Required commerce records are retained until the deletion workflow resolves their legal retention requirements.

Path parameters

customer_idstringRequired

Flint customer ID.

Response · 202

Same response as Resolve a customer deletion request.

curl -X POST https://api.withflintpay.com/v1/customers/cus_123/deletion-requests \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get a customer deletion request#

GET/v1/customers/{customer_id}/deletion-requests/{customer_deletion_request_id}

Requires scope customers.read or customers.write

Returns the current status of a tracked deletion request.

Path parameters

customer_idstringRequired

Flint customer ID.

customer_deletion_request_idstringRequired

Flint customer deletion request ID.

Response · 200

Same response as Resolve a customer deletion request.

curl https://api.withflintpay.com/v1/customers/cus_123/deletion-requests/{customer_deletion_request_id} \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY"

Link guest purchases to a customer#

POST/v1/customers/{customer_id}/link-guest-purchasesIdempotent

Requires scope customers.write

Links purchases with the verified email and no customer to the verification's customer in the same merchant environment. Purchases bound to another customer stay with that customer. The verification is single use; use the same Idempotency-Key to retry an uncertain result.

Path parameters

customer_idstringRequired

Flint customer ID.

Request body

customer_verification_idstringRequired

Response · 200

dataobjectRequired

metaobject

request_idstring

curl -X POST https://api.withflintpay.com/v1/customers/cus_123/link-guest-purchases \
  -H "Flint-Version: 2026-09-07" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "customer_verification_id": ""
  }'

Was this helpful?