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

Endpoints

List customer deletion requests#

GET/v1/customer-deletion-requestsRequires 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_reviewprocessingcompletedrejectedfailed
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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/customer-deletion-requests \
  -H "Authorization: Bearer YOUR_API_KEY"

Resolve a customer deletion request#

POST/v1/customer-deletion-requests/{customer_deletion_request_id}/resolveIdempotentRequires 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
approvereject
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

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

List customers#

GET/v1/customersRequires 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 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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
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,
      "group_id": "vip",
      "is_verified": 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/customersIdempotentRequires scope: customers.write

Creates a customer for the authenticated merchant.

Request body
billing_addressobject
emailstringrequired
external_reference_idstring
group_idstring
internal_notestring
is_verifiedboolean
metadatamap of string
namestring
phonestring
shipping_addressobject
tax_exemptboolean
Response · 201
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDED
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,
    "group_id": "vip",
    "is_verified": 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}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. Expansion requires 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

Error codes

AUTH_REQUIREDDANGLING_EXPANSION_REFERENCEEXPANSION_DEPENDENCY_UNAVAILABLEEXPANSION_RESOLUTION_FAILEDINSUFFICIENT_SCOPEINTERNAL_ERRORINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/customers/cus_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Update customer#

PATCH/v1/customers/{customer_id}IdempotentRequires 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
external_reference_idstring
group_idstring
internal_notestring
is_verifiedboolean
metadatamap of string
namestring
phonestring
shipping_addressobject
tax_exemptboolean
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_API_KEYINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUND
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,
    "group_id": "vip",
    "is_verified": true,
    "created_at": "2026-03-17T14:30:00Z",
    "updated_at": "2026-03-17T14:30:00Z"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

List customer addresses#

GET/v1/customers/{customer_id}/addressesRequires 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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/customers/cus_123/addresses \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a customer address#

POST/v1/customers/{customer_id}/addressesIdempotentRequires 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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/customers/cus_123/addresses \
  -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
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/customers/cus_123/addresses/{customer_address_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update a customer address#

PATCH/v1/customers/{customer_id}/addresses/{customer_address_id}IdempotentRequires 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
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X PATCH https://api.withflintpay.com/v1/customers/cus_123/addresses/{customer_address_id} \
  -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}IdempotentRequires 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

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X DELETE https://api.withflintpay.com/v1/customers/cus_123/addresses/{customer_address_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Set a default customer address#

POST/v1/customers/{customer_id}/addresses/{customer_address_id}/set-defaultIdempotentRequires 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
billingshippingboth
Response · 200
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/customers/cus_123/addresses/{customer_address_id}/set-default \
  -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-requestsIdempotentRequires 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
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl -X POST https://api.withflintpay.com/v1/customers/cus_123/deletion-requests \
  -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
dataobjectrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/customers/cus_123/deletion-requests/{customer_deletion_request_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
Rate this doc