Customer deletion requests
When a customer asks you to delete their data, for example under GDPR or CCPA, you record it as a customer deletion request. There is no DELETE /v1/customers/{customer_id}. Every deletion goes through a request that someone on your side approves or rejects, and approval erases the customer's personal data instead of your sales history. The customer stays readable by ID with status: "deleted".
A request can start in two places:
- The customer asks from their account. Flint's hosted customer account and accounts you build on
/v1/meboth let a signed-in customer request deletion.GET /v1/me/deletion-requestslists that customer's requests newest first, with the samestatusfilter and paging as the merchant list, so an account can show where a request stands and when an earlier one was rejected. - You open it for them. Use this when the request arrives by email, phone, or a support ticket. Create it with
POST /v1/customer-deletion-requests.
Both land in the same queue and follow the same review.
How a request moves#
status on customer deletion requestA customer has at most one open request at a time. Asking again while one is pending_review, processing, or failed returns the existing request instead of creating a new one.
How the customer's status changes#
Every customer has a read-only status, on GET /v1/customers/{customer_id}, in lists, in customer.* events, and wherever an order, invoice, payment, or subscription expands its customer.
status on customerApproving a request moves the customer from active to deletion_processing, raises its version, and sends customer.updated. Completion moves it to deleted and sends customer.deleted.
GET /v1/customers lists active and deletion_processing customers. A deleted customer drops out of the list unless you ask for it with status:
curl "https://api.withflintpay.com/v1/customers?status=deleted" \
-H "Authorization: Bearer YOUR_API_KEY"
Repeat status or separate values with commas to combine them, such as status=active,deleted. A page token from a list with one status filter is rejected on a list with another.
Receive a customer's request#
Subscribe to customer_deletion_request.created so each request reaches a person or a ticket queue:
{
"event_type": "customer_deletion_request.created",
"data": {
"object": {
"customer_deletion_request_id": "cdel_1kmn0aExample",
"customer_id": "cus_1kmn0aExample",
"status": "pending_review",
"retention_policy": "retain_required_commerce_records",
"requested_at": "2026-09-22T17:04:05Z",
"requested_by": "buyer",
"decision_reason": null,
"decided_at": null,
"response_due_at": "2026-10-22T17:04:05Z"
}
}
}
To review the queue without webhooks, list open requests:
curl "https://api.withflintpay.com/v1/customer-deletion-requests?status=pending_review" \
-H "Authorization: Bearer YOUR_API_KEY"
Each request includes requested_by: buyer for a request opened from the buyer account, or merchant for one you opened on their behalf. It is null only for pre-existing requests whose source cannot be determined. Returning an existing open request preserves its original source. response_due_at is requested_at plus one calendar month in UTC, with the day clamped to the end of the next month: January 31 becomes February 28, or February 29 in a leap year.
The list filters by status and customer_id and pages with page_size (up to 100) and page_token. GET /v1/customer-deletion-requests/{customer_deletion_request_id} reads one request. Reads need the customers.read scope; creating and resolving need customers.write.
Open a request yourself#
When the customer asks outside their account, create the request for them and name the customer in the body:
curl -X POST https://api.withflintpay.com/v1/customer-deletion-requests \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: delete-cus-1kmn0a" \
-d '{"customer_id": "cus_1kmn0aExample"}'
{
"data": {
"customer_deletion_request_id": "cdel_1kmn0aExample",
"customer_id": "cus_1kmn0aExample",
"status": "pending_review",
"retention_policy": "retain_required_commerce_records",
"requested_at": "2026-09-22T17:04:05Z",
"requested_by": "merchant",
"decision_reason": null,
"decided_at": null,
"response_due_at": "2026-10-22T17:04:05Z"
}
}
A new request returns 201 Created, and customer_deletion_request.created fires just as it does for a customer's own request. If the customer already has an open request, Flint returns it unchanged with 200 OK and creates nothing. Nothing is deleted until you approve, so confirm the requester's identity first.
A retry with the same key and body replays the original status, 201 or 200. A request for another customer_id needs its own key. A missing or malformed customer_id returns 400 INVALID_REQUEST with param: customer_id.
POST /v1/me/deletion-requests, the route behind a signed-in customer's own request, follows the same rule with an empty body: 201 for a new request and 200 for the open one.
Clear subscriptions and saved cards#
While a request is pending_review, its GET and list responses include blocking_resources and blocking_resource_count. These identify the subscriptions and saved cards that must be cleared manually or through the approval options. They are computed when you read the request, using the same resource rules as approval. blocking_resources contains references such as {"resource_type": "subscription", "resource_id": "sub_1kmn0aExample"}, capped at 25 subscriptions and 25 payment methods. The total count includes every blocker. If it exceeds the array's length, list the customer's subscriptions and payment methods to find the rest. When all blockers are cleared, the fields are [] and 0; on other request statuses, both fields are absent. Creation webhooks include the same fields in their pending request snapshot.
Flint will not erase a customer who could still be charged. To let Flint clear the blockers, approve with both options in the same body:
{"decision": "approve", "cancel_subscriptions": true, "remove_payment_methods": true}
Both options default to false. cancel_subscriptions cancels every non-canceled subscription immediately through the usual cancellation path. remove_payment_methods detaches and archives every active or pending saved card. When both are selected, subscriptions are canceled first. If a category you did not select still blocks deletion, approval returns 409 RESOURCE_IN_USE before doing any work.
Approval returns processing. Read the request again to follow canceled_subscription_ids and removed_payment_method_ids; both are sorted arrays and start empty. Completed work is preserved across failures and retries. If the request becomes failed, approve again with the original options or omit them to resume. Options cannot change after the first approval. When deletion completes, the arrays remain available on the request.
To clear the blockers yourself before approving:
- Cancel every subscription that is not already
canceled. Cancel with{"cancel_immediately": true}; a subscription scheduled to cancel at period end still counts until that date. See Cancel. - Delete every saved card that is
activeorpending. See Delete a card.
curl "https://api.withflintpay.com/v1/subscriptions?customer_id=cus_1kmn0aExample" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.withflintpay.com/v1/payment-methods?customer_id=cus_1kmn0aExample&status=active,pending" \
-H "Authorization: Bearer YOUR_API_KEY"
The payment method list returns every status except archived by default, so status=active,pending narrows it to the cards that block approval. A deleted card is archived and no longer blocks it. Deleting a card that is already archived returns it again with no second event.
Unpaid invoices and open orders do not block deletion. Collect, void, or write them off before approving if you need them settled.
Approve or reject#
curl -X POST https://api.withflintpay.com/v1/customer-deletion-requests/cdel_1kmn0aExample/resolve \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Idempotency-Key: resolve-cdel-1kmn0a" \
-d '{"decision": "approve"}'
{
"data": {
"customer_deletion_request_id": "cdel_1kmn0aExample",
"customer_id": "cus_1kmn0aExample",
"status": "processing",
"retention_policy": "retain_required_commerce_records",
"requested_at": "2026-09-22T17:04:05Z",
"requested_by": "merchant",
"decision_reason": null,
"decided_at": "2026-09-22T17:20:00Z",
"response_due_at": "2026-10-22T17:04:05Z"
}
}
"decision": "approve"moves the request toprocessingand the customer todeletion_processing. The customer's sessions end right away, and any change to the customer, such as saving a card or creating a subscription, fails withACTION_NOT_ALLOWEDwithdetails[0].reason: in_progress. Flint sendscustomer_deletion_request.processing, andcustomer.updatedwith the customer'sstatusand its newversion. Approving afailedrequest again sendscustomer_deletion_request.processingagain, changes nothing about the customer, and sends nocustomer.updated."decision": "reject"moves it torejectedand firescustomer_deletion_request.rejected. The customer is unchanged. You can includedecision_reason, a plain-text explanation the buyer can read throughGET /v1/me/deletion-requestsand its single-request route. Flint trims leading and trailing whitespace; the remaining text must contain 1 to 500 characters. A blank reason is refused. Omitting it leavesdecision_reason: null. Sending it withapprovereturns400 INVALID_REQUESTwith detail codeNOT_ALLOWEDandparam: decision_reasonbefore changing the request or customer.- If a subscription or saved card remains, approval fails with
RESOURCE_IN_USE. The error message gives the counts.details[0].blocking_resourceslists up to 25 blockers asresource_typeandresource_id, ordered by type, then ID.details[0].blocking_resource_countgives the total; if it exceeds the list length, the list is truncated. Only subscriptions and payment methods in the customer's merchant, mode, and environment are included, subject to your read permissions. Clear the listed resources and list the customer's remaining subscriptions and saved cards if needed.
When the customer has an email address, Flint emails them after a rejection and after an approved deletion completes. Both emails use your store's branding, and replies go to your support email when it is set. The rejection includes decision_reason when you provide it. The completion notice explains what was erased, which orders and receipts stay with your store for its records, and that deletion cannot be undone.
For example, reject with an explanation:
{
"decision": "reject",
"decision_reason": "Records are required while an active chargeback dispute is resolved."
}
The response includes the trimmed decision_reason and sets both decided_at and resolved_at to the rejection time. Repeating the decision returns the stored reason unchanged. completed and rejected requests have no further lifecycle actions: their supported_actions is [].
decided_at records the most recent approve or reject decision. It is null while pending, and for pre-existing decisions whose time cannot be determined. Approval sets it while the request is still processing; retry approval updates it. Completion or failure leaves it unchanged.
resolved_at is the time of the most recent resolved outcome: rejected, completed, or failed. It is absent while the request is pending_review or processing. Approving a failed request again clears it until the next resolved outcome.
Processing runs in the background and ends in completed, which fires customer_deletion_request.completed, or in failed, which fires customer_deletion_request.failed. To check a request between events, read it:
curl https://api.withflintpay.com/v1/customer-deletion-requests/cdel_1kmn0aExample \
-H "Authorization: Bearer YOUR_API_KEY"
A request fails when a subscription or saved card appears while it is processing. Clear it and approve the same request again. A failed request can be approved again but not rejected.
What Flint deletes and what it keeps#
When the request completes:
- The customer record is anonymized. Its name becomes "Deleted customer".
email,phone,billing_address,shipping_address,tax_identity,internal_note,metadata,external_reference_id,segment, anddefault_payment_method_idare cleared, andis_merchant_verifiedbecomesfalse. Saved addresses are deleted. - Saved cards keep no card details. The payment method records stay with their brand, last four digits, and expiry removed, and the processor no longer holds the card.
- Earlier customer writes cannot replay erased data. After completion, an idempotent replay of a customer create, update, saved-address write, or tax exemption write returns
409 ACTION_NOT_ALLOWEDwith reasonterminal_status. ReadGET /v1/customers/{customer_id}for the deleted customer. - Retained contact copies are erased in batches after your processing deletions finish. Cleanup is scheduled about 10 minutes after completion, with a follow-up about 24 hours later. If other deletions are still processing for your merchant, cleanup waits for them to finish. This includes retained write responses and stored email and webhook payloads awaiting delivery. Replay expiry does not determine when these copies are erased; required command records can remain after their contact details are cleared.
- Sales history is kept, without contact details. Orders, invoices, credit notes, payments, and refunds stay for accounting, tax, and disputes. Email addresses and phone numbers are removed from them, including invoice delivery attempts.
- Issued invoices keep who they were issued to. Tax law requires an issued invoice to keep the buyer's name, address, and tax ID, so invoices and credit notes issued before deletion keep
customer_display_name,billing_address, andbuyer_tax_identity, and their PDFs don't change. Invoice search no longer matches that name; find these invoices by number or withcustomer_id. Draft invoices lose them and can't be issued. - Buyer links stop working at approval. Hosted invoice pages and invoice PDF links sent to the customer stop opening, and a new link can't be generated. Settle open invoices before approving, or record payment manually.
- Orders keep the delivery address. The recipient's name and address stay as shipping and tax evidence; the recipient's phone and email are removed.
- Custom field answers are removed. The customer's orders and their checkout sessions return
custom_field_answers: []. Answers older orders keep inmetadataare treated like other metadata. - Email preferences are kept separately, so an unsubscribe is still honored. Flint stores a keyed marker, not the email address. After deletion,
POST /v1/email-preferences/lookupwith the address still returns its preferences, withcustomer_idandversionasnullwhen no customer has that address. The deleted customer's email-preferences read returns404because its email was erased. Deletion sends nocustomer_email_preferences.updated; usecustomer.deletedfor erasure.
The customer is not removed. GET /v1/customers/{customer_id} returns it with status: "deleted", and so does expanding customer on an order, invoice, payment, or subscription, so reports and refunds keep working. What it returns is only:
customer_id,merchant_id,version,created_at, andupdated_at.status: "deleted"andname: "Deleted customer".email,phone,tax_identity,external_reference_id,internal_note, andsegmentasnull, an emptymetadata, and no addresses or default payment method.tax_exempt,default_invoice_payment_term_id, andreceivables, which are not personal data.receivables, when you expand it, keeps unpaid invoices explainable.
A deleted customer can't be changed or reactivated. Creating a customer session for a customer with status: deleted or deletion_processing returns 409 ACTION_NOT_ALLOWED with details[0].reason: terminal_status, resource_type: customer, and current_status naming that status. No session credentials are created. A new deletion request for a deleted customer returns 409 ACTION_NOT_ALLOWED with details[0].reason: already_applied. If the same person comes back, create a new customer.
You can still revoke sessions for a retained customer. Revoke-all returns 200 with revoked_count: 0 when no sessions remain to revoke.
If you keep your own copy of the customer's data, in your database, CRM, or analytics, delete it when customer.deleted or customer_deletion_request.completed arrives. Flint erases external_reference_id, so correlate by customer_id. If you map customers by external_reference_id, read the mapping when customer_deletion_request.created or the customer.updated that approval sends arrives, before completion.
Respond to an access request#
When a customer asks what data you hold about them, for example under GDPR Article 15 or 20 or the CCPA right to know, there is no export route to call. You answer from reads made with your API key, one customer at a time. Confirm the requester's identity first, as you would for a deletion request, and decide with your counsel what you send back and in what format.
1. Find the customer#
Search by the email the requester gave you. The match is exact and ignores case:
curl "https://api.withflintpay.com/v1/customers?email=ana@example.com" \
-H "Authorization: Bearer YOUR_API_KEY"
Repeat for any other address the person used. A customer you already deleted is anonymized and has no personal data left to disclose, and a list leaves it out unless you add status=deleted.
2. Read the customer's records#
Replace cus_1kmn0aExample with the customer's ID. Every list takes page_size (up to 100) and page_token, so page each one to the end. A key with the matching .write scope can make the same read.
| Data | Read | Scope |
|---|---|---|
| Profile, default addresses, tax identity, metadata | GET /v1/customers/{customer_id} | customers.read |
| Saved addresses | GET /v1/customers/{customer_id}/addresses | customers.read |
| Email preferences | GET /v1/customers/{customer_id}/email-preferences | customers.read |
| Deletion requests | GET /v1/customer-deletion-requests?customer_id= | customers.read |
| Orders | GET /v1/orders?customer_id=, then GET /v1/orders/{order_id}/activities for each | commerce.orders.read |
| Fulfillments | GET /v1/fulfillments?customer_id= | commerce.orders.read |
| Shipments, packages, and fulfillment events | For each order: GET /v1/shipments?order_id=, GET /v1/packages?order_id=, and GET /v1/fulfillment-events?order_id= | commerce.orders.read |
| Checkout sessions | GET /v1/checkout-sessions?customer_id= | checkouts.checkout_sessions.read |
| Payments | GET /v1/payment-intents?customer_id=, then GET /v1/payment-intents/{payment_intent_id}/activities for each | payments.payment_intents.read |
| Refunds | GET /v1/refunds?customer_id= | commerce.refunds.read |
| Saved payment methods | GET /v1/payment-methods?customer_id= | payments.payment_methods.read |
| Subscriptions and their payment retries | GET /v1/subscriptions?customer_id=, then GET /v1/subscriptions/{subscription_id}/payment-retries for each | commerce.subscriptions.read |
| Invoices | GET /v1/invoices?customer_id=, then GET /v1/invoices/{invoice_id}/activities for each | commerce.invoices.read |
| Credit notes | GET /v1/credit-notes?customer_id= | commerce.credit_notes.read |
| Returns | GET /v1/returns?customer_id=, then GET /v1/return-resolutions?return_id= and GET /v1/returns/{return_id}/activities for each | commerce.returns.read |
| Gift cards assigned to the customer, including store credit | GET /v1/gift-cards?customer_id= | commerce.gift_cards.read |
| Disputes | GET /v1/disputes?customer_id= | payments.disputes.read |
| Payment reviews | GET /v1/payment-reviews?customer_id= | risk.read |
Payment reviews hold your risk assessment of the customer's payments. Decide with your counsel how much of that you disclose.
A gift card the customer bought is assigned to whoever holds it, so it can have customer_id: null, and the gift card read above doesn't list it. Step 4 finds those from the orders.
3. Add purchases made as a guest#
A typed email never attaches a purchase to an existing customer, so a purchase the person made as a guest with the same email stays unlinked. It doesn't appear under customer_id. Filter orders by the exact email instead:
curl "https://api.withflintpay.com/v1/orders?email=ana%40example.com" \
-H "Authorization: Bearer YOUR_API_KEY"
email matches either buyer_contact.email or the linked customer's email exactly, ignoring case. It returns both guest and linked orders, so deduplicate by order_id against the orders collected in step 2. For each one, read the related records by order_id: GET /v1/fulfillments, /v1/shipments, /v1/packages, /v1/fulfillment-events, /v1/checkout-sessions, /v1/payment-intents, /v1/refunds, /v1/invoices, /v1/returns, /v1/disputes, and /v1/payment-reviews all take it as a filter. Link a buyer's guest purchases explains how an order later joins a customer.
4. Add gift cards the customer bought#
On each order you collected in steps 2 and 3, every line item's purchased_gift_cards lists the cards it issued. Read each card by its gift_card_id, which needs commerce.gift_cards.read:
curl https://api.withflintpay.com/v1/gift-cards/gc_1kmn0aExample \
-H "Authorization: Bearer YOUR_API_KEY"
Order reads never include the card's code.
5. Add checkouts the customer left#
A buyer who typed their email at hosted Checkout and left has an unpaid order and a checkout session. The session's buyer_contact.email holds the email. The order may hold the name and address they entered, but GET /v1/orders?email= doesn't match it, because the order has no email. GET /v1/checkout-sessions has no email filter either, so list the sessions and compare the email yourself:
curl "https://api.withflintpay.com/v1/checkout-sessions?updated_after=2026-10-21T00:00:00Z&page_size=100" \
-H "Authorization: Bearer YOUR_API_KEY"
This read needs checkouts.checkout_sessions.read. Set updated_after to 30 days before today, and page to the end. Flint clears a session's buyer_contact 30 days after the session ends, so an older checkout holds no email to match. For each session whose buyer_contact.email matches the requester's address, ignoring case, read its order with GET /v1/orders/{order_id}, and add it to the orders you collected. Then read the order's related records as in step 3.
6. Read email preferences for an address#
GET /v1/customers/{customer_id}/email-preferences returns the preferences for the customer's current email address. The preferences belong to the address, so they also cover guest checkouts with it. For an address with no customer, send it in the body:
curl -X POST https://api.withflintpay.com/v1/email-preferences/lookup \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"email": "ana@example.com"}'
The response has the same shape as the customer read, with customer_id and version as null when no customer has the address. Both reads need customers.read. A customer with no email address returns 404 RESOURCE_NOT_FOUND with reason email_missing.
7. Read saved gift cards with a customer session#
One read still needs a session that acts as the customer. A buyer can save a gift card to their account by proving they hold the code. Saved access is proof of possession, not a link to the customer, so GET /v1/gift-cards?customer_id= doesn't list it. To read the cards the customer saved:
- Create a session with
POST /v1/customer-sessionsand the customer'scustomer_id. Your key needscustomers.sessions.write. Setexpires_in_secondsto300, the shortest lifetime. - Call
GET /v1/me/gift-cardswith the session'ssecretas the bearer token. - Revoke the session when you have the answer.
The session signs in as the customer, so run it from your backend and don't show its secret to anyone.
What is not part of your answer#
- Flint wallet cards. Cards in a buyer's Flint wallet (
/v1/me/flint-wallet/cards) belong to the buyer's Flint account, not to your store. Your API key and your sessions can't read them. Send a request for them to Flint. - Pending email changes. A request to change a buyer's email lasts 30 minutes, and Flint clears its old and new addresses and its codes once it expires, within about an hour. No read returns one.
- Request logs.
GET /v1/api-request-logscan hold a customer's data in request bodies, but only briefly: headers and bodies are kept for 14 days and summaries for 90. Buyer-side IP addresses and user agents are kept for 30 days. Deleting a customer removes the IP address, user agent, headers, bodies, and query parameters from their own buyer requests. The summary remains for its 90-day retention. Treat them as short-lived operational logs. Debug API requests lists what they capture.
Gaps to plan for#
- No single export. You assemble the answer from the reads above and format it yourself.
- No
customer_idfilter on shipments, packages, or fulfillment events. Read them for each order. Credit notes also have noorder_idfilter, so a guest order's credit notes can't be found by filter. - No
emailfilter on checkout sessions. You list recent sessions and comparebuyer_contact.emailyourself. - Saved gift cards need a customer session. No read with your API key alone returns them.
Webhook events#
The customer_deletion_request.* events carry the deletion request in data.object: customer_deletion_request_id, customer_id, status, retention_policy, requested_at, requested_by, decision_reason, decided_at, response_due_at, and resolved_at once the request is resolved. The buyer reads the same decision fields. If the customer is later deleted, rejection reasons on their earlier requests and stored event copies are erased. customer.updated and customer.deleted carry the customer. The customer.deleted object is the same record GET /v1/customers/{customer_id} returns after deletion, so it holds none of the erased values. Completion sends both customer.deleted and customer_deletion_request.completed; each belongs to its own resource, so subscribe to customer.* if you mirror customers. Partner apps receive only customer.deleted: deletion request events go to the merchant's own endpoints, because the deletion request routes refuse partner app tokens. A deletion request has no version; each status change sends one event with data.previous_attributes, and repeating a request or a decision sends nothing. Deletion also cancels the customer's pending invoice emails, each with invoice_delivery_attempt.failed: those still queued while the request is processing, at completion, and any found later. Erasing the customer's data from its orders, invoices, payments, and checkout sessions sends no event for those records, and a record whose GET doesn't change keeps its version.
processing and failed can repeat for one request. Dedupe on webhook_event_id, and read the request when you need its current status, since deliveries can arrive out of order. Deleting cards before approval fires payment_method.archived for each card; the customer deletion itself does not.
Errors you will hit#
Common mistakes#
- Canceling subscriptions at period end. A subscription with
cancel_at_period_endstill blocks approval. Cancel it immediately. - Checking only active cards. A card the customer started saving and abandoned is
pendingand still blocks approval. Astatus=activelist misses it, so list withstatus=active,pending. - Treating
failedas final. Afailedrequest can be approved again, which sendscustomer_deletion_request.processingagain. Wait forcustomer_deletion_request.completedbefore you delete your own copy. - Expecting sales history to disappear. Orders, invoices, and payments stay. Contact details go, and issued invoices keep the name, address, and tax ID they were issued with.
- Looking for a deleted customer in the list.
GET /v1/customersleaves deleted customers out. Read one by ID, or list withstatus=deleted. - Keeping your own copy. Flint deletes its data, not yours. Handle
customer.deletedin every system that stores the customer.
Next steps#
- Customer accounts: where customers request deletion in the hosted account.
- Save a card and charge it later: list and delete a customer's saved cards.
- Subscription billing: cancel subscriptions immediately.
- Customer sessions: create and revoke the session that reads saved gift cards.
- Customers API Reference: every field on the customer.