Customer email delivery

Flint emails your buyers about receipts, deliveries, subscriptions, failed payments, Returns, and invoices. You can take any of those over.

This is one setting per family, not one setting for everything. Most merchants who want their own receipts are happy to let Flint keep sending dunning, and there is no reason to make that an all-or-nothing trade.

The six families#

Each field on customer_email_delivery takes flint_sends, the default, or merchant_sends.

curl -X PATCH https://api.withflintpay.com/v1/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email_delivery": {
      "order_receipts": "merchant_sends",
      "fulfillment_updates": "merchant_sends"
    }
  }'

order_receipts covers every purchase receipt, including receipts for payments made without an order. Refund receipts are not in a family yet, so Flint always sends them for now.

customer_email_delivery is a merchant setting. Locations and devices can't override it.

The events keep firing#

Turning a family off stops Flint's mail and nothing else. The webhook events behind it are unchanged, which is the whole mechanism: you subscribe to what Flint would have written about, and write it yourself.

A payment retry on a past-due subscription, started by the buyer from their account or by you, sends subscription_payment_retry.created, then subscription_payment_retry.succeeded or subscription_payment_retry.failed. If you send your own dunning email, use them to tell the buyer how the retry went.

Not every event in a family deserves an email. fulfillment_updates fires six ways because a parcel changes state more often than a buyer wants to hear about it; Flint's own version does not send one message per event either. Pick the transitions your buyers care about. See choosing the right event.

Link the buyer to their order#

Flint's own email links the buyer to the order, subscription, or Return in your Flint-hosted customer account, and the link opens that page without a sign-in. Your email can carry the same link. Create one when you write the message:

curl -X POST https://api.withflintpay.com/v1/orders/ord_01J5Z8N3QK4W7Y2RB6TPVXHC9D/access-links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: order-paid-ord_01J5Z8N3QK4W7Y2RB6TPVXHC9D"

{
  "data": {
    "url": "https://links.withflintpay.com/account/YnV5ZXItYWNjb3VudC1saW5rOnYx.eyJ2IjoxfQ.kX8uY2Vy7Qp4Ht0Wm3Ja9Ls6Rd1Fb5Nc2Gz8Vq4Ek0#g=flint_bag_Tq3Zr8Wn1Kc6Lm0Pv5Xs9Hd2Fj7Gb4Ya8Ue3Ni6Ro1",
    "expires_at": "2026-11-02T15:04:05Z",
    "purpose": "order_view"
  },
  "request_id": "bce56cba-0827-44aa-bb56-4f200ba15ee6"
}

Put url in the message as it is. Anyone who has the link can see what it opens, so treat it like a password reset link: send it only to that buyer, keep it out of logs and analytics, and create a new one for each message. Flint returns it only in this response, and again when you retry with the same Idempotency-Key within 24 hours.

The retry key is scoped to your merchant, credential, environment, and the resource's route. A retry returns the original link without extending its lifetime or restoring its opens. Without a key, every call creates a new link and has no replay result. If Flint cannot retain a result after creating the link, contact support with the request ID before submitting another request.

Past either limit, the buyer signs in with a code Flint emails them instead. Each route needs the read scope of its resource: commerce.orders.read, commerce.subscriptions.read, or commerce.returns.read.

The link resolves when the buyer opens it, so it follows your current custom domain. It needs the Flint-hosted account: with customer_account.mode set to merchant_hosted, the routes return ACCESS_LINK_MERCHANT_HOSTED. Link to your own pages instead, and open them with a customer session. A link opens a resource only for its customer, so an order without a customer_id, or a Return whose order has none, returns ACCESS_LINK_CUSTOMER_REQUIRED. Set customer_id on orders before payment to link their buyers.

Email Flint always sends#

Flint sends these whatever customer_email_delivery says:

• Sign-in codes for Flint's hosted account.
• Codes that confirm an email change, sent to the current and the new address. The buyer types them to prove they own each address.
• Verification codes from checkout and from guest purchase linking.
• Refund receipts, for now, because they are not in a family yet.

Templates#

Flint does not currently support editing its email templates.

To control how it looks or what it says, set that family to merchant_sends and send it from the events above.

Account links still work#

Buyer email that Flint sends contains account links resolved at click time against your customer account settings. That is a separate decision from this one.

If you only want Flint's email to point at your own account pages, set customer_account.mode and leave customer_email_delivery alone. Repointing links is not the same as owning the mail, and it is much less work.

With customer_account.mode set to merchant_hosted, every account link follows it, including the "Pay invoice" button in invoice email and the unsubscribe link. Each opens the matching route template on your site. Build your own customer account covers the invoice and email_preferences templates and the parameters each link carries.

Next steps#

• Webhooks for signatures, retries, and exactly-once processing
• Webhook events catalog for every payload above
• Customer accounts to repoint links without taking over delivery