141 changes to the Flint API, SDKs, and docs, newest first, from October 26, 2026 to November 1, 2026. The newest changes are on the changelog.
API
Customers
Subscriptions
Set a return destination on customer and subscription access links#
Send return_url when creating a customer access link or subscription access link to keep a destination on your site for the browser session the link starts. The customer route now accepts an optional JSON body; calls without a body still work.
The URL must be nonempty absolute HTTPS without credentials, up to 2,048 characters. Query strings and fragments are allowed, with no host allowlist. Test mode also accepts HTTP loopback URLs. Invalid values return 400 INVALID_REQUEST with detail INVALID_VALUE at return_url.
Every access-link response now includes return_url. It is null when omitted, and always null for order and Return links. Changing or adding the URL requires a new idempotency key. The destination ends with sign-out or session end; a later sign-in by emailed code has no return URL.
Buyers can now move their own subscription to another plan. You choose the plans: set plan_change_options on a subscription plan to up to 25 {subscription_plan_id, billing_starts} entries, where billing_starts is now or next_renewal for that path. The default [] keeps plan changes off. Your own POST /v1/subscriptions/{subscription_id}/change-plan calls aren't limited to the list.
Read. A buyer's subscription lists the options usable now in plan_change_options, each with a subscription_plan summary, and buyer_actions has a new change_plan kind between swap_items and renew. Handle kinds you don't recognize.
Preview.POST /v1/me/subscription-previews accepts mode: "plan_change" with subscription_id, subscription_plan_id, and an optional billing interval pair and quantity. It returns the same plan change preview as the merchant route.
Change.POST /v1/me/subscriptions/{subscription_id}/change-plan (changeMeSubscriptionPlan, SDK me.changeSubscriptionPlan) requires an Idempotency-Key and a full customer session. Access links, including subscription_manage links, can't make it. It returns subscription, order, and order_payment_attempt with 200, including when a now payment is declined. For next_renewal, the plan changes immediately, nothing is charged or credited, and order and order_payment_attempt are null.
Errors. A target outside the subscription's options returns 400 INVALID_REQUEST with INVALID_VALUE. A plan with no usable options returns 409 ACTION_NOT_ALLOWED with reason not_offered.
No new webhook events or emails. Plan changes send subscription.plan_changed and, for now, subscription.payment_succeeded. Editing plan_change_options sends no webhook. See Let buyers change plans.
POST /v1/checkout-sessions now accepts discounts for quick_pay and subscription_plan sessions. Send 1 to 10 entries, each with promotion containing either promotion_id or promotion_code. Flint applies them to the new order and saves the order and session together. A redemption failure creates neither record; a ranking loss returns 201 with a promotion_declined warning.
A promotion selected by ID needs no code, and buyers can't remove it. Account promotion settings still apply, including account code settings for code-type promotions. Set session promotion_config.codes_enabled: false alongside a pre-applied offer when buyers shouldn't add codes.
Saved customer addresses validate US and Canadian subdivisions#
Saved customer addresses previously accepted any nonempty address.state within the character limit. Creating or replacing a saved US or Canadian address now requires a state, province, or territory that belongs to address.country.
This applies to POST /v1/customers/{customer_id}/addresses, PATCH /v1/customers/{customer_id}/addresses/{customer_address_id}, POST /v1/me/addresses, and PATCH /v1/me/addresses/{customer_address_id} when you send address.
Send a code such as TX or ON, an ISO-prefixed code such as US-TX or CA-ON, or a name such as Texas, Ontario, or Québec. Matching ignores case and surrounding whitespace. US territories and military codes AA, AE, and AP remain accepted. Values keep their submitted form after trimming surrounding whitespace.
A state that doesn't belong to its country, such as ZZ for US or TX for CA, returns 400 INVALID_REQUEST with param: address.state and detail code INVALID_VALUE. Correct the state or country before sending the address again. A Canadian address can still omit state.
Countries other than the United States and Canada have no new membership check. This change doesn't check whether postal codes exist, change checkout or order address validation, or rewrite existing saved addresses. Updates that don't send address keep their existing behavior.
ACTION_NOT_ALLOWED reason merchant_managed_receipts is renamed to merchant_managed_email. Update reason matching for receipt refusals. The same reason covers an explicit delivery_mode: email issue or create-and-issue, and scheduling an issue, while customer_email_delivery.invoices is merchant_sends. These requests now return 409 before creating or changing the invoice. Issue with caller_managed or merchant_default, or set the invoices family to flint_sends; scheduling needs flint_sends.
When recipient_email is omitted at draft creation, Flint stores the linked customer's email. The value is visible on the invoice and can be replaced or cleared with PATCH. Explicit null leaves it unset at creation. Issuing a stored draft without a recipient now returns 409 ACTION_NOT_ALLOWED, reason configuration_required, with error_source: merchant and next_actions to PATCH recipient_email. Create-and-issue without a resolved recipient still returns 400 INVALID_REQUEST, detail REQUIRED, at recipient_email. Send Idempotency-Key on invoice issue requests.
customer_email_delivery.order_receipts now covers every payment and refund receipt, including invoices and payments without an order. Failed bank debit notices follow invoices for invoice payments and order_receipts otherwise. Setting the corresponding family to merchant_sends suppresses these emails, including queued deliveries. Subscribe to the family's events to send them yourself.
Page tokens are now signed and bound to their list and caller. Merchant lists bind tokens to the merchant and environment. Buyer lists also bind tokens to the buyer, customer, or session scope. Altering a token or using it outside that scope returns the same invalid-token validation error as a malformed token: HTTP 400 INVALID_REQUEST with an INVALID_VALUE detail on page_token.
Previously issued unsigned tokens are invalid. Restart the list without page_token, then use the response's next_page_token for subsequent requests. Keep filters and sort parameters the same; you may change page_size between pages. Tokens remain opaque: do not parse, construct, or depend on their contents.
These changes apply to every supported API version.
Subscription plans now accept plan_change_options on create and update. Each option names a target subscription_plan_id and sets billing_starts to now or next_renewal. Add up to 25 options in display order.
When you include plan_change_options in PATCH /v1/subscription-plans/{subscription_plan_id}, send expected_version from the plan you read. The array replaces the current options; send [] to clear it. Omitting the field preserves the list, and null is invalid.
Subscription refusals distinguish payment and promotion targeting#
Breaking: initial_payment_pending is removed from the published ACTION_NOT_ALLOWED reasons. Resume on a past_due subscription returns payment_required, including when the first payment has not completed. Update the payment method and create a payment retry. Retained errors that used the old internal resume condition also return payment_required.
An active promotion that does not target a variant covered by a subscription offer now returns 409 ACTION_NOT_ALLOWED with reason variant_not_targeted and no current_status. When the caller can read variants, details[0].blocking_resources contains the uncovered variant's resource_id with resource_type: "product_variant". Widen the promotion's targeting to this variant, or remove the variant from the offer.
An unavailable promotion still returns reason unsupported_state with its current_status. See subscription offers.
Breaking change
API
Subscriptions
Trial subscriptions activate after the first charge succeeds#
Breaking: active now means the first charge succeeded. When a trial ends, Flint charges the first period and the subscription stays trialing while that charge is pending. Previously it became active first. A successful charge makes it active and sends subscription.payment_succeeded and subscription.activated.
Breaking: a declined first charge moves trialing straight to past_due. The subscription never reads active in between, and subscription.past_due follows the failed payment path. When a retry succeeds, the subscription becomes active and Flint sends subscription.activated exactly once.
Pending first charges for other starts are unchanged: an immediate start stays incomplete and a scheduled start stays scheduled.
During a trial, current_period_start_at and current_period_end_at describe the first paid period, which starts at trial_end_at. Flint adds no trial_start_at field.
If you gate paid access on status: "active" or on subscription.activated, no change is needed. If you use trialing to check whether a trial is still running, read trial_end_at instead. See Free trials.
Lifecycle actions Flint accepts now. complete is offered while awaiting_upload or processing and remains accepted for completed files, returning the completed file.
Filter by the original Idempotency-Key, after trimming surrounding whitespace.
Webhook events
23 additions
Field
Category.version
Persisted owned-state version.
Field
CustomerDeletionRequest.supported_actions
Lifecycle actions Flint accepts now, independent of the caller's permissions.
Field
DeliveryRateCallback.signing_methods
Signing methods enabled for callback HTTP requests. jwt sends Authorization: Bearer with a Flint-signed token whose aud is this delivery_rate_callback_id; hmac sends webhook-signature and signing key IDs.
Field
ExpandedPayoutDestinationSummary.version
Persisted version of this resource's owned state.
Field
ExpandedPayoutSummary.supported_actions
Lifecycle actions Flint accepts now.
Field
GiftCardRedemption.supported_actions
Lifecycle actions accepted for the stored redemption, independent of the caller's credentials. capture is available only before expires_at; cancel remains available until the reservation is resolved.
Field
InvoiceDeliveryAttempt.invoice_id
ID of the invoice this delivery attempt belongs to.
Field
MerchantBillingInvoice.applied_credit_money
Credit applied to the invoice: the sum of its credit line items.
Breaking change
API
Catalog
Subscriptions
Money-movement
Payment-links
Inventory
Delivery
Boolean and currency field renames and integer bounds#
Update response readers, request fields, query filters, and webhook handlers to use these names:
Resource or schema
Before
After
PayoutDestination and ExpandedPayoutDestinationSummary
default_for_currency
is_default_for_currency
Subscription and BuyerSubscription
awaiting_billing_schedule
is_awaiting_billing_schedule
ProductVariant
images_inherited
is_inheriting_product_images
PublicPaymentLinkResult
sales_ended
is_past_sales_end
APIRequestLogReproduction
redactions_present
has_redactions
Product, ProductVariant, Bundle, BundleComponentVariantSummary, and PublicResolvedBundleVariantSummary
available_for_sale
is_available_for_sale
PayoutSettings and UpdatePayoutSettingsRequest
minimum_balance_by_currency
minimum_balance_currency_options
Use is_default_for_currency on GET /v1/payout-destinations and is_awaiting_billing_schedule on GET /v1/subscriptions. Send payout minimum balances as minimum_balance_currency_options on PATCH /v1/payout-settings. The map still uses currency codes as keys, and a null value still clears that currency's minimum. The old field and filter names are no longer accepted.
The renamed response fields also apply to expanded resources, buyer subscription responses, and webhook resource snapshots. Field meanings and values stay the same.
Published integer bounds now stay between -9007199254740991 and 9007199254740991, inclusive. This tightens the bounds for inventory counters, physical versions, observation sequences, and inventory level update fences. Integer request fields, including delivery business-day ranges, and version query fences reject values outside this range with 400 INVALID_REQUEST, an INVALID_VALUE detail, and the affected field in param. Send an integer within the range; sending a string does not bypass validation.
Breaking change
API
Customers
Webhooks
Read customer email preferences before sending email#
Use GET /v1/customers/{customer_id}/email-preferences or POST /v1/email-preferences/lookup with customers.read to check whether a buyer accepts shipping updates and checkout reminders before sending your own email. Both operations return the same response shape. Merchants cannot change these preferences.
The shared email-preferences response schema now allows customer_id and version to be null. Email lookup returns null for both when the address has no customer record. Customer reads and authenticated /v1/me/email-preferences reads and updates continue to return a customer ID and a positive version. Update clients generated from the schema to handle the nullable fields.
Subscribe to customer_email_preferences.updated to receive the current preferences when a customer's preference version advances, including when their email address changes. Check preferences again before every send, including for guest addresses. Opt-outs can survive customer deletion; deletion itself does not send a preference event.
Breaking change
API
Customers
Customer sessions distinguish missing and deleted customers#
POST /v1/customers/{customer_id}/sessions/revoke previously returned 200 with revoked_count: 0 for an unknown customer or a customer outside the key's merchant, mode, or sandbox. It now returns 404 RESOURCE_NOT_FOUND with param: customer_id. Check the ID and selected environment instead of treating that response as a successful revocation. An existing customer with no sessions to revoke, including a retained deleted customer, still returns 200 with revoked_count: 0.
POST /v1/customer-sessions previously returned 404 RESOURCE_NOT_FOUND for a retained deleted customer. It now returns 409 ACTION_NOT_ALLOWED for customers with status: deleted or deletion_processing, with details[0].reason: terminal_status, resource_type: customer, and current_status naming the customer's status. remediation.retry is none, and no session or refresh token is created. Handle this conflict separately from a missing customer. Create a new customer before creating a session for a returning buyer whose customer was deleted.
Session creation still returns 404 RESOURCE_NOT_FOUND for an unknown customer or one outside the key's merchant, mode, or sandbox; that response now names param: customer_id.
Breaking change
API
Payments
Orders
Webhooks
Capture deadlines include order resource guarantees#
PaymentIntent.authorization_expires_at, order payment attempt deadlines, and Order.authorization_amounts.expires_at now publish the earlier of the provider capture deadline and any order resource guarantee. Previously they published only the provider deadline, even when Flint released order resources earlier. Payment review snapshots and webhook copies publish the same effective deadline.
Orders that reserve inventory, coupon or promotion use, payment-link capacity, fulfillment selections, or gift-card value have a resource guarantee of at most 24 hours from the payment attempt's start, or an earlier reservation deadline. Resource-free holds keep their provider deadline. Schedule capture from the published timestamp, even if you previously expected a multi-day hold.
When that deadline lapses, Flint expires the hold and sends payment_intent.expired. Previously a resource-guarantee lapse could send payment_intent.canceled with cancellation_reason: abandoned. Update cancellation handlers that treated those lapses as abandoned payments. The matching order payment attempt now reaches its expiry outcome; expiry does not discharge order debt.
A new capture at or after the deadline returns 409 ACTION_NOT_ALLOWED, reason authorization_expired, before contacting the provider. If cleanup has already released the hold, the terminal state can instead return terminal_status. Retrying a completed capture with its original idempotency key recovers the original result.
Error schemas distinguish top-level and validation detail codes#
ErrorObject.code now lists only top-level error codes. The x-flint-error-codes extension on operations and responses also lists only top-level codes.
ErrorDetail.code is now a union: on INVALID_REQUEST, it uses ErrorDetailCode (REQUIRED, INVALID_VALUE, UNKNOWN_FIELD, or NOT_ALLOWED); on other errors, it repeats the top-level code. Update schema readers that expect one enum containing both sets. The error envelope and its wire values are unchanged.
ErrorObject.remediation is required and non-null. API_VERSION_RETIRED appears in operation error lists only while a published API version is retired. Operations that require no request authentication no longer list errors added by authentication middleware; credential exchanges retain the errors their handlers return.
The error catalog marks REQUEST_CANCELED as a log-only 499 protocol_error. No client receives that response.
POST /v1/fulfillments/{fulfillment_id}/transitions is removed. Send POST to the route that matches the former action, and remove action from the body:
Previous action
New route
accept
POST /v1/fulfillments/{fulfillment_id}/accept
schedule
POST /v1/fulfillments/{fulfillment_id}/schedule
start
POST /v1/fulfillments/{fulfillment_id}/start
mark_preparing
POST /v1/fulfillments/{fulfillment_id}/mark-preparing
mark_picked
POST /v1/fulfillments/{fulfillment_id}/mark-picked
mark_packed
POST /v1/fulfillments/{fulfillment_id}/mark-packed
mark_ready
POST /v1/fulfillments/{fulfillment_id}/mark-ready
dispatch
POST /v1/fulfillments/{fulfillment_id}/dispatch
complete
POST /v1/fulfillments/{fulfillment_id}/complete
mark_no_show
POST /v1/fulfillments/{fulfillment_id}/mark-no-show
fail
POST /v1/fulfillments/{fulfillment_id}/fail
cancel
POST /v1/fulfillments/{fulfillment_id}/cancel
hold
POST /v1/fulfillments/{fulfillment_id}/hold
release_hold
POST /v1/fulfillments/{fulfillment_id}/release-hold
Each body keeps the fields of its former action branch, such as reason on hold and release_quantity on fail, and still accepts expected_version, occurred_at, and reason_message. Each route returns the updated Fulfillment, keeps its scope, and takes an optional Idempotency-Key. For example:
The operation IDs are acceptFulfillment, scheduleFulfillment, startFulfillment, markFulfillmentPreparing, markFulfillmentPicked, markFulfillmentPacked, markFulfillmentReady, dispatchFulfillment, completeFulfillment, markFulfillmentNoShow, failFulfillment, cancelFulfillment, holdFulfillment, and releaseFulfillmentHold.
supported_actions values don't change. Each value is the route segment with hyphens written as underscores, so mark_no_show is /mark-no-show.
Unpaid orders list no actions. While a fulfillment's order isn't paid, Flint refuses every fulfillment action with 409 ACTION_NOT_ALLOWED and reason unsupported_state, and the fulfillment's supported_actions is now []. It lists actions again once the order is paid. The list comes from the fulfillment, its order, and any hold on it, never from your credential or scopes; a caller without permission for a route gets 403 INSUFFICIENT_SCOPE. Payment holds behave as before: only cancel and hold stay in the list, and other actions return 409 ACTION_NOT_ALLOWED with reason on_hold.
Package and inventory /transitions routes are unchanged in this release.
Regenerate API clients and update fulfillment calls, supported_actions handling, and any code that sends action to the old route. See Fulfill and ship orders and Send an action.
POST /v1/gift-cards/{gift_card_id}/cash-out now refuses a card with any freeze, restriction, or unresolved funding dispute. Previously, a frozen card could still be cashed out. The rule covers the whole card, including value from undisputed loads. Restricted cards no longer list cash_out in supported_actions on reads, command results, or webhook snapshots.
Cash-out and redemption refusals on restricted cards return 409 ACTION_NOT_ALLOWED with details[0].reason: restricted. For redemptions, this replaces the previous unsupported_state reason. Handle restricted when deciding how to resolve the refusal.
details[0].restrictions uses the same shape as GiftCard.restrictions. Funding disputes also appear in details[0].blocking_resources with resource_type: dispute when your credential can read disputes. The error has error_source: merchant and remediation.retry: none. Lift the merchant freeze, or resolve the funding dispute in blocking_resources, then retry. There is no override.
Check that the card offers cash_out before paying the holder outside Flint. An eligible cash-out must still fit the card's unreserved value. Flint records the cash you attest you paid; it does not send cash. See cash-out eligibility.
Breaking change
API
Gift-cards
Gift card rotation cancels unsent notifications and money fields share Money#
Rotating a gift card code now cancels its scheduled and pending notifications for the previous code when sending has not started. Each cancellation emits gift_card_notification.updated with status: canceled and status_reason: credential_rotated. Notifications already being sent or accepted by the email service are left as they are. Include notification in the rotation request or resend afterward if the recipient needs the new code.
Every gift card notification response and webhook snapshot now includes the nullable status_reason field. It is null unless a reason applies. Treat its vocabulary as extensible.
Gift card configuration, purchase, line item update, and allocation acceptance money fields now reference the shared Money schema. Regenerate clients to use the shared types. The JSON format and server validation are unchanged: gift card purchases use USD and amounts from 1 to 200000 cents. Allocation totals can be zero and do not have the per-purchase cap.
An idempotency key now names one request within its namespace and operation. Reusing the key to update a different customer or renew a different subscription returns 409 IDEMPOTENCY_KEY_REUSED. Previously, some routes treated each path resource as a separate key scope. An identical retry still replays. The same key on different operations names independent requests.
Path parameters and the body are compared with the original request. A parent ID also participates when a child create uses a top-level route. Save one key per action, and use a new key when the target or request changes.
An order payment uses one idempotency key namespace across the merchant's credentials. Routes that create credential-bound secrets, such as API keys and customer access links, keep their credential scope.
On optional and required routes, a blank Idempotency-Key now returns 400 INVALID_REQUEST with detail INVALID_VALUE at Idempotency-Key. Repeated header lines return detail NOT_ALLOWED, even when their values match. Previously, a blank value could disable protection on an optional route, and repeated headers selected the first value. Send the header once with a nonblank key. Commas within a single header line remain allowed. Routes that ignore idempotency keys continue to ignore the header.
A finished request retried through a different Flint API than the one that ran it never runs again. It returns 409 IDEMPOTENCY_KEY_REUSED with reason transport_mismatch, and the result isn't converted between APIs. Get the result from the API that made the request, or send a new request with a new key. A request still running returns IDEMPOTENCY_KEY_IN_PROGRESS, as before.
Retained records created before this change still protect retries under their original matching rules, whichever Flint API wrote them. See Scope and lifetime.
Invoice due_date, payment_due.due_date, and schedule entry due.due_date replace due_at. Send and read dates as YYYY-MM-DD in the invoice's published timezone. Without a configured timezone, Flint uses UTC. The old timestamp fields are rejected on writes and omitted from reads, including buyer reads and expanded invoice summaries.
Invoice lists replace due_after and due_before with due_date_from (inclusive) and due_date_to (exclusive). Sort by due_date instead of due_at. Update saved queries and restart pagination with the new sort and filters.
A schedule entry stays due throughout its due date. It becomes overdue, and eligible for late fees, only after that date ends. Automatic collection runs at the later of issue and the start of the due date. An at_issue deposit still charges at issue.
Reminder rules on or before the local issue date are skipped. For email delivery, automatic reminders and late fee notices or assessments wait for the first invoice email to be sent. Each action stops waiting without running if the first email is still unsent 24 hours after issue. An on_receipt payment term with a late fee requires grace_period_days of at least 1.
Past dates sent on create or PATCH return 400 INVALID_REQUEST with detail INVALID_VALUE and param on the date field. Issuing a stored draft after its due date ends returns 409 ACTION_NOT_ALLOWED with reason configuration_required and next_actions to PATCH the draft.
These changes apply to all supported API versions. Replace timestamp fields and values in your invoice requests, responses, filters, and sorting before upgrading your integration.
Merchant invoices, invoice late fees, invoice manual payments, credit notes, and credit note allocations now return a required supported_actions array. Expanded invoice summaries and webhook data.object snapshots carry the same action list. Lifecycle refusal details include supported_actions alongside current_status and the current_resource reference. An empty array means no lifecycle action is available.
The list follows stored resource state, including collection settings, invoice schedules, collection blocks, issued credit notes, and credit allocations or refunds. It does not depend on your API key's scopes. A listed action still requires its route's permissions. Buyer invoice and credit note projections omit merchant actions.
Invoice actions are issue, collect, void, and mark_uncollectible. Late fees support waive, manual payments and credit note allocations support reverse, and credit notes support issue and void. Each value names its existing action route, with underscores replacing hyphens.
Invoice and credit note status void is replaced by voided, including buyer projections, list filters, expanded invoice summaries, refusal status facts, and the snapshots for invoice.voided and credit_note.voided. The action and route remain void. Update comparisons, filters, and webhook consumers to use voided. Dashboard invoice CSV exports now write voided in the status column instead of void.
Invoice manual payment status is a closed enum with recorded and reversed. Its terminal value is reversed, published as x-flint-terminal-values in OpenAPI. Invoice and credit note status metadata identifies their terminal voided value; invoice uncollectible is also terminal.
These changes apply to all supported API versions. Update generated clients and resource fixtures before upgrading. Continue sending an Idempotency-Key when issuing an invoice with POST /v1/invoices/{invoice_id}/issue.
Repeating DELETE /v1/locations/{location_id} now returns the archived Location with 200 OK. Its version, created_at, and updated_at stay unchanged. If you send expected_version, it must still match the current version; a stale fence returns 409 VERSION_CONFLICT.
PATCH /v1/locations/{location_id} on an archived Location now returns 409 ACTION_NOT_ALLOWED with details[0].reason: archived, current_status: archived, and error.remediation.retry: none. Previously, PATCH and repeated DELETE returned 404 RESOURCE_NOT_FOUND for archived Locations. Missing IDs and Locations outside your merchant or environment still return 404.
Location responses no longer include validation_status or normalized_address. Flint stores the address you supply and does not verify or normalize it. Remove reads of these fields and use address for the Location's postal address.
Update integrations that read these fields. These changes apply to merchant and buyer responses, expanded order summaries, return previews, and the matching webhook objects.
On orders, settlement_amounts.credit_money becomes settlement_amounts.overpaid_money: money collected beyond what is owed and not yet refunded. settlement_amounts.balance_money is removed. Read outstanding_money for what remains owed and overpaid_money for the excess held. If you need the former signed balance, subtract overpaid_money from outstanding_money.
Order settlement_amounts now uses OrderSettlementAmounts, which extends the shared SettlementAmounts with overpaid_money and settled_tip_money. The shared core contains paid_money, refunded_money, net_collected_money, written_off_money, and outstanding_money.
On returns, financial_summary.credit_money becomes financial_summary.credit_adjustment_money. On return resolutions and their previews, credit_money becomes credit_adjustment_money. These fields measure credit adjustments, separately from deductions and refunds.
On merchant billing invoices, credit_money becomes applied_credit_money. It measures the credit applied to the invoice. total_money remains subtotal_money minus that applied credit.
total_money on order and invoice line items now uses Money instead of SignedMoney, including buyer order line items. Every supported line total is non-negative. The JSON amount and currency representation stays the same; update generated client types that referenced SignedMoney.
The affected reads include /v1/orders, /v1/me/orders, /v1/returns, /v1/me/returns, /v1/return-resolutions, /v1/invoices, and /v1/merchant-billing-invoices, with their detail routes and return-resolution previews. Order, return, return-resolution, and merchant-billing-invoice webhook objects use the same fields as their reads.
client_secret_enabled now controls first issuance for existing partner apps. Previously, PATCH /v1/partner-apps/{partner_app_id} with client_secret_enabled: true returned 400 INVALID_REQUEST, and POST .../rotate-secret issued the secret. Now PATCH enables secret authentication, issues the secret when none exists, and returns the PartnerAppWithSecret data kind with one-time data.client_secret. Save it from that response; reads, lists, and later updates omit it. If issuance fails after the app configuration changes, Flint restores the previous configuration.
rotate-secret now only rotates an existing secret. With no issued secret, it returns 409 ACTION_NOT_ALLOWED with reason secret_not_issued, and next_steps points to PATCH with client_secret_enabled: true. Replace first-secret rotation calls, including calls that re-enable a disabled secret, with that PATCH. Setting client_secret_enabled: true when a secret already exists leaves it unchanged.
Dashboard sessions need fresh identity verification to enable a secret through PATCH, including when retrying the issuing request. Live API keys continue to work without dashboard verification.
Use an Idempotency-Key on the issuing PATCH. If you lose the response, retry the identical request with the same key and the same API key or dashboard session. A replay returns the secret only to the credential that issued it, subject to the one-time secret replay limits. Another credential never receives it.
Creating an app with client_secret_enabled: true, disabling secrets with false, and rotating an existing secret keep their existing behavior. These changes apply to every supported API version. See Enable a client secret and the partner app reference.
Breaking change
API
Payouts
Payout destination changes recover after interrupted requests#
PATCH /v1/payout-settings, PATCH /v1/payout-destinations/{payout_destination_id}, and DELETE /v1/payout-destinations/{payout_destination_id} now return 409 OPERATION_IN_PROGRESS when another change to the same record is running. Previously, this condition returned CONCURRENT_MODIFICATION before provider dispatch or 500 IDEMPOTENCY_RECOVERY_REQUIRED after dispatch. The competing request makes no change. Wait for Retry-After: 1, then resend the identical request with its original key. An identical request already running returns 409 IDEMPOTENCY_KEY_IN_PROGRESS.
Retry an interrupted destination change with its original request and key. Flint resumes a metadata update with the identical provider request within the recovery window. For an interrupted archive, Flint checks whether the destination still exists and completes its removal if needed. A proven provider rejection releases the destination for another change. IDEMPOTENCY_RECOVERY_REQUIRED remains for outcomes Flint cannot safely determine, including expired metadata recovery windows and older interrupted changes without recovery information.
PayoutDestination.disabled_reason no longer lists disabled_by_merchant_request or superseded_destination_session_completed. Flint did not produce either value. Remove those cases from exhaustive enum handling; use the remaining published values and keep a fallback for future values.
Breaking change
API
Payouts
Balances
Payout readiness requires an active default destination#
Payout readiness and Balance.payouts_enabled now require an active default payout destination for the payout currency, alongside the existing account and capability requirements. Previously, readiness could report ready and a balance could enable payouts with a non-default or unusable destination. Integrations should wait for readiness and check the balance flag before offering payouts.
Connected bank accounts that are usable for payouts now report active instead of verification_required in both live and test mode. A verification problem still reports verification_required, and a bank that rejected a payout still reports failed. Existing stored destinations keep their status until the next provider reconciliation writes the correction. That write can emit payout_destination.updated; observing the same state again does not emit another update. Read repairs continue to suppress webhooks.
Sandbox preparation establishes the test bank as its currency's default and confirms its active status and default through provider reads before finishing. New sandboxes need no manual bank verification step.
PayoutSettings.default_payout_destinations is now always present and is {} when no defaults exist. This also applies to the resource in payout_settings.updated webhook payloads. It remains read-only. See Payouts.
Products previously had no total limit on non-archived variants. A product now supports at most 250 active and inactive variants combined. Archived variants don't count. This limit applies to POST /v1/products/{product_id}/variants and POST /v1/products; the latter still accepts at most 100 variants in one request.
A create that would exceed the limit returns 409 LIMIT_REACHED with details[0].reason: product_variants, facts limit and current_count, and remediation.retry: none. Archive a variant you no longer sell, then add the new one.
GET /v1/products and GET /v1/products/{product_id} now accept:
expand=variants: the product's complete active and inactive variants as full ProductVariant objects without nested expansions, ordered by position then variant_id. The array's length equals variant_count; an archived product returns variants: []. This needs commerce.products.read.
expand=variants.modifier_set: the same variants with each variant's own modifier set expanded. This also needs commerce.catalog.read.
A product list page holds at most 500 expanded variants. Flint ends the page before the first product that would exceed the budget, always returns at least one product, and never splits a product's variants across pages. page_size is a maximum number of products; follow next_page_token after a short page to continue from the last product returned.
The POST /v1/products response continues to include variants without expand. Webhook objects never include it. Every variant change, including attaching or changing a variant's modifier set, advances its product's version and updated_at.
To backfill a catalog, page GET /v1/products?status=active,inactive,archived&expand=variants and replace each product's stored variant set with its expanded array. Use updated_after for later reads. See Backfill and recover and Product variant page budget.
Quantity targets on POST /v1/refunds now round their share of the line's remaining paid value half up in the currency's minor units, matching credit-note quantity corrections. Flint then rounds the proportional tax and discount shares half up and balances subtotal. Previously it truncated subtotal, discount, and tax separately and derived the total from those components.
For a three-unit line with subtotal 4,497, discount 450, and tax 263, the first one-unit refund changes from 1,436 to 1,437 minor units. Separate one-unit refunds are 1,437, 1,437, and 1,436. The final quantity takes every component's remaining minor units, so the refunds sum to the line's 4,310 total.
New Return line values, previews, and resolution allocations use the same rule. Stored refunds and Return commitments keep their amounts. Retrying a refund with its original idempotency key returns its stored result.
Use the returned amount_money and line_item_allocations for reconciliation. Update any calculations that predict a quantity refund by truncating its components separately. Refunds describes the rounding rule.
Breaking: Sandbox buyer emails to addresses outside your team can now be suppressed when the sandbox reaches its daily limit. Invoice delivery attempts and fulfillment notifications report status: suppressed and suppression_reason: sandbox_daily_limit_reached.
sandbox_daily_limit_reached: Not sent because the sandbox reached its daily limit of buyer emails to addresses outside your team. Send to a team address, or wait for the next UTC day.
Treat suppression_reason as extensible and handle values you do not recognize. A new reason does not introduce a new message status.
Breaking change
API
Api-keys
Sandboxes
Disputes
Scope requirements and CLI sessions use explicit context rules#
CLI OAuth sessions always contain separately approved merchant and environment contexts. On POST /v1/oauth/device/authorize, omitting session_mode now means contexts. Any supplied value other than contexts, including an empty value, returns 400 invalid_request with session_mode in the error description.
Legacy single-context sessions can no longer exchange device codes, refresh tokens, or authenticate API requests. Sign in again with Flint CLI v0.10 or later. Token responses include oauth_session_id and context_id; send the selected context_id when refreshing. Contexts sessions keep their existing token lifetimes and rotation rules.
Redeeming a device code for a superseded reauthorization review now returns 400 expired_token, replacing invalid_grant. Start a new review. The existing session remains active and can still refresh; invalid_grant continues to identify a session that has ended.
For operations that require several scopes with x-flint-required-scopes-mode: all, x-flint-required-scopes now lists the base scopes alone. For example, listCreditNoteRefunds publishes commerce.credit_notes.read and commerce.refunds.read. Evaluate each requirement using its x-flint-scopes[].implied_by alternatives, then require every entry to pass. Lists with mode any continue to include the write alternatives directly. payments.disputes.write now also satisfies payments.disputes.read.
Sandbox archive requests with a malformed sandbox_id now return 400 INVALID_REQUEST naming sandbox_id, rather than looking up the malformed ID. CreateSandboxRequest.scopes and IssueSandboxAPIKeyRequest.scopes now publish only the scopes accepted on test keys; live-only sandbox and partner-app management scopes are excluded.
The remaining lists that used older page tokens now use the shared keyset format. Each new token records the last row's sort value and ID, so continuing the list does not need to read that row again. List ordering and filters stay the same.
This applies to inventory items, levels, adjustments, allocation policies and their revisions, reservations, counts, receipts, transfers, and locations; merchant billing invoices and payment method domains; fulfillment revocations, selections, and quotes; credit notes and their allocations, invoice events, manual payments, payment attempts, and payment terms; order and payment activity; account orders and resource timelines; returns and their line items, receipts, inspections, dispositions, resolutions, policies, policy versions, and reasons; risk rule versions; subscription delivery migration failures; and payout destinations, balance transactions, and payouts.
Outstanding tokens on these lists return an invalid-token validation error with HTTP 400. Restart the list without page_token, then use the new response's next_page_token for subsequent requests. Keep the filters and sort the same. You may change page_size between requests where the list accepts it.
These changes apply to every supported API version.
Breaking change
API
Subscriptions
Subscription recovery applies the configured dunning end action#
When a recorded payment retry fails after subscription billing recovers from an interruption, Flint now applies your configured dunning_end_action: cancel, pause, or notify_only. Previously, this recovery path always left the subscription past_due for manual recovery, even when you configured cancellation or pausing.
Externally scheduled subscriptions use external_dunning_end_action, which defaults to notify_only. Recovery keeps the existing retry limit. Permanent declines still require a manual payment retry after the buyer updates their payment method.
WebhookDeliveryAction.delivery_status, returned by webhook delivery and resend actions, changes from an extensible enum to the closed message_status vocabulary. It still returns pending, delivered, failed, or suppressed, matching WebhookDelivery.status.
Update generated clients that distinguish closed and extensible enums. Continue reading delivery_status for the message's current outcome and attempt_status for the individual attempt's outcome. The attempt status remains extensible.
Closed status properties also publish x-flint-terminal-values in OpenAPI. Each listed value's description ends with "This status is final." An empty list means no value is guaranteed final. A succeeded refund or payout can still change. See Statuses & lifecycles for the generated table.
Webhook endpoint responses now include created_by, a resource reference to the API key, user, partner app, or workload identity that created the endpoint. The field is returned on create, get, and list. It is absent when Flint doesn't know the creator, including every endpoint created before 2026-10-31. Existing endpoints are not backfilled.
GET /v1/webhook-endpoints accepts a created_by filter that matches the creator's exact ID. Use it during leaked key response to list the endpoints a key created. Endpoints without created_by never match the filter.
This change is additive. Existing requests and responses work unchanged.
Bundles no longer accept or return taxable or line_item_tax_category (tax_category on older API versions). Remove both fields from POST /v1/bundles and PATCH /v1/bundles/{bundle_id} requests and from code reading bundle responses or bundle webhook events. Sending either field now returns 400 INVALID_REQUEST with detail code UNKNOWN_FIELD.
A bundle line now takes the taxable and line_item_tax_category values shared by its component variants. All components must share both stored values. An unset category means the merchant default and equals only another unset category, even if an explicit category currently matches that default. The sold line's shape stays the same, and lines already sold keep their recorded tax treatment.
Bundle create and component replacement compare each component with the first component in the request. A difference returns 400 INVALID_REQUEST with a NOT_ALLOWED detail at each differing components[index].variant_id, naming the differing attribute. A variant or product change that would make an existing bundle mixed returns 409 ACTION_NOT_ALLOWED with reason mixed_tax_treatment, retry mode none, and the bundles in blocking_resources. Remove a component from its bundle before changing its tax treatment, or choose components that already share the same treatment. Adding an older mixed bundle to an order returns 409 ACTION_NOT_ALLOWED with reason configuration_required until its components share the same treatment.
New variants of a product_type: digital product now store digital_goods when line_item_tax_category is omitted. This applies to default_variant and variants on POST /v1/products, and to POST /v1/products/{product_id}/variants. Reads return the stored category, and you can edit it. Send an explicit category to choose another treatment. Changing an existing product to digital fills only its variants' unset categories with digital_goods and advances their versions; the whole change is refused if it would make a containing bundle mixed. Other existing rows are unchanged.
Buyer payments and refunds omit merchant references and metadata#
Buyer payment intent and refund responses omit metadata and external_reference_id. Payment intents previously returned the merchant's external_reference_id and an empty metadata object to buyers. Refund responses already omitted both fields, but their buyer schema still declared them.
This applies to /v1/me/payment-intents, /v1/me/refunds, their individual reads, and payment or refund views embedded in buyer responses. Customer sessions, checkout credentials, and invoice access tokens receive the same omissions. BuyerPaymentIntent and BuyerRefund no longer declare either field.
Remove reads of these fields from buyer-facing integrations. Read merchant references and metadata on your backend with a merchant credential when needed. Merchant payment intent and refund responses keep both fields.
Breaking change
API
Catalog
Promotions
Gift-cards
Customer-accounts
Promotion codes, gift card loads, and buyer transactions use top-level routes#
Breaking: update integrations to use these routes and body fields. The nested routes are removed.
Old
New
POST /v1/promotions/{promotion_id}/codes
POST /v1/promotion-codes, with promotion_id in the body
GET, PATCH, or DELETE /v1/promotions/{promotion_id}/codes/{promotion_code_id}
The same method at /v1/promotion-codes/{promotion_code_id}
POST /v1/gift-cards/{gift_card_id}/loads
POST /v1/gift-card-loads, with gift_card_id in the body
expected_version on gift card load and redemption creates
expected_gift_card_version, still checked against the gift card's version
GET /v1/me/gift-cards/{gift_card_id}/transactions
GET /v1/me/gift-card-transactions?gift_card_id={gift_card_id}
List one promotion's codes with GET /v1/promotion-codes?promotion_id={promotion_id}. List one card's loads with GET /v1/gift-card-loads?gift_card_id={gift_card_id}, and retrieve a load with GET /v1/gift-card-loads/{gift_card_load_id}. Both parent ID filters match exactly.
Buyer transaction history still requires saved access to the card and returns the same anonymous entries and pagination. Keep the same gift_card_id and buyer session when continuing a page. Other buyers' saved cards are not accessible.
Keep using expected_version on gift card updates and commands, and on redemption capture and cancel. Only load and redemption creates rename the fence.
After a create moves to its top-level route, reusing one Idempotency-Key across two parents returns IDEMPOTENCY_KEY_REUSED. Use a separate key for each distinct create, and reuse that key only when retrying the same request for the same parent.
Added:product_id is required and non-null beside variant_id on BundleComponentVariantSummary, PaymentLinkAvailableVariant, ProductVariantMatch, PublicResolvedBundleVariantSummary, ReturnReplacementLineItem, and SubscriptionPlanSwapVariant. Product variant routes stay under /v1/products/{product_id}/variants.
Breaking change
API
Products
Bundles
Bundle delivery readiness and catalog position defaults#
Bundle reads and catalog writes now use these rules across supported API versions:
available_for_sale previously checked that a bundle was active, had components, and every component's variant and product were active. It now also requires the bundle's aggregate delivery_configuration_status to be different from action_required. This applies to GET /v1/bundles and GET /v1/bundles/{bundle_id}. Configure delivery for every component that needs it before offering the bundle for sale. Stock is still excluded from this field.
A bundle with no components previously reported delivery_configuration_status: configured and matched no delivery configuration status filter. It now reports not_applicable and appears when listing bundles with delivery_configuration_status=not_applicable. An empty bundle still has available_for_sale: false.
Omitted position values previously defaulted to 0. Options, option values, and variants supplied to POST /v1/products, and options and values in full replacement arrays, now default to their zero-based array index. Explicit positions, including 0, are preserved. Send explicit positions if you need the previous order.
POST /v1/products/{product_id}/variants previously defaulted an omitted position to 0. It now appends after the product's highest variant position, or uses 0 for the first variant. Concurrent creates with omitted positions receive separate positions. Sparse variant updates continue to keep the current position when position is omitted.
Text modifier length errors now describe the existing limits in UTF-8 bytes after trimming surrounding whitespace. For list modifier groups, a rejected required override now tells you to set min_selected: 1 to require a selection; required applies only to text groups.
Breaking change
API
Catalog
Category reference counts include ended promotions and policy history#
Breaking:Category.targeting_reference_count now counts every promotion that has not been deleted, every return reason, and every return policy whose revisions reference the category. Previously, the count excluded promotions past their end time or use limit and omitted references present only in historical return policy revisions. Those references already prevented DELETE /v1/categories/{category_id}; they now appear in the count too.
Each referencing resource counts once. Several rules in a promotion or several revisions of one return policy that reference the category add one to the count, not one per rule or revision. Deleted promotions do not count.
Check targeting_reference_count, assigned_product_count, and assigned_bundle_count before deleting a category. If any is above zero, deletion returns 409 RESOURCE_IN_USE. All three must be zero before you can delete the category. Publishing a new policy revision without the category does not clear a historical revision's reference.
Promotion redemptions and releases no longer advance the category's version, because usage no longer changes its reference count. Category updates and writes that change membership or targeting still advance it. Integrations should use the counts to check for deletion blockers and read the promotion itself to track its remaining uses.
Breaking change
API
Checkout
Customers
Merchants
Subscriptions
Checkout, credential, and merchant lifecycle actions#
Breaking: delivery migrations use processing.SubscriptionDeliveryMigration.status changes from running to processing in API responses and webhook snapshots. Update status comparisons and send status=processing to GET /v1/subscription-delivery-migrations. pending and completed keep their meanings.
Breaking: tax connection actions describe the resource state.TaxConnection.supported_actions lists the same actions for every caller, including read-only API keys and dashboard users. Check your caller's permissions separately before offering a connect or disconnect control. Calling either action still requires settings.write.
Checkout sessions, customer verifications, customer sessions, customer deletion requests, API keys, partner app installs, partner environment grants, files, and payment reviews now publish a required supported_actions array. Its values name the lifecycle actions Flint accepts for the resource's current state, and an empty array means none are available. The list does not grant permission to perform an action.
Breaking: an opposite deletion decision names the locked field. When POST /v1/customer-deletion-requests/{customer_deletion_request_id}/resolve refuses a decision that conflicts with the stored decision, 409 ACTION_NOT_ALLOWED now carries reason field_locked and param: decision instead of unsupported_state. Repeating the stored decision remains accepted, so resolve remains in supported_actions.
Breaking: payment-link resolution uses the buyer checkout schema.POST /v1/payment-links/{payment_link_id}/resolve returns BuyerCheckoutSessionWithSecret instead of CheckoutSessionWithSecret. Buyer checkout sessions omit merchant supported_actions. Nested payment errors use BuyerErrorRemediation, which omits merchant next_actions; use its retry and next_steps guidance. Update generated response types to the buyer schema.
Breaking change
API
Disputes
Balances
Merchant-billing
Dispute fees follow the money deducted from your balance#
Dispute balance transactions now include a processor dispute fee deducted from your balance in fee_money. Previously, dispute rows reported fee_money of 0, omitted that deduction from net_money, and could also carry a card_dispute event fee in merchant billing.
These behavior changes apply to GET /v1/balance-transactions, the single-transaction read, balance transaction webhooks, and balance transaction reports:
A dispute row with amount_money of -4200 and a 1500 processor fee has fee_money of 1500 and net_money of -5700. A dispute fee on a dispute_reversal row follows the same rule: net_money is amount_money minus fee_money.
A principal-only reversal has fee_money of 0. If the processor returns the fee on that reversal, fee_money is negative. If it posts a separate fee credit, that credit appears as its own row. A dispute's won status alone doesn't return the fee.
A card dispute fee deducted directly from your balance carries no additional card_dispute event fee. That event fee remains available in merchant billing only when Flint paid the processor's fee.
Use each row's actual fee_money and sum net_money to reconcile your balance. Remove assumptions that disputes always have zero fees or that winning always returns the dispute fee. Read merchant billing for any event fee and Reconcile the result for a worked example.
Breaking change
Docs
Mcp
Docs MCP tools renamed, and docs Markdown is read in bounded parts#
Breaking: the docs MCP server at https://developers.withflintpay.com/mcp replaces its tools, and /llms-full.txt is gone.
Tools.get_page, list_endpoints, and get_endpoint are removed. search_docs and search_flint_help keep their names.
Removed
Use instead
get_page with path
read_doc with target, a docs path or URL
list_endpoints with resource
list_operations with resource, path_prefix, or method
get_endpoint with operation_id
read_operation with operation_id, route, or cli_name
list_docs browses the docs by collection, and read_schema reads one schema's fields. search_docs now also searches error codes, webhook event types, CLI commands, changelog entries, and lookups, and takes kinds, limit, and cursor.
Bounded results. Every tool result holds up to 16 KiB by default. Pass max_bytes from 2048 to 65536 to change it. A result that doesn't fit ends with the exact call that returns the next part. read_operation returns an overview by default; pass section with request, response, errors, or examples for the rest.
Protocol. The server supports MCP protocol versions 2025-11-25 and 2025-06-18. initialize answers 2025-11-25 to a client that asks for 2024-11-05 or 2025-03-26, and a request that sends another MCP-Protocol-Version header gets 400. The server rejects JSON-RPC batches with -32600: send one message per POST.
Markdown. Every docs page has a .md twin, including error codes, webhook events, CLI commands, the changelog, and lookups. Long pages split into parts with a Next: link and a Link header, and ?section= and ?max_bytes= select a section or a part size. Each API operation and schema has its own page at /docs/api/operations/<operationId>.md and /docs/api/schemas/<Name>.md.
Removed./llms-full.txt returns 410 Gone. Use /llms.txt as the index and /llms/manifest.json to fetch every document.
If you configured an agent with the old tool names, such as in an AGENTS.md or CLAUDE.md file, update them. The AI agents guide has the new loop and the project instructions snippet.
error_source now says who must act before the request can succeed, and it depends only on the error code and details[0].reason. The value for each code and reason is in the error catalog. The vocabulary is caller, merchant, merchant_endpoint, and flint.
caller is new. It means the request must change: its inputs, its credential, or how often you send it. It covers mistakes in your integration's requests and invalid input a buyer gave through your app. Errors that reported merchant because the request was wrong, such as INVALID_REQUEST, INVALID_CREDENTIAL, INSUFFICIENT_SCOPE, VERSION_CONFLICT, RATE_LIMIT_EXCEEDED, and LIMIT_REACHED, now say caller. CLI errors that happen before a request is sent say caller too.
merchant is narrower. It means the merchant's account or stored configuration must change first: onboarding, verification, a setting, configuration that a later request reads, or a review a person approves. It is the default for MERCHANT_NOT_READY and PAYMENT_REVIEW_OPEN. Reasons such as configuration_required, customer_account_mode_conflict, and merchant_hosted_customer_accounts under ACTION_NOT_ALLOWED also say merchant. The reasons that mean Flint is repairing or reviewing something say flint: account_setup_repair_required, account_setup_unavailable, under_review, processing_not_enabled, platform_funding_unavailable, and reconciliation_required.
merchant_endpoint replaces integration.integration meant both an endpoint the merchant runs and the integrator's own code. merchant_endpoint covers only the first: an endpoint the merchant configured for Flint to call that failed, timed out, or answered badly. flint now also covers CONCURRENT_MODIFICATION, OPERATION_IN_PROGRESS, and every 5xx code that has no other source.
Two new 502 EXTERNAL_SERVICE_ERROR reasons carry merchant_endpoint. Both have remediation.retry: same_request.
rate_callback_failed: your delivery rate callback failed, timed out, or answered with an invalid response. This replaces reason rate_unavailable with a callback_*, timeout, or malformed_responsefailure_category. failure_category stays as a fact. rate_unavailable remains for a rate that can't be calculated for any other reason, and says flint.
issuer_unavailable: a workload identity issuer's OpenID Connect discovery endpoint failed or timed out. The error still has param: issuer, and it had no reason before.
In the docs metadata, each code and each reason now publishes error_source, and each reason publishes retry. A status entry no longer carries error_source, because it depends on the code and reason rather than the status.
Code that branches on error_source should handle caller and merchant_endpoint and stop expecting integration. Keep branching on code and details[0].reason for the fix. The error handling guide defines each value, the delivery rate callbacks guide covers the callback, and the workload identities reference covers the issuer.
Breaking change
API
Fulfillment
Invoices
Idempotency
Fulfillment creation and invoice issue require an Idempotency-Key#
POST /v1/orders/{order_id}/fulfillments now requires an Idempotency-Key for every request body. Creating a fulfillment with an inline package marked shipped can consume inventory. Repeating that request without protection could create another fulfillment and consume more stock.
POST /v1/invoices/{invoice_id}/issue also requires a key for every body because issuing an automatic-collection invoice can create payment movements. After a lost response, retry with the saved key and body. Read the invoice and its payment-attempts list to inspect collection; contact support with the original key if the outcome remains uncertain.
A request to either route without a key returns 400 INVALID_REQUEST with details[0].code: "REQUIRED" and details[0].param: "Idempotency-Key" before the body is read. Save a key before sending and reuse it with the same body after a timeout. SDKs and the CLI require you to supply the key for this route.
Some retained invoice-issue results can return IDEMPOTENCY_RECOVERY_REQUIRED. Keep the original key and contact support with the request ID; sending a new key does not recover the earlier result.
If replay cannot recover the result, use GET /v1/fulfillments filtered by order_id and your saved external_reference_id, if supplied. The list has no idempotency_key filter. An empty or ambiguous result does not prove creation failed. Contact support with the original key and request ID before creating another fulfillment.
Payment intent confirm and capture still take an optional key; order pay still requires one. The idempotency guide explains the rule and how to recover a lost confirm response.
Breaking change
API
Gift-cards
Keep existing gift card codes when importing balances#
POST /v1/gift-cards accepts an optional top-level code only when funding.source.funding_source_type is import. Codes must contain 16 gift card alphabet characters after removing spaces and hyphens. Flint stores the supplied code as a secret and omits code and code_recovery_expires_at from the response. A duplicate returns 409 ALREADY_EXISTS at code.
GiftCard.code_source identifies generated and imported codes. Code rotation issues a generated code and resets code_source to generated.
Previously, inner spaces made a code invalid; every code input now ignores ASCII spaces. POST /v1/me/gift-cards with credential_type: code treats imported-code cards as not found. Use a private recipient link to save those cards; checkout still accepts their codes.
See gift cards and migrating from Square. Rotate imported codes when you can reach their holders, and delete migration exports after the import.
Breaking change
API
Gift-cards
Gift card lifecycle verbs and shared status words#
POST /v1/gift-cards/{gift_card_id}/transitions is removed. Use one route per action:
Previous request
New route
Request body
action: "freeze"
POST /v1/gift-cards/{gift_card_id}/freeze
reason and optional expected_version
action: "unfreeze"
POST /v1/gift-cards/{gift_card_id}/unfreeze
Optional expected_version
action: "close"
POST /v1/gift-cards/{gift_card_id}/close
Optional expected_version
Remove action from each body. The operation IDs are freezeGiftCard, unfreezeGiftCard, and closeGiftCard. The routes keep their scopes, optional Idempotency-Key, version checks, and gift card responses.
Update status comparisons and list filters to use these values:
Field
Previous value
New value
GiftCardRedemption.status
captured
succeeded
GiftCardNotification.status
queued or sending
pending
GiftCardNotification.status
bounced
failed
GiftCardNotificationDeliveryAttempt.status
started
pending
GiftCardNotificationDeliveryAttempt.status
abandoned
unconfirmed
The notification's closed message_status vocabulary publishes only scheduled, pending, sent, failed, unconfirmed, and canceled. pending covers both waiting to send and sending; failed includes bounced messages. Delivery attempts use the extensible message_attempt_status vocabulary and publish pending, sent, failed, and unconfirmed. A bounce remains a bounced event in delivery.events. The captured_money field and webhook event names keep their names.
Gift cards, redemptions, and notifications now always include supported_actions, including in command results and webhook snapshots. [] means no lifecycle action is available. The values depend on stored state, never your credential or scopes; your credential still needs permission to call the route. Gift card actions add adjust_balance and cash_out; redemptions list capture and cancel, and notifications list cancel when state permits them. Each value names its verb route, with underscores replacing hyphens.
Use a notification's supported_actions to decide whether cancellation is available. Its pending status alone doesn't say whether sending has already started.
Regenerate API clients and update routes, request bodies, status filters, comparisons, and webhook consumers together. SDK 8.0.0 includes these route and status changes. See gift card actions and recipient email.
Inventory receipt reads and resource references now accept only invrec_ IDs. The legacy invret_ prefix is no longer accepted by GET /v1/inventory-receipts/{inventory_receipt_id}, GET /v1/resource-timelines/{resource_id}, or related_resource_ids on POST /v1/feedback-reports.
Use the inventory_receipt_id returned by Flint when retrieving an inventory receipt or referencing it in another request. Update stored references that use invret_ before retrying them.
Recording or reversing a backdated manual payment now sets the invoice's updated_at, and the update timestamps of checkout sessions invalidated and payment attempts canceled by that action, to the recording time. The payment's received_at and reversed_at, and the invoice's paid_at and closed_at, keep their business meaning.
Lists of bundle components, partner apps, credentials, and installs, organization memberships, webhook events and event types, checkout fulfillment options, fulfillment status updates, and inventory movements now continue from the last row's sort values and ID as they were when the page was returned. Updating or deleting that row between requests no longer moves or ends pagination.
Outstanding page tokens on these lists return the invalid-token validation error with HTTP 400. Restart the list without page_token, then use the new response's next_page_token for subsequent requests. Keep the filters and sort the same. You may change page_size between requests.
GET /v1/tax-connection/registrations now returns up to 20 registrations by default, matching its published default. Previously, leaving out page_size returned up to 100. Follow next_page_token to read every registration, or send page_size=100 to retain the previous page size.
These changes apply to every supported API version.
Breaking change
API
Money
Request money objects require amount and currency#
Breaking: Every money object you send must include both amount and currency. If either is missing, Flint returns 400 INVALID_REQUEST with a REQUIRED detail for each missing member. Each detail's param names the full JSON path, such as line_items[0].unit_price_money.currency. Previously, an incomplete money object could cause a 500 response or silently create a $0 amount.
Send {"amount": 0, "currency": "USD"} for an explicit zero where the field permits it. Optional money fields may still be omitted, and fields that document null clearing still accept it. See Money & currency.
Breaking change
API
Onboarding
Onboarding rejects changes to initial account intent#
POST /v1/onboarding/advance now returns 409 ACTION_NOT_ALLOWED with reason field_locked when an explicit country or requested_capabilities differs from the initial intent after account provisioning starts. param identifies the field. Previously, a provisioned account could return 200 while ignoring the change.
Omit these fields to preserve the initial intent. The same capability set in a different order is accepted. Unsupported countries still return 400 INVALID_REQUEST before locked-field checks. A refused intent change does not apply the accompanying profile updates.
To enable ACH debit payments on an existing account, use the ACH debit setting instead of changing onboarding intent.
Breaking: ACTION_NOT_ALLOWED, LIMIT_REACHED, PAYMENT_OPTION_UNAVAILABLE, and PROMOTION_DECLINED always return 409. Update clients that expect payment option or promotion refusals at 400, or count limits at 429. Follow remediation.retry for recovery; promotion declines and count limits use none. A promotion code with invalid characters or length returns 400 INVALID_REQUEST, with detail INVALID_VALUE at its parameter. An unknown but syntactically valid code returns 409 PROMOTION_DECLINED with reason code_invalid.
Breaking: expired report downloads return 409 ACTION_NOT_ALLOWED with reason terminal_status, replacing 410. Create the report again with a new key. Only API_VERSION_RETIRED returns 410, and only RATE_LIMIT_EXCEEDED returns 429.
Breaking: completed image ingestions that require a new attempt return 409 ACTION_NOT_ALLOWED with reason image_ingestion_restart_required and retry none. This replaces the restart reason on 500, 502, 503, and 504 responses. Start a new ingestion with a new Idempotency-Key. Image validation failures remain 400 INVALID_REQUEST and no longer carry the restart reason: correct the named input and send it with a new key. Transient failures that can continue the same attempt keep their server error code and same_request retry.
Retained errors use the same public contract when replayed. Regenerate SDKs from the updated OpenAPI schema and update status-based error handling.
Captured request and response bodies in APIRequestLogDetail and APIRequestLogReproduction now use oneOf instead of a type array. The alternatives are objects, arrays, and strings. Array items can contain any JSON value. These alternatives preserve the existing body types and let generators that reject non-null type arrays load these models.
The issue_test_key selectors in CreateSandboxRequest and the buyer_fields.require_email constraint in CreateCheckoutSessionSubscriptionPlan now use typed boolean enums, enum: [true] or enum: [false], instead of const. Accepted values and required fields stay the same.
Regenerate your OpenAPI client if log model generation or Python formatting failed. These changes remove the boolean-constant syntax errors in generated Python models. Other generator limitations can still prevent complete client generation.
Breaking change
API
Developers
Partners
OpenAPI version headers use strings for client generation#
The OpenAPI request parameter for Flint-Version now uses type: string with pattern: ^\d{4}-\d{2}-\d{2}$, replacing format: date. Every operation references the shared components.parameters.FlintVersion parameter. Regenerate your client and pass a string such as 2026-09-07 wherever your generator previously expected a date object. HTTP requests still send the same YYYY-MM-DD header value.
The PartnerAppCredential response schema now uses not: {} instead of boolean false schemas to exclude other credential payloads. This affects list, create, get, and delete responses under /v1/partner-apps/{partner_app_id}/credentials. A credential still includes only the payload matching its type: public_key, jwks_url, or workload_identity.
These changes remove the date-header rejection in openapi-python-client and the boolean-property parsing failure in oapi-codegen. Other schema limitations in those generators can still prevent complete client generation.
Breaking: Every order money input and computed amount is now limited to 99999999 minor units ($999,999.99 USD), the single-payment ceiling. Amounts above the ceiling and totals that would exceed it are refused instead of overflowing to negative subtotals or a zero total. Payment options can have lower limits.
This applies when creating orders and when changing their prices, quantities, modifiers, discounts, charges, tips, or tax. A valid unit price and quantity can still exceed the ceiling when multiplied, and individually valid line items, charges, and tips can exceed it when combined.
Flint returns 400 INVALID_REQUEST with detail code INVALID_VALUE and param naming the input responsible. The refused request does not create or change the order. Reduce that input or split the purchase into orders whose inputs and computed amounts fit within the ceiling. The existing line item quantity range remains 1 through 9999.
page_size is now independent of page_token on every list. For example, request 20 records on the first page, then send its next_page_token with page_size=100 on the next request. Keep the endpoint, filters, sort, merchant, and environment the same. You may also change expand between pages.
This corrects lists of payment method domains, custom domains, tax registrations, test clocks, workload identities, credit notes and their allocations, invoice manual payments, invoice payment attempts, reports, and feedback reports, which previously rejected changes to page_size during traversal.
GET /v1/checkout-sessions and GET /v1/webhook-endpoints now continue from the last row's sort value and ID as they were when the page was returned. Updating or deleting that row between requests no longer moves or ends the traversal. These lists and the other corrected lists reject tokens issued before this change, even when the requested page size stays the same.
These changes apply to every supported API version. If a previously issued page_token returns a validation error with HTTP 400, restart the list without page_token and use the new response's next_page_token for subsequent requests. Treat tokens as opaque and hold them only while traversing the list.
A successful final partial capture now reduces an order's collectible balance by the uncaptured authorization. settlement_amounts.released_money records the discharged debt, limited to that capture's authorization and the remaining priced obligation. Canceled, expired, and failed attempts do not discharge order debt.
For a $25.00 order authorized for $25.00 and finally captured for $15.00, paid_money is $15.00, released_money is $10.00, and outstanding_money is zero. The order becomes payment_status: paid, status: closed, with closed_reason: paid. Previously it stayed open and partially paid with $10.00 still collectible. Remove any follow-up collection or manual close intended to handle that released amount.
pricing_amounts stays unchanged. Released money does not count as paid, refunded, written off, overpaid, or collected, and only captured money can be refunded. A refund does not reopen the discharged debt. Inventory and promotion use follow actual funded allocations; fulfillment creation proceeds when the order becomes paid.
The payment transition sends order.paid and closure sends order.closed, once each. That commit does not also send order.partially_paid or order.updated, and replaying the capture sends no new event.
Partner app updates reject null fields and identify invalid scopes#
PATCH /v1/partner-apps/{partner_app_id} now rejects null for name, redirect_uris, permission_manifest, default_requested_permissions, and expected_version. These values previously acted like omitted fields. The response is 400 INVALID_REQUEST with detail code INVALID_VALUE and param naming the field. Omit a field to leave it unchanged. The existing null restrictions on api_version, expected_api_version, and client_secret_enabled still apply.
When creating or updating a partner app, a rejected manifest scope now has a concrete error path such as permission_manifest[0].required_scopes[2], rather than permission_manifest[0].required_scopes. The message names the scope. An unknown scope returns detail code INVALID_VALUE; a known scope that partner installs cannot request now returns NOT_ALLOWED. Update error handling that matches the old path or detail code, and choose scopes marked as available to partner installs in the scope catalog.
The onboarding session token no longer authenticates partner app routes. It previously worked for app creation, listing, retrieval, and updates, and for reading installs. All routes under /v1/partner-apps and /v1/partner-app-installs, including credentials, secret rotation, deletion, and revocation, now refuse this token with 401 INVALID_CREDENTIAL and details[0].reasonwrong_credential_type.
Create and manage partner apps with a live API key from Dashboard > Developers > API keys, a live CLI login from flint login --live, or an authorized live dashboard session. None requires a verified business. Dashboard sessions still need fresh identity verification to add a credential or rotate a secret.
Test keys continue to get 403 FORBIDDEN with details[0].reasonlive_mode_required. The onboarding session token continues to work on its supported sandbox setup routes.
Create partner apps with any supported API version#
POST /v1/partner-apps now accepts any supported api_version, including a version newer than the request's Flint-Version. Updates already accept these versions.
Omitting api_version still uses the request's API version. Unsupported versions are still rejected.
API
Partners
Api-keys
Webhooks
Link API keys and webhook endpoints to a connected app#
POST /v1/api-keys and POST /v1/webhook-endpoints accept an optional, immutable partner_app_install_id. API key and endpoint resources always include the field, with null when unlinked. Both lists accept it as a single-value, exact-match filter.
Revoking the install revokes linked keys and deletes linked merchant endpoints. Revoking one environment grant ends its environment's linked access. Sandbox endpoints stop receiving events immediately and are normally removed within seconds; an attempt already in flight may still arrive. Reinstalling the app doesn't restore old keys or endpoints. Unlinked resources keep working until separately revoked or deleted.
Keys and endpoints created by a linked key inherit the same install. Linked keys can't create workload identities, partner app client credentials, customer access links, or delivery rate callbacks. They also can't create a sandbox with issue_test_key: true, rotate a partner app's client secret, regenerate an invoice public link, or copy webhook endpoints. Workload identity updates that change the subject, claim conditions or scopes, or reactivate the identity, are refused too. Each install can have up to 25 active linked keys and 25 linked endpoints per environment.
The merchant install revoke, app-owner install revoke, and environment-grant revoke responses return PartnerAppInstallWithEndedAccess. It includes required revoked_api_key_ids and deleted_webhook_endpoint_ids arrays, both empty when nothing ended. Install reads and events keep their existing shape.
Webhook deliveries add suppression_reasonpartner_app_install_revoked for linked merchant endpoints whose install access ended, before endpoint deletion.
Partner-source webhooks require live configuration access#
Breaking: endpoints whose event_sources include partner_app or installed_merchants are global partner-app configuration. Test-mode credentials can no longer create, update, or delete them, rotate their secrets, send test events, resend their deliveries, or create deliveries from their events. These mutations return 403 FORBIDDEN with reason live_mode_required, including idempotent replays. This applies even when installed_merchant_modes is only ["test"].
Sandbox endpoint, event, and delivery lists now omit global partner-source records. A filter selecting only partner sources returns an empty collection. Direct reads of their endpoints, events, deliveries, and delivery attempts return 404 RESOURCE_NOT_FOUND; list filters naming those records by ID return the same error.
Move partner webhook configuration and recovery requests to the app owner's live-mode credential, with webhooks.write for mutations and webhooks.read for reads, or use an authorized Dashboard session. Send these requests in live context. Keep test credentials for ordinary merchant sandbox webhooks, which continue to work in their own sandbox.
installed_merchant_modes still selects which installed-merchant events an endpoint receives. This change doesn't alter event emission or which events a configured endpoint subscribes to. Partner install tokens still can't mutate endpoints or trigger deliveries, and event payloads and attempt response details still require the event's resource-read scopes.
Payment intent status events fire once per transition#
Payment intent status events now fire only when the stored status changes. Previously, a synchronous API result followed by a provider webhook, or multiple provider observations of one result, could create separate events for the same transition. Repeated observations and replays no longer create another status event.
This applies to payment_intent.requires_action, payment_intent.processing, payment_intent.requires_capture, payment_intent.succeeded, payment_intent.canceled, and payment_intent.expired.
payment_intent.payment_failed now fires once for each newly recorded failure. Two observations of the same failed attempt produce one event. A later failed attempt produces its own event, even when the payment intent's status is unchanged.
Delivery remains at least once. Keep handlers idempotent and deduplicate retries and resends on webhook_event_id, because one recorded event can still be delivered more than once. See Payment intent events.
Breaking change
API
Payment-links
Inventory
Payment links require usable delivery and inventory configuration#
POST /v1/payment-links and sellability changes through PATCH /v1/payment-links/{payment_link_id} previously accepted links whose buyers could not check out because delivery methods were missing or incompatible, or inventory allocation was disabled. These requests now return 409 ACTION_NOT_ALLOWED with reason configuration_required and retry none.
Set delivery_method_ids on the link or settings.checkout.default_delivery_method_ids to cover its items' delivery profiles. A profile can allow pickup or require no checkout delivery method. Tracked items also need a routing source with an active location whose inventory_allocation_enabled is true. An allocation policy remains usable when at least one of its locations allows allocation. Temporary stock shortages do not prevent these writes.
The check runs when creating a link, changing its status to active, or editing line_items, delivery_method_ids, or inventory_routing_source. You can still rename, edit metadata, or deactivate an existing link that needs configuration. Error details identify the resource to configure and include a follow-up action when a separate write is required.
Every required line needs a usable option. Event buyers can skip adjustable tiers, so an unusable optional tier does not prevent saving a link when another tier can be checked out. For a pinned inventory policy revision, enable allocation at an active location in that revision or change the link's inventory_routing_source. Publishing a new policy revision does not change the pin.
Breaking: payout success is succeeded. Payout status: "paid" becomes status: "succeeded" in API responses, expanded payout summaries, webhook payloads, and the GET /v1/payouts status filter. Update status comparisons and send status=succeeded when listing successful payouts. The bank accepted the deposit, but it can still return it later: a succeeded payout can become failed. A reversed payout keeps status: "succeeded" and reports reversal_status: "reversed".
Breaking: payout.paid becomes payout.succeeded. Update webhook subscriptions and event handlers. Once deployed, this change sends payout.succeeded to every webhook endpoint, including endpoints pinned to older API versions. Flint applies no version transforms during the breaking-change window. The event still means the bank accepted the deposit. The catalog lists payout.paid in previous_names; stored subscriptions, event reads, retries, and resends use payout.succeeded. Inputs accept only the new name. Keep handling payout.failed for payouts you already marked as received, and handle payout.reversed separately.
Breaking: dispute response sessions name the Stripe payment explicitly. In the response from POST /v1/disputes/{dispute_id}/response-sessions, client_session.stripe.components[].payment becomes client_session.stripe.components[].stripe_payment_intent_id. Pass that value to Stripe Connect's setPayment or React payment prop. It is a Stripe PaymentIntent ID, separate from the dispute's Flint payment_intent_id.
Payouts and disputes now include a required supported_actions array, independent of the caller's credential:
Payouts list cancel when they are pending and were not sent by your schedule. Call POST /v1/payouts/{payout_id}/cancel with money_movement.payouts.write.
Disputes list accept when a chargeback is in needs_response, has a response window, and its evidence_due_at hasn't passed. Call POST /v1/disputes/{dispute_id}/accept with payments.disputes.write.
Either list is [] when no lifecycle action is available. Dispute accept and simulation refusals include supported_actions too. Simulation and response sessions stay outside the list.
For disputes, supported_actions, is_action_required, and is_evidence_deadline_passed are evaluated when you read the dispute; webhook payloads keep the values from when Flint recorded the change. Once evidence_due_at has passed, reads return is_action_required: false, is_evidence_deadline_passed: true, and no accept action, with no event. Schedule reminders from that timestamp and read the dispute before acting.
Inquiry accept refusals now offer a create_refund next action at /v1/refunds, with required_fields: ["payment_intent_id"], required_scope: "commerce.refunds.write", and a target_resource naming the dispute's Flint payment intent. When an action includes target_resource, send its resource_id in the request field named {resource_type}_id. Here, send it as payment_intent_id.
Refunds refused because of an open or lost chargeback explain that the buyer already has the money. Respond to or accept the dispute in blocking_resources; refunds work again once it is won or prevented. When exactly one dispute blocks the refund, next_actions offers get_dispute with its URL.
has_evidence means evidence is saved, submitted or not. In test mode, Flint saves an unsubmitted draft when the dispute first needs a response, so has_evidence: true doesn't mean someone started a response. A dispute.updated with that value can follow dispute.needs_response. Use is_action_required: true and evidence_submission_count: 0 for unanswered cases, whether or not a draft exists. Flint can't report whether anyone edited a draft. Drafts are off in live mode until Flint enables them, and merchants can't opt out. Simulating an outcome submits any saved draft and replaces its additional notes with the processor's test value.
Breaking: ErrorDetail.capability no longer includes create_instant_payouts. Flint doesn't offer instant payouts, so this capability cannot be returned in an error. Remove branches for that value. Payouts Flint sends use standard; instant remains readable and filterable for payouts sent outside Flint and recorded from the processor.
Readiness actions use request paths and a shared review reason#
Breaking:ReadinessAction.required_fields now lists paths in the action's target request body. For advance_onboarding, replace website_url, support_email, support_phone, and support_url with profile.website_url, profile.support_email, profile.support_phone, and profile.support_url. Send the values inside profile when calling POST /v1/onboarding/advance. Top-level inputs such as country, requested_capabilities, and the API key's name keep their existing paths.
Breaking:MERCHANT_NOT_READY errors now use details[0].reason: "platform_review" where they previously used under_review. Update clients that match the old reason. The new value matches readiness status_reason and means Flint paused processing while it reviews the merchant account. Processing resumes when the review ends; contact Flint support for details.
onboarding_required remains a coarse error reason covering readiness onboarding_not_started, requirements_due, requirements_past_due, and pending_verification. Read GET /v1/merchant for the specific readiness reason and next actions.
Request properties no longer carry x-flint-enum-kind or x-flint-enum-vocabulary. If your tooling reads these extensions on requests, use the property's enum values to determine accepted values instead. Adding an accepted request value is compatible, regardless of how a response vocabulary grows.
Schemas shared with responses now use separate request views. Follow the updated $ref targets, including references inside union branches.
HTTP payload fields and accepted request enum values are unchanged. Response enum properties continue to publish their growth metadata.
Order line items, invoice snapshot line items, and subscription line items now return required type instead of optional source_type, including their buyer views and webhook snapshots. The closed order_line_type vocabulary has three values: variant for a catalog variant, bundle for a catalog bundle, and custom for an item without either catalog source. Read type wherever you previously read source_type. Custom lines now explicitly return type: "custom".
POST /v1/onboarding/start no longer returns verification_started. A successful response returns verification_token and expires_at. POST /v1/onboarding/verify-email no longer returns merchant_created. Use the returned user, merchant, and onboarding session to continue whether verification provisioned a merchant or signed in an existing user. Neither response reports whether the merchant was newly created.
The refund creation response schema is renamed from CreateRefundResult to RefundWithGiftCardCodes. Update generated SDK type references to the new name. The JSON response is unchanged: it contains the Refund fields plus gift_card_codes when codes are recoverable.
Response schemas also mark always-returned created_at, updated_at, and merchant_id fields as required. Merchant Customer responses mark internal_note, external_reference_id, and segment as required and nullable, matching the existing JSON output. These fields return null when unset.
remediation.retry now depends only on the error code and details[0].reason, never on the route or the request. same_request means nobody has to act and the wait is at most one hour. none means someone else must act, you must watch for an outcome, or the wait is longer than an hour or has no known end. A 429 is only a throttle over a window of an hour or less. Every other count limit is a 409 LIMIT_REACHED quota. The errors below change.
Quotas move from 429 to 409 LIMIT_REACHED. Each has remediation.retry: none, no Retry-After, and a new details[0].resets_at (an RFC 3339 time) when time alone frees capacity.
POST /v1/reports with five reports already pending: reason pending_reports, limit: 5, and the pending reports in blocking_resources. Wait for one to finish, then create the report again as a new request.
Connecting a sixth webhook event stream for an environment: reason webhook_event_streams with limit. Close a stream or wait for one to end.
POST /v1/demo-sessions past 10 per IP in 24 hours: reason daily_demo_sessions with limit and resets_at, replacing Retry-After of up to 24 hours.
Customer verification codes past 10 per customer or email in 24 hours: reason verification_codes with limit and resets_at. The 3 per 15 minutes limit stays 429 RATE_LIMIT_EXCEEDED.
Saved-card confirmation codes past a daily cap: reason saved_card_codes, now with limit and resets_at.
Checkout saved-card codes for an email or number past 10 wrong tries in 24 hours or 30 in 7 days: reason verification_attempts with limit and resets_at. When several limits apply at once, the response reports the one that resets last. Once a cap is reached, a correct code is refused too, and checkout customer verification still answers wrong, expired, replaced, and out-of-tries codes the same way.
LIMIT_EXCEEDED reasons buyer_daily, card_daily, merchant_adjustments_daily, and merchant_imports_daily, and LIMIT_REACHED reasons daily_gift_card_purchases, monthly_tax_calculations, and external_paid_orders, now carry resets_at where Flint knows the time. resets_at is a new field on ErrorDetail.
Flint's webhook stream capacity returns 503. When Flint reaches its process-wide cap of 250 event streams, a connection returns 503 SERVICE_UNAVAILABLE with same_request, error_source: flint, and a short Retry-After, replacing 429 RATE_LIMIT_EXCEEDED.
Every 429 carries Retry-After, a whole number of seconds from 1 to 3600. Receipt and invoice reminder resends, custom domain validation, customer verification codes, and saved-card codes now send it. Custom domain validation sends the time left in its window instead of a fixed 60.
Flint sends Retry-After only with same_request. A PAYMENT_ATTEMPT_ACTIVE conflict keeps none and no longer sends that header. Read the named attempt and use its supported_actions before starting another payment.
Waits that need someone else, or have no known end, are none.
capability_pending and platform_funding_unavailable under MERCHANT_NOT_READY, PAYMENT_OPTION_UNAVAILABLE, and PAYMENT_PROCESSING_UNAVAILABLE, previously same_request. For capability_pending, read readiness.capabilities on GET /v1/merchant until the capability is active, then send a new request. For platform_funding_unavailable, the merchant changes nothing and tries again later as a new request.
Onboarding that this Flint environment hasn't configured returns 503 SERVICE_UNAVAILABLE with reason repair_required and retry none, previously same_request with no reason. Contact Flint support with the request_id. A temporary onboarding outage stays same_request.
ACTION_NOT_ALLOWED with reason in_progress on POST /v1/subscriptions/{subscription_id}/change-plan is none, previously same_request on that route only. It now means a collection payment is waiting on the buyer. Wait for the buyer to pay or the collection to end, then send a new request.
A renewal in progress is OPERATION_IN_PROGRESS.POST /v1/subscriptions/{subscription_id}/change-plan while Flint runs a renewal payment returns 409 OPERATION_IN_PROGRESS with remediation.retry: same_request, a short Retry-After, and the subscription in details[0], replacing ACTION_NOT_ALLOWED with reason in_progress. Send the same request again with the same Idempotency-Key.
A stale credit note draft is VERSION_CONFLICT. Issuing a credit note whose creditable amounts changed since you read it returns 409 VERSION_CONFLICT with after_refresh, replacing CONCURRENT_MODIFICATION with reason credit_note_creditable_value_changed. details[0] names the credit note with resource_type, resource_id, and current_version. Read the note, refresh the draft, and issue with a new Idempotency-Key.
Custom return replacement lines now require fulfillment, using the same input as an order line. Include it in resolution previews, creates, process requests, and replacement collection PATCHes, including retained custom lines. Send {"requirement":"none"} when nothing is delivered, or supply the fulfillment requirements for what you will send.
Exchange and replacement orders now inherit the original Order's inventory routing source, so tracked catalog replacements can be priced without a new resolution field. If that Order has no routing source, a tracked replacement returns 409 ACTION_NOT_ALLOWED with reason configuration_required, naming the original Order. Set its inventory_routing_source before trying again. The Return's receiving location is not an outbound fallback.
Replacement pricing errors now name replacement_line_items, with a resolution. prefix on previews, instead of the internal order input line_items.
Breaking:ReadinessRequirements.current_deadline_at and ResponseWarning.current_deadline_at are now due_at. Update clients that read the old field. The instant is unchanged: the merchant must submit the due onboarding information by this time. Warning due_at appears only on merchant_onboarding_deadline and merchant_onboarding_past_due when a deadline is set.
Breaking: While automatic sandbox preparation is queued or running, affected readiness axes and capabilities report status: pending, status_reason: provisioning, and empty next_actions. Flint owns this work. Read readiness again shortly; no merchant account session is needed. Onboarding state's next_step is absent during preparation. A sandbox with no queued preparation still reports its onboarding requirements and actions. Live readiness is unchanged.
Breaking: The merchant readiness embedded in POST /v1/onboarding/verify-email now describes the default sandbox named by default_sandbox_id. It agrees with GET /v1/merchant using the returned onboarding session for the same observation. Previously, it described the live account.
The new provisioning value is an additive member of the extensible readiness reason vocabulary. Accept future reason values without failing to parse the response.
The OpenAPI document now publishes more of the limits and response shapes Flint already uses. Runtime validation and responses are unchanged. Regenerate clients to update their models.
TextModifierConfigInput.min_length has minimum: 0; max_length has minimum: 1 and maximum: 500. These are the existing text configuration limits for modifier group creation, including inline groups.
CreateSubscriptionPlanRequest.trial_period_days and UpdateSubscriptionPlanRequest.trial_period_days have minimum: 0 and maximum: 365.
Settings request and response schemas publish subscriptions.dunning_retry_days from 1 to 90, with a default of 16, and inventory.low_stock_threshold with minimum: 0.
MerchantAccountSessionCreateRequest.targeted_requirements has maxItems: 100. Each code can contain at most 255 UTF-8 bytes after trimming surrounding whitespace; this remains in the field description because maxLength counts untrimmed characters.
Customer create and update name descriptions state the existing limit of 255 Unicode code points after trimming surrounding whitespace. They do not gain an untrimmed maxLength constraint.
Keep submitted values within these existing bounds. The server continues to return the same validation errors.
For POST /v1/products, CreateProductRequestSimple no longer lists options or variants, and CreateProductRequestOptioned no longer lists default_variant. For POST /v1/risk-previews, CreateRiskPreviewRequestStoredRule no longer lists action or predicate. These fields were already rejected in those variants. Send only the fields allowed by the selected variant.
PublicResolvedModifierGroup.pricing_scope no longer lists per_line. The field remains and returns per_item.
Location.coordinate_source no longer permits null. Like coordinate, it is omitted when unset.
ResourceTimelineAPIRequestEntry.reference_url gains format: uri, matching the absolute guide URLs returned by request logs.
CardDetails.wallet publishes the extensible vocabulary apple_pay and google_pay, with descriptions. Continue to handle additional values in extensible response vocabularies.
Merchant resource annotations now include fields removed by the buyer projection's access rules, including the merchant-only fields on Return. Return metadata remains present as an empty object for buyers.
Operations with empty effective security no longer publish Flint-Merchant-Id, Flint-Mode, or Flint-Sandbox-Id response headers. The public payment-link read still documents those headers on its 200 response, where the server returns the link's context. Do not depend on these headers on other credential-free operations.
The OpenAPI document now describes the inputs Flint already accepts and the responses it already returns. Runtime validation and responses are unchanged. Regenerate clients to update their models.
Named structural variants previously listed fields that their own unconditional not predicates prohibited. Those fields are removed from the variant's properties. This affects return resolution inputs, return policy revision inputs, and credit note correction inputs. Send only the fields allowed by the selected variant. Conditional exclusions still apply as before.
The POST /v1/checkout-sessions variants are also narrowed:
CreateCheckoutSessionOrder omits quick_pay_item, subscription_plan_id, subscription_terms, customer_id, and tax.
CreateCheckoutSessionQuickPay omits order_id, replace_checkout_session_id, subscription_plan_id, and subscription_terms.
CreateCheckoutSessionSubscriptionPlan omits order_id, replace_checkout_session_id, and quick_pay_item.
These properties were already rejected for those variants.
ReturnLineItem.merchandise_status and BuyerReturnLineItem.merchandise_status omit exception. The aggregate Return.merchandise_status retains it.
DecideReturnInspectionLineItemRequest.acceptance_status changes from accepted | rejected | review_required to accepted | rejected. Recorded inspection results can still contain review_required.
CreateReturnReceiptRequest.source_system, CreateReturnInspectionRequest.source_system, and ReturnProcessReceiptInput.source_system use ReturnSourceSystemInput. Its source_system_type accepts manual, pos, wms, erp, and other, with flint removed. Responses keep ReturnSourceSystem, including flint.
ReturnResolution.action_required_by and BuyerReturnResolution.action_required_by change from buyer | merchant | integration to buyer | merchant. The merchant list filter still accepts integration.
EmailPreferenceLink.email_preference changes from shipping_updates | checkout_reminders | other to shipping_updates | checkout_reminders.
BuyerFulfillmentEvent.previous_status and .current_status omit on_hold. Merchant fulfillment events retain it.
FulfillmentHold.previous_status omits on_hold, completed, canceled, failed, and no_show. Its allowed values are pending, accepted, scheduled, in_progress, preparing, picked, packed, ready, and dispatched.
Remove the rejected enum values from requests. Update generated response models to use each field's published vocabulary.
BrandingSettingsInput.primary_color, .accent_color, .background_color, and .text_color publish the pattern ^#[0-9a-fA-F]{6}$. corner_radius publishes int32 with a minimum of 0 and maximum of 32. Existing validation errors stay the same.
RefundLineItemAdjustmentIn now marks amount_money and reason as required, matching refund creation validation.
Inventory reservation demands publishes 1 through 100 entries. InventoryReservationOwnerInput.key publishes 1 through 255 characters.
ReturnReason.handle publishes ^[a-z][a-z0-9_]{0,99}$ and lengths 1 through 100; version has a minimum of 1. Return reason create and update inputs publish at most 100 category_handles. Request descriptions state handle, name, and description limits after trimming; name and description limits count bytes.
Send values within these existing limits. Client-side validation generated from the schema can now enforce them before sending a request.
BuyerInvoice.customer, BuyerInvoice.order, and BuyerFulfillment.order are removed from the published schemas. /v1/me routes do not accept expand and never return those fields. Use the buyer resource's IDs and documented buyer endpoints for related resources.
Operations with empty security omit x-flint-route-class; they do not spend a credential or merchant route-class budget. See Rate limits for IP limits.
Breaking change
API
Onboarding
Session next actions share the create request shape#
NextAction.merchant_account_session now references ReadinessMerchantAccountSession, the shared body for POST /v1/merchant-account-sessions. The removed NextActionMerchantAccountSession schema used a singular component field that the create endpoint rejected.
Use components as an array, together with collection_strategy and future_requirements. Optional targeted_requirements preserves the requirement codes in a recommendation. There is no singular-field alias. Update integrations and generated clients that reference the removed schema or component property.
When a create_merchant_account_session action includes merchant_account_session, send that body unchanged. An action without a session body does not choose a collection policy for you: read GET /v1/merchant and use the recommendation in its readiness. Producers without requirement facts leave the session body absent. Existing warning actions continue to direct integrations to readiness.
POST /v1/subscriptions/{subscription_id}/change-plan and POST /v1/subscription-previews with mode: "plan_change" accept optional line_items, each with a target subscription_plan_line_item_id and a whole-number quantity from 1 to 9,999. IDs must belong to the target plan and cannot repeat.
An explicit quantity takes precedence. Otherwise, Flint carries the quantity from a paired current line, matching by plan line ID on the same plan, then by variant or bundle, then by the only line on each side. An unpaired target line uses its plan quantity. A three-seat upgrade from $10 to $25 per seat now has a $75 recurring items subtotal.
If an adjusted current line cannot be paired, the change fails with 409 ACTION_NOT_ALLOWED, reason quantity_not_carried, and param: "line_items". details[0].blocking_resources names subscription lines your key can read. Send a quantity for every target line to make the choice explicit. Nothing changes on refusal.
A now change on a trialing subscription returns trial_in_progress, or cancellation_scheduled when it is set to cancel, matching Order now. Use next_renewal to change plans during the trial.
Breaking change: plan changes preserve line quantities instead of resetting them to the target plan's defaults. This affects immediate charges and future renewals on every supported API version. Review integrations that relied on the reset and send line_items explicitly when a quantity should change. The subscription-level quantity multiplier and billing_starts choices keep their existing behavior.
Webhook attempts now report pending while scheduled or in flight. This replaces both queued and sending in:
WebhookDeliveryAttempt.status from GET /v1/webhook-deliveries/{webhook_delivery_id}/attempts.
WebhookDeliveryAction.attempt_status from creating a delivery, resending a delivery, or sending a test event.
ResourceTimelineWebhookDeliveryAttemptEntry.status from resource timelines.
Update status comparisons and generated client types to accept pending in place of queued and sending. Attempts still report delivered when the endpoint answers 2xx, and failed for a non-2xx response, timeout, or connection failure. The vocabulary is extensible, so handle unknown attempt statuses without failing to read the record.
Delivery status values stay pending, delivered, failed, and suppressed. OpenAPI names the delivery record's closed vocabulary message_status and the extensible attempt vocabulary message_attempt_status. The delivery_status in action responses uses the same delivery values and remains extensible. No event names change.
OpenAPI also describes each signing method and each status value, and explains attempt failure fields at the attempt level. The x-flint-webhooks.signing extension now lists methods: ["jwt", "hmac"] and default: "jwt". Tools that read its former top-level HMAC details must read those details under signing.hmac; JWT details remain under signing.jwt.
Breaking change
API
Webhooks
Webhook signing changes through PATCH and new endpoints pin their version#
signing_methods now controls whether a webhook endpoint uses HMAC. Previously, adding hmac through PATCH /v1/webhook-endpoints/{webhook_endpoint_id} failed when no secret existed, and POST .../rotate-secret issued the first secret. Now PATCH issues that secret and returns it once in data.secret. Include hmac in signing_methods and send the endpoint's current expected_version. Save the secret from that response; later updates, reads, and lists omit it.
rotate-secret now only rotates an existing secret. On a JWT-only endpoint it returns 409 ACTION_NOT_ALLOWED, with reason secret_not_issued. Replace any first-secret rotation call with a PATCH that includes hmac. Creating an endpoint with hmac, removing hmac, and signature headers keep their existing behavior. Delivery rate callbacks and partner app secrets keep their existing issuance behavior.
Omitting api_version on POST /v1/webhook-endpoints previously stored "default", which followed the merchant default at delivery time. It now stores the version the create request is served at: its Flint-Version header, or the merchant default when the header is absent. Send "api_version": "default" explicitly if the endpoint should follow future default changes. Existing endpoints keep their stored version, and omitting api_version from PATCH still leaves it unchanged.
Flint now shows the Webhook deliveries are failing notice and emails team members who can manage webhooks after a live delivery's fifth failed automatic attempt, about an hour after the first. Previously, the notice waited for the ninth failed attempt, about three days in.
Automatic retries continue after the alert. You get one notice per incident, and a successful delivery resolves it. Sandbox endpoints and test events don't raise the notice.
GET /v1/webhook-events includes synthetic test events by default. The include parameter has been removed. Use test=false to exclude synthetic events or test=true to return only synthetic events. Omitting test returns all events. GET /v1/webhook-events/stream accepts the same boolean filter.
Exact webhook_event_id and webhook_endpoint_id filters on GET /v1/webhook-deliveries return an empty page when no visible deliveries match, instead of returning 404 for an unknown or invisible reference. A deleted endpoint's retained deliveries still match its ID. Malformed IDs still return 400 INVALID_REQUEST with an INVALID_VALUE detail.
Merchant webhook envelopes and event resources now include the public sandbox_id in test mode. OpenAPI webhook object schemas publish x-flint-webhook-omitted-fields for fields left out of resource snapshots.
Webhook resend and delivery creation errors change:
An event past its 14-day payload retention returns 409 ACTION_NOT_ALLOWED with details[0].reason: payload_expired, replacing terminal_status. Retry is none. Read the resource with GET for its current state. Flint can't resend the expired event. Expired report downloads continue to use terminal_status.
POST /v1/webhook-deliveries/{webhook_delivery_id}/resend while another attempt for the same delivery is running returns 409 OPERATION_IN_PROGRESS, replacing ACTION_NOT_ALLOWED with reason in_progress. The response has no reason, uses remediation.retry: same_request, and sends Retry-After: 5. Wait, then retry the same request with the same Idempotency-Key. The refusal isn't retained against the key. details[0] identifies the delivery with resource_type: webhook_delivery and its resource_id.
Creating a delivery for an endpoint that doesn't subscribe to its event still returns 409 ACTION_NOT_ALLOWED with reason configuration_required. Its remediation.next_steps now names the fields to correct: add the event type to the endpoint's enabled_events; for partner endpoints, also check event_sources and installed_merchant_modes, then retry.
Delivery, attempt, and timeline attempt error_category uses webhook_payload_render instead of server_error when Flint can't prepare the payload. Update branches on that field. The failure remains retryable, and Flint retries automatically while the delivery is pending.
Delivery revocations name exact revisions, keys, and geographies#
POST /v1/delivery-revocations now requires an exact target. The operation ID changes from revokeDeliveryDependency to createDeliveryRevocation, the SDK method is deliveryRevocations.create, and the request schema is CreateDeliveryRevocationRequest.
The delivery_method and delivery_rate_callback target types and the top-level expected_version field are removed. Read the resource's current revision ID and send one of these targets:
Requests and responses include only the fields for their target type. Response targets have no expected_version. Older revocations stored with delivery_method or delivery_rate_callback targets read back as their revision type, with both parent and revision IDs.
A missing parent, a parent from another merchant or environment, a revision from another parent, an unknown signing key, or a geography version the Location never recorded returns 404 RESOURCE_NOT_FOUND at the failed target field. Signing-key targets accept only the named callback's current or previous HMAC key. These refusals change nothing and send no event.
A second revocation for the same exact target returns 409 ALREADY_EXISTS, including when the earlier revocation used a removed target type. details[0].current_resource contains the existing revocation. The duplicate changes nothing and sends no second delivery_revocation.created event.
Each new revocation sends delivery_revocation.created once. When fencing the current revision advances a method's or callback's version, Flint also sends delivery_method.updated or delivery_rate_callback.updated in the same transaction.
Breaking: Merchant hold requests no longer accept reason: payment_review. They return 400 INVALID_REQUEST with detail INVALID_VALUE at reason. Use fraud_review for your own review, or other with reason_message.
Fulfillment.active_hold now includes the required, read-only initiated_by field: merchant for you or your integration, or flint for a Flint payment hold. Treat this vocabulary as extensible.
Packages record progress without advancing merchant-held fulfillments, whatever the reason, including legacy payment_review holds. Flint payment holds keep the fulfillment paused while the payment stop is active; later package progress can advance it after that stop lifts. The response reason vocabulary still includes payment_review for holds placed by Flint.
Breaking change
API
Delivery
Checkout
Revoked methods no longer block fresh delivery quotes#
Creating a delivery quote now succeeds when a pinned method revision, rate callback revision, callback signing key, or Location geography version has been revoked. Previously, one revoked dependency caused the entire request to return 409 DELIVERY_REQUOTE_REQUIRED with reason quote_revoked, including every attempt to requote.
Fresh quotes leave the affected method out of options and report its candidate outcome as type: unavailable with unavailable_reason: dependency_revoked. Merchant callers also receive a diagnostic with code: dependency_revoked, recommended_action: review_configuration, and the method and revision IDs. Other methods remain available. If every method is affected, the quote succeeds with no available options.
Quotes issued before the revocation still become revoked. Selecting from one returns 409 DELIVERY_REQUOTE_REQUIRED with reason quote_revoked. Create a new quote and offer its remaining options.
Open checkout sessions keep their pinned revisions. Publishing a corrected revision makes it available to new sessions; an existing session keeps the fenced revision unavailable. See delivery revocations.
Breaking change
Webhooks
Webhook created_at is when Flint recorded the event#
Breaking: for new merchant and partner webhook events, envelope created_at is when Flint first records the event. Previously, it could be the resource change time, a provider timestamp, or an earlier observation time. Delayed events now appear in created_after windows for their recording time.
Use the timestamps on data.object for the resource's business times. Retries and manual resends keep the event's original created_at and snapshot. Existing events keep their timestamps.
Distinct events can share a timestamp. Continue to overlap timestamp windows and deduplicate by webhook_event_id, or use the event stream to resume in recorded order.
Breaking: merchant and partner webhook envelopes now require a top-level event_source:
merchant for events sent to merchant endpoints.
partner_app for your app's own lifecycle events.
installed_merchants for resource events from merchants that installed your app.
Partner envelopes no longer include source.type. Read event_source instead. The other source fields keep their existing meanings: merchant_id, partner_app_install_id, mode, environment_grant_id, and sandbox_id.
Typed OpenAPI webhook entries now use string const tags for event_type and each branch's event_source. Entries with two source branches declare an event_source discriminator and mapping. Regenerate webhook types and update handlers that read source.type. Shared envelope components retain the full extensible event_type enum.
Each typed entry also includes x-flint-previous-names, matching the catalog's previous_names array. It is [] when the event has never been renamed, so tools can suggest current names without calling the catalog API.
Breaking change
API
Orders
Checkout-sessions
Customers
Subscriptions
Payment-links
A typed email no longer attaches a purchase to an existing customer#
A paid order, its payment intents, saved cards, and subscriptions now join an existing customer only when the checkout acted for that customer. The email a buyer types never does on its own.
Before
When a buyer paid with an email that an existing customer already had, Flint linked the order, its payments, and any card or subscription it created to that customer. A buyer who typed someone else's email could put a purchase on that person's account, where it appeared in their /v1/me and hosted account.
Now
A checkout acts for a customer in two cases: you set customer_id on the order or the checkout session, or the buyer confirmed the email with a code in this checkout (POST /v1/checkout-sessions/{checkout_session_id}/customer-verifications and its confirm route). Everything else follows from that:
One-time orders. A guest who types the email of an existing customer and doesn't confirm it pays as before, and the order stays unlinked with buyer_email kept. It doesn't appear in that customer's /v1/me or hosted account. Its payment intents stay unassigned.
Claiming the order. The account holder claims the order with the existing link-guest-purchases flow: Flint emails a code to the address, and POST /v1/customers/{customer_id}/link-guest-purchases attaches it. See Link a buyer's guest purchases.
A new email. Flint still creates a minimal customer and sends customer.created. If two checkouts race to create the customer for one email, the one that loses stays unlinked.
Saved cards. The customer that holds a card waiting for phone confirmation, or a card saved with save_payment_method_phone, gets nothing else from the payment. The order doesn't join them.
Subscription signups. Paid signups, free trials and setup-only signups, carts that mix a subscription with other items, and payment links need a customer. When the typed email belongs to an existing customer and the checkout hasn't confirmed it, pay returns 409 ACTION_NOT_ALLOWED with details[0].reason: verification_required, before anything is charged or saved. Request a code with POST /v1/checkout-sessions/{checkout_session_id}/customer-verifications and purposesave_payment_method, confirm it, and pay again with the checkout credential the confirmation returned. A signup with a new email needs no code. A signup that pays with a saved payment method, with no customer_id on the order and no customer the checkout acts for, returns 409 ACTION_NOT_ALLOWED with reason configuration_required, resource_type: order, and the order's ID as resource_id, with no param, before anything is charged. The error's next_actions has an update_order entry for PATCH /v1/orders/{order_id} with required_fields: ["customer_id"]. Set customer_id on the order and pay again with the same Idempotency-Key.
Nothing changes for historical purchases, and no request or response fields were added.
Who is affected
Backends that rely on a guest's typed email to put orders on an existing customer, and then read those orders through that customer's /v1/me, the customer filter, or customer_id on the order.
Integrations that sign up subscribers through a payment link or a checkout session without customer_id, where the subscriber's email already has a customer. Hosted checkout shows the code step; the buyer enters the code, then presses Pay again, and their payment details are kept. Only embedded checkouts that handle ACTION_NOT_ALLOWED need a change.
What to do
Set customer_id on the order or the checkout session for signed-in buyers. Nothing else changes for them.
Handle verification_required on subscription signups in an embedded checkout. Who the subscription belongs to shows the calls.
For a guest order that should reach an existing customer, run the link-guest-purchases flow once the buyer proves they own the email.
Don't read the absence of customer_id on a paid order as a failure. Match guest orders by buyer_email until they are claimed.
Breaking change
API
Payments
Payment method domain changes recover after interrupted requests#
PATCH /v1/payment-method-domains/{payment_method_domain_id} now returns 409 OPERATION_IN_PROGRESS when another change on the registration is running. Previously, this condition returned 500 IDEMPOTENCY_RECOVERY_REQUIRED. Wait for Retry-After, then resend the identical request with its original Idempotency-Key. An identical-key request already running continues to return 409 IDEMPOTENCY_KEY_IN_PROGRESS.
After 503 SERVICE_UNAVAILABLE, retry the identical PATCH with its original key. Flint resumes the earlier change before accepting a different change. The same recovery applies when Flint registers a payment domain for a custom domain or customer account URL.
IDEMPOTENCY_RECOVERY_REQUIRED is reserved for changes Flint cannot safely recover, including an expired recovery window or an older interrupted change whose original target is unavailable. Read the registration to inspect its current state, then contact support with the original key and request_id before submitting another change.
Breaking change
API
Merchants
Files
Shared merchant profile writes require live credentials#
Breaking: test credentials can no longer write any of the 13 mutable fields on PATCH /v1/merchant: api_version, business_name, email, phone, address, reporting_timezone, metadata, logo, icon, support_email, support_phone, support_url, and website_url. These values are shared by live mode and every sandbox.
A test credential that supplies any of these fields gets 403 FORBIDDEN with reason live_mode_required, including explicit null, clears, and empty or nonempty metadata updates. Nothing in the request is saved. The response has one detail per supplied shared field, ordered by field name, with its JSON path in param; the top-level param names the first field.
Creating a file with purpose merchant_logo or merchant_icon, completing that file, and importing a branding image from a URL require the same authority. Other file purposes stay writable in their own environment.
Use a live-mode credential with merchants.profile.write or a Dashboard session. Dashboard sessions can edit shared profile fields and branding with any environment selected, subject to the user's role. Onboarding sessions have no Dashboard exception. To set sandbox onboarding prefill, send profile to POST /v1/onboarding/advance; it changes only that sandbox.
The profile stays shared. A profile update still sends merchant.updated to every active environment.
Register sandbox webhook endpoints before DNS is ready#
Sandbox webhook endpoints and partner endpoints restricted to test mode can now be created or updated before their hostname resolves. You can register a receiver before its host is live. Live endpoints and partner endpoints that include live mode still require a resolving public host.
HTTPS, localhost, private IP, and signing-method URL rules still apply. Before every delivery, Flint resolves the hostname and checks every address. DNS resolution failures now report webhook_dns instead of webhook_blocked_target, and automatic retries continue. Targets that resolve to private or local addresses still report webhook_blocked_target.
Breaking change
API
Delivery
Delivery rate callbacks verify with Flint’s public keys by default#
New delivery rate callbacks default to signing_methods: ["jwt"] across supported API versions. Verify the bearer JWT with Flint's public JWKS, using your delivery_rate_callback_id (dcb_...) as the audience and checking body_sha256 against the exact request bytes. Each HTTP request has a unique jti, including retries of the same evaluation. Deduplicate on delivery_rate_evaluation_id. The delivery rate callback guide includes verification code and JWKS cache rules.
Existing callbacks keep ["hmac"]. To migrate, PATCH signing_methods to ["jwt", "hmac"] with the current expected_version, deploy JWT verification, then replace the set with ["jwt"]. Removing hmac deletes the current and previous secrets, their key IDs, and expiry. Every callback resource response includes signing_methods; PATCH replaces the set and rejects empty, unknown, and duplicate values.
JWT-only callbacks have no shared secret issued, stored, or returned. To opt into HMAC on create, send ["hmac"] or ["jwt", "hmac"]; only these create responses include secret and key_id, shown once. Adding hmac through PATCH without a secret returns 409 ACTION_NOT_ALLOWED with reason secret_not_issued. Call rotate-secret to issue the first secret and add hmac, or to rotate an existing secret with a one-hour overlap.
JWT callbacks send Authorization: Bearer <token>. Every callback request still carries webhook-id and webhook-timestamp; webhook-signature and Flint-Signing-Key-Ids are present only with HMAC. If Flint cannot sign a JWT, it sends no request, including for hybrid callbacks, and the affected methods follow the existing unavailable-callback pricing behavior. Test deliveries and connection checks return 503 SERVICE_UNAVAILABLE. Signing uses the callback's existing request timeout budget.
API
Partner apps support JWKS URLs and workload identities#
Partner app credentials now accept type: jwks_url and type: workload_identity alongside public_key. Register them at /v1/partner-apps/{partner_app_id}/credentials, then send client_id, client_assertion_type, and client_assertion on token and revoke requests.
A JWKS URL credential points to a set of up to 10 public signing keys. Flint validates the set on creation, caches keys, and refreshes them when an assertion has an unknown key ID, at most once per URL per minute. jwks_url.last_fetched_at reports the last successful fetch. Self-signed assertions keep the existing five-minute expiry and single-use jti requirements.
A workload identity credential trusts an external OIDC issuer, exact subject, audience, and optional claim conditions. It can use GitHub Actions or another supported provider without a stored private signing key. The assertion must expire within one hour and 60 seconds; a valid provider token can authenticate multiple requests without single-use jti enforcement.
The 20-active-credential limit applies across all types. Removing a credential stops it from authenticating immediately. Invalid JWKS or discovery configuration returns 400 INVALID_REQUEST; temporary upstream failures on create return 502 EXTERNAL_SERVICE_ERROR, with the affected field in param.
POST /v1/disputes/{dispute_id}/simulate (simulateDispute) simulates the card network's ruling on a sandbox dispute. Send a required outcome: won or lost for a chargeback in needs_response, and inquiry_closed or escalated for an inquiry in inquiry_needs_response. A missing or unknown outcome returns 400 INVALID_REQUEST.
Flint submits Stripe's documented test evidence for the outcome, and the ruling arrives through the dispute's usual webhook events, as a real one would. Flint never sets the outcome itself, and Stripe gives no timing for it. The route returns 200 with the dispute, normally under_review or inquiry_under_review with evidence_submission_count1. Create a test dispute by paying with 4000 0000 0000 0259, or with 4000 0000 0000 1976 for an inquiry.
won sends dispute.updated, then dispute.won.
lost sends dispute.updated, then dispute.lost.
inquiry_closed sends dispute.updated, then dispute.inquiry_closed.
escalated turns the inquiry into a chargeback and sends dispute.needs_response, sometimes after a dispute.updated.
The route requires payments.disputes.write, accepts an optional Idempotency-Key, and uses the external_provider_action rate limit class. It works with a test-mode API key or Dashboard session. A live credential gets 403 FORBIDDEN with reason test_mode_required. Simulating is separate from POST /v1/disputes/{dispute_id}/accept, which concedes a chargeback as the merchant.
A dispute that can't take the outcome returns 409 ACTION_NOT_ALLOWED. Branch on details[0].reason:
terminal_status: the dispute is won, lost, prevented, or inquiry_closed, including after you accept it.
in_progress: the dispute is under review, or another request is submitting the same outcome.
bank_return_not_contestable: the dispute is a bank return.
unsupported_state: the dispute has no response window, its deadline has passed, or its state is unrecognized. With paramoutcome, the outcome is for the other kind of dispute, such as won on an inquiry.
A repeat with a new Idempotency-Key returns 409, because the dispute already has submitted evidence. A retry with the same key replays the first result. A 503 SERVICE_UNAVAILABLE with reason processor_unavailable means Stripe couldn't take the evidence: retry with the same key.
Tax registrations now have a period, and you can turn automatic tax off without contacting support.
Registration dates
TaxRegistration has a new end_date: the last day the registration applies, inclusive, or null for no end date. start_date can now be up to 365 days in the future on create, so you can schedule a registration before it takes effect.
status adds scheduled (confirmed, starts after today) and ended (confirmed, end_date has passed). Both come from the UTC date, so a status can change on a date boundary with no write, no tax_connection.updated webhook, and no new version. Branch on status with these values in mind. The status list filter accepts them, and the list route has a new exact state filter.
A state can now have several registrations whose periods don't overlap. A create or edit that overlaps another registration in the state returns 409 ALREADY_EXISTS with current_resource.
PATCH can set or clear end_date on a scheduled or active registration. registration_number and start_date stay editable only while a registration is pending or rejected; a locked field returns 409 ACTION_NOT_ALLOWED with reason field_locked, and any edit to an ended registration returns unsupported_state. An end_date before today (UTC) or before start_date returns 400 INVALID_REQUEST with INVALID_VALUE.
DELETE now removes a scheduled registration. active and ended registrations still can't be deleted.
To change a registration number, set the old registration's end_date, then create the new registration with a start_date one day later.
An order to a state whose registration isn't in effect on the sale's date calculates zero tax.
Disconnect
POST /v1/tax-connection/disconnect turns automatic tax off. tax_default_behavior is required: turn_off sets tax.default_enabled to false, and keep leaves it on, so orders that inherit tax are refused until you reconnect. Neither value turns the setting on. The response holds the tax_connection and the settings.
Open orders with calculated automatic tax and no issued invoice become tax incomplete. Invoices with issued tax still collect. Payment links that turn tax on explicitly are refused when a checkout session is created.
The connection reads not_connected with the new status_reasondisconnected, and supported_actions gains disconnect. Reconnect with POST /v1/tax-connection/connect and a new seller_attestation.
status_reason and supported_actions can now change with the clock when a registration's end_date passes. Read the connection before you show a connect control.
Test clocks now work end to end in a sandbox. Send test_clock_id to POST /v1/customers to create a customer on a clock. The customer, and every subscription created for them, read the clock's time instead of real time. Then move the clock with POST /v1/test-clocks/{test_clock_id}/advance.
When you advance a clock, Flint runs the billing that falls due, in order, at the clock's time:
Trials end, the first charge runs, and subscription.trial_ending and subscription.renewal_upcoming notices go out.
Renewals charge at next_billing_at, and failed ones move through payment retries to the action you configured when retries run out.
Scheduled starts, timed pauses, and cancellations at the end of a period take effect.
Events are real sandbox webhook deliveries, carrying test_clock_id, and subscription emails are real emails to the address on the customer, so use addresses you control. test_clock.ready arrives after every event the advance caused. POST /v1/subscriptions/{subscription_id}/renew now judges a trial by the clock's time and returns trial_in_progress until you advance past trial_end_at.
Customer.test_clock_id and Subscription.test_clock_id are read-only and merchant-only. A customer can't move to another clock: PATCH /v1/customers/{customer_id} with test_clock_id returns 400 INVALID_REQUEST with detail UNKNOWN_FIELD.
GET /v1/customers and GET /v1/subscriptions accept an exact-match test_clock_id filter.
A live credential that sends test_clock_id or the filter gets 403 FORBIDDEN with reason test_mode_required.
A clock holds up to 10 subscriptions that aren't canceled. An eleventh returns 409 LIMIT_REACHED with reason test_clock_subscriptions.
An advance can't go past two billing intervals of any of the clock's subscriptions, or two years. Past that, it returns 409 ACTION_NOT_ALLOWED with reason advance_limit_exceeded and maximum_frozen_at in the error detail.
While a clock is advancing, writes to its subscriptions return 409 ACTION_NOT_ALLOWED with reason in_progress. Wait for test_clock.ready and retry.
Orders, payment intents, invoices, and the other resources a clock doesn't bind keep real time, as does Stripe's own processing. Invoices don't follow the clock yet.
API keys declare access: full, read_only, or restricted. Full keys hold every scope Flint includes for their mode, now and as Flint adds scopes. Read-only keys hold the read scopes of that set, including future read scopes. Restricted keys hold exactly their scopes. Keys show access, and scopes lists what a key holds today.
Breaking:access replaces scope_preset on POST /v1/api-keys and the sandbox key routes, and it is required when creating a key. Send scopes only with access: "restricted", including on PATCH /v1/api-keys/{api_key_id}. Send expected_version when changing a key's access or scopes. Only an authorized user session, after fresh identity verification, or a full-access key can grant full or read_only; other credentials get 403 FORBIDDEN with reason full_access_required. Existing keys are restricted with their current scopes. PATCH /v1/api-keys/{api_key_id} uses the sensitive_write budget.
The request schema for POST /v1/me/return-previews now includes store_credit in resolution.resolution_type. Use mode: "resolution", provide resolution.return_id and a nonempty resolution.line_items list, and omit resolution.replacement_line_items. Store credit returns value on new gift cards instead of the original payment.
This corrects the published contract to match requests the server already accepts. Generated SDKs can support buyer store-credit previews after their next release.
Breaking change
API
Checkout
Delivery
Read checkout delivery and write selections without a required fence#
Breaking:CheckoutSession.fulfillment is now CheckoutSession.delivery. Its always-present delivery_selection_id is the current selection ID, or null when none is current.
expected_delivery_selection_id is optional when creating a checkout delivery quote, creating a selection, or clearing the current selection. Omit it to make no assertion. In JSON bodies, send null to assert that no selection is current, or an ID to assert that it is current. The DELETE query parameter accepts an ID. A failed assertion returns 409 VERSION_CONFLICT with param: expected_delivery_selection_id and current_delivery_selection_id. Clearing without a current selection returns 404 RESOURCE_NOT_FOUND.
Breaking: selection creation no longer accepts external_system or external_reference_id. Either field returns 400 INVALID_REQUEST with an UNKNOWN_FIELD detail, for merchant and checkout credentials. Use Idempotency-Key for retries, the checkout session's or order's external_reference_id and metadata for correlation, and each selected choice's merchant_reference for rate-service references.
Delivery previews in delivery_options mode can omit delivery_method_ids to use settings.checkout.default_delivery_method_ids. The response returns the resolved IDs. With no defaults, it returns empty delivery_method_ids and choice_groups.
Breaking: previews in pickup_locations mode no longer accept expected_delivery_selection_id. Sending it returns 400 INVALID_REQUEST with an UNKNOWN_FIELD detail. Pickup previews evaluate the current selection at read time.
Breaking change
API
Checkout
Payment links accept only the current checkout fields#
Payment link create and update requests now reject customer_collection, redirects.success_redirect_url, and redirects.cancel_redirect_url with INVALID_REQUEST and an UNKNOWN_FIELD detail. Send buyer_fields, redirects.success_url, and redirects.cancel_url instead.
Hosted payment link completion pages now read only checkout_session_id and order_id. The retired csId and orderId query parameters are ignored. Hosted checkout already appends the current parameter names to success URLs.
Breaking change
API
Idempotency
Inventory
Recover creates by key and create inventory drafts without one#
Every route that requires an Idempotency-Key now has a documented recovery path. These lists accept a new idempotency_key filter: payment intents, refunds, payouts, invoices, subscriptions, gift cards, order payment attempts, invoice manual payments, Returns, and Return receipts, inspections, and dispositions. Buyers can list their subscription payment retries with GET /v1/me/subscriptions/{subscription_id}/payment-retries, which accepts the same filter. Recovery reads maps each required route to its read.
A filter on a top-level list matches the request that created the resource, not its latest update. A list filtered by idempotency_key returns current authorized resources and leaves out values that grant access, such as an invoice's public_url and an order payment attempt's pending_actions. A pending match doesn't prove success, and an empty list doesn't prove that a request had no effect. Retry the original request with the same key first, and reconcile unresolved outcomes with support instead of sending the action again under a new key.
Breaking: every idempotency_key list filter, including the existing ones on inventory, gift card, credit note, invoice payment attempt, and subscription payment retry lists, takes exactly one value, trims surrounding whitespace, and applies the header's rules: 1 to 255 characters, with no null characters or line breaks. A blank, repeated, or invalid value returns 400 INVALID_REQUEST. Matching is exact and case-sensitive.
POST /v1/inventory-transfers now accepts an optional Idempotency-Key. A transfer draft moves no stock, so each request without a key creates a separate draft. With a key, a same-body retry returns the original draft and a different body is a conflict; find a keyed draft with GET /v1/inventory-transfers?idempotency_key={key}. Adjustment, receipt, and reservation creation still require a key.
Breaking: inventory resources and movements omit idempotency_key when the request that created them had no key, including in replays of older results, instead of returning an empty string. A supplied key is always returned.
Breaking change
API
Orders
Fulfillment
Delivery
Link orders and fulfillments to delivery selections#
Order.governing_delivery_selection_id and BuyerOrder.governing_delivery_selection_id are now present on every order response, including lists, mutation results, expanded orders, buyer order lists, and order.* webhook snapshots. The value is null when no delivery selection governs the order. Open, unpaid orders use the effective current selection; paid, closed, or frozen orders keep the stored selection.
Fulfillments created from a checkout delivery selection now include four read-only fields: delivery_selection_id, delivery_choice_group_id, delivery_execution_leg_id, and delivery_method_id. All four fields are always present and are null for fulfillments created manually. Buyer fulfillment responses are unchanged.
When an order is paid with a governing delivery selection, Flint creates one fulfillment per execution leg shortly after payment and sends fulfillment.created for each. Handle those events to execute delivery. Creating a manual fulfillment for quantities owned by the selection returns 409 LIMIT_EXCEEDED.
Breaking change
API
Delivery
Read consistent delivery quotes and list delivery history#
Delivery quotes now report the same status and stale_reason on individual reads, quote lists, and checkout quote reads. These values reflect the checkout, inventory demand, eligibility context, and effective current selection at read time. The status filter on GET /v1/delivery-quotes matches that derived status. Quotes remain ordered by creation time ascending. A page scans at most 500 candidates, so it can contain fewer than page_size items while still returning a next_page_token.
Quotes now include created_at and a nullable delivery_revocation_id. Merchants can list revocations with GET /v1/delivery-revocations, filtering by target_type, reason, created_after, and created_before. Merchants can also list a checkout's selections with GET /v1/checkout-sessions/{checkout_session_id}/delivery-selections. Both new lists return the newest resources first and default to 20 items per page.
Breaking: the quote-level consumed_by_delivery_selection_id is renamed to superseded_by_delivery_quote_id. It identifies the priced quote that replaced the original quote; the replacement's basis_delivery_quote_id points back to the original. The matching stale_reason changes from consumed_by_priced_quote to superseded_by_priced_quote. Option-level consumed_by_delivery_selection_id fields keep their names and meanings.
Breaking: the operation ID for GET /v1/checkout-sessions/{checkout_session_id}/delivery-selections/{delivery_selection_id} changes from getCheckoutSessionDeliverySelectionHistory to getCheckoutSessionDeliverySelection. Its URL stays the same.
Revocation response schemas now match the existing responses: a revocation target never includes the request-only expected_version assertion. Requests that revoke a stable method or callback still require that assertion.
In test mode, Flint can prepare an unsubmitted evidence draft when a card dispute needs a response. It uses existing sale records and fills only blank evidence fields. Review and edit the draft in the dispute response component before submitting it. Automatic drafts remain disabled in live mode.
Requests that select a commerce or payment variant now require its discriminator. Send type on invoice and order-line creation, payment-link lines, subscription-plan lines, and order-line modifiers; calculation_type on charges and tips; variant_mode on product creation; and mode on risk previews. Shipment creation requires direction, and tax locations require address_type.
Payment credentials require credential_type: token, payment_method, or stripe_confirmation_token. To continue confirmation with an attached payment source, send {"credential_type":"attached"}. An empty confirmation body is rejected. Fields belonging to another variant return INVALID_REQUEST with a NOT_ALLOWED detail identifying the conflicting fields.
Payment-link and subscription-plan lines now return type, including lines in expansions, webhooks, and replayed responses. Payment-link custom lines distinguish custom_fixed from custom_variable; variable lines can still have an initial price. OpenAPI alternatives have complete named schemas, branch titles, and explicit discriminator mappings for SDK request construction and response narrowing.
Merchant reads now accept previously stored boolean and numeric metadata values instead of failing. These values appear as strings, such as "true" and "42". Existing string values are preserved. Metadata writes still require string values.
Breaking change
API
Onboarding
Idempotency
Merchant account sessions replay recorded handoffs#
These changes apply immediately to every supported API version:
Refresh moves from POST /v1/merchant-account-sessions/refresh to POST /v1/merchant-account-session-refreshes. The old route is removed. The body is still { "launch_token": "..." }.
Create and refresh return 200 OK instead of 201 Created. The response body is unchanged.
The Idempotency-Key header stays optional. Within 24 hours, a retry with the same key and body returns the original result, including its launch token, client secret, policy, and expiry timestamps, and Flint doesn't create another provider session. Before, a retry created a new session. A replay doesn't extend either expiry, and only the credential that made the original request can replay it.
Each new client secret now needs a new key. While the launch token is valid, send a new refresh with a new key. After the launch token expires or Flint denies authorization, send a new create with a new key.
A same-key retry of a request made before this change returns IDEMPOTENCY_RECOVERY_REQUIRED and creates no session. Send the request again with a new key.
Update integrations to call the new URL, accept 200, and send a new key for each new create or refresh. See Retries and replay.
Breaking: Every response address now uses Address. Only country is always present; other members are omitted when they have no value. This replaces PostalAddress, DeliveryAddressResource, LocationAddress, and OrderDeliveryDestinationAddress, including delivery advisory suggestions and webhook addresses.
Complete postal address requests use AddressInput, replacing LocationAddressInput and OrderDeliveryDestinationAddressInput. Send line1, city, and an uppercase ISO country code. US addresses also require state and postal_code; other countries can omit them. line2, state, and postal_code accept null. Empty strings, including whitespace-only values, are rejected. Limits after trimming are 255 characters for each address line, 100 for city and state, and 20 for postal code.
Delivery quotes still accept partial DeliveryAddressInput: send what the buyer has entered, with at least country when sending any address member. A destination_address sent with a delivery selection must be complete, and international addresses can leave out state and postal_code. A selection that omits it uses the quote's destination, which may be partial. Saved address storage and tax and delivery calculations keep their existing values.
Breaking change
API
Customers
Delivery
Manage customer addresses through saved addresses#
Breaking:POST /v1/customers and PATCH /v1/customers/{customer_id} no longer accept billing_address or shipping_address. Create or update saved addresses through /v1/customers/{customer_id}/addresses or /v1/me/addresses.
Customer responses and webhooks always include billing_address and shipping_address. Each is a read-only copy of its saved default, or null when no address holds that default. Flint uses the billing default for orders without another tax location and the shipping default to prefill checkout.
The address set-default routes have been removed. Set or clear is_default_billing and is_default_shipping on the address with PATCH. Deleting a default leaves that role without a default; Flint does not choose another saved address.
Child routes move with their collections. GET /v1/partner-app-installs lists a merchant's installed apps with a live API key; it doesn't accept an onboarding_session_token. Wallet store setup is now POST /v1/me/flint-wallet/cards/{flint_wallet_card_id}/store-setups. Demo reset takes its ID only from the path; the body accepts an optional template. Sending demo_session_id in the body returns 400 INVALID_REQUEST.
Wallet card lists return flint_wallet_card_id, a nested card object with brand, last4, exp_month and exp_year, and store_payment_method_id (null when no store copy exists). The card handle keeps its fwc_ prefix. The nested card omits wallet.
Operation IDs follow these paths: getAuthContext, sandbox operations without Developer, partner app operations without Developer, listMeFlintWalletCards, listMePaymentIntents, getMePaymentIntent, createInvoiceCheckoutSession and createReturnResolutionCheckoutSession. Publisher install operations are listPartnerAppInstalls, getPartnerAppInstall, revokePartnerAppInstall and revokePartnerAppEnvironmentGrant; merchant install operations are listMerchantPartnerAppInstalls and revokeMerchantPartnerAppInstall.
Schema names change from DeveloperAuthContext to AuthContext, DeveloperAuthContextResponse to AuthContextResponse, and DeveloperSandbox to Sandbox. Buyer wallet schemas use BuyerFlintWalletCard, BuyerFlintWalletCardListResponse, BuyerFlintWalletStoreSetup and BuyerFlintWalletStoreSetupResponse.
Update SDK method names and CLI bindings when adopting the new contract. Checkout launches retain their existing success statuses. Same-key retries retain their original idempotency identity across the path change.
GET /v1/payment-links/{payment_link_id}/public now reports stock state for catalog lines, so your page can show a sold-out link without a failed payment.
Line items. Each resolved_line_items entry has a required, output-only is_sold_out boolean. It's true when the link's inventory_routing_source can't supply the line at its minimum quantity: for a bundle, when any tracked component can't be supplied. A line where the buyer chooses a variant is true only when every entry in available_variants is sold out. Lines that don't track inventory, including ad hoc lines, are false.
Link. The top-level is_sold_out is now also true for an active link that isn't an event link and has an inventory_routing_source, when any catalog line is sold out, because a buyer buys every line together. Lines that don't track inventory, including ad hoc lines, never count and don't offset a sold-out line. A line where the buyer chooses a variant counts only when every variant is sold out. Starting checkout on a sold-out link is refused with 409 INVENTORY_INSUFFICIENT with detail code INVENTORY_INSUFFICIENT, resource_type: "payment_link", and available_quantity: 0.
Unchanged. The read and the checkout start are advisory: they publish no stock counts and hold no stock. Flint checks and holds stock when the buyer starts payment, and that check decides. Event links keep their own is_sold_out.
Payout trace information and accurate billing states#
Payouts now include trace_id when the processor supplies trace information. Its status is pending, available, or unsupported, and value holds the bank's trace number when available. Use that number to help your bank locate a late deposit.
Payouts also include original_payout_id and reversed_by_payout_id when Flint has the matching payouts. These references can appear before a reversal completes. Read reversal_status to confirm completion; a payout_reversal balance transaction records the returned money.
These breaking corrections apply immediately to every supported API version:
Payout.reversal_status and the expanded payout summary accept only none and reversed. The unused reversing value is removed. A payout stays none until the reversal completes.
Money movement list metadata no longer includes history.earliest_available_at. Flint does not record that history boundary. history.status and history.latest_reconciled_at remain available.
Merchant billing invoice status is open, paid, or written_off. The unused draft, collecting, delinquent, and void values are removed from responses and the list filter. To find unpaid invoices, use GET /v1/merchant-billing-invoices?status=open. A removed filter value returns 400 INVALID_REQUEST with an INVALID_VALUE detail.
Flint's public error-code set is closed at 39 top-level codes and four validation detail codes: REQUIRED, INVALID_VALUE, UNKNOWN_FIELD, and NOT_ALLOWED. The shared code schema contains exactly 43 values. Route-specific conditions use these codes and their published reasons.
The edge firewall now returns HTTP 403FORBIDDEN with details[0].reason: "request_blocked". Replace branches on REQUEST_BLOCKED with this code and reason. Remove URLs pointing to private, loopback, or cloud metadata addresses from the request before retrying.
Error details use resource_type and resource_id for resource identity and blocking_resources for blockers. The remaining subscription_plan_line_item_id, risk_rule_ids, line_item_key, and requested_key_mode detail aliases are removed. Read param for request-field attribution; the requested key mode is already in your request. Retained error responses also use the current vocabulary.
Breaking:POST /v1/payment-intents/{payment_intent_id}/receipts now returns 404. Use POST /v1/payment-intents/{payment_intent_id}/send-receipt for both standalone and order-owned payment intents. For an order-owned intent, it queues the order receipt. The response remains the payment intent, and recipient rules and rate limits are unchanged.
Before:
HTTP
POST /v1/payment-intents/pi_example/receipts
Content-Type: application/json
{}
After:
HTTP
POST /v1/payment-intents/pi_example/send-receipt
Content-Type: application/json
{}
Existing Idempotency-Key records still replay through send-receipt. Keep the same key and request body when retrying a receipt send.
Set or clear is_default_billing and is_default_shipping with PATCH /v1/customers/{customer_id}/addresses/{customer_address_id} or PATCH /v1/me/addresses/{customer_address_id}. Setting a flag to true moves that default to the address. Setting it to false clears the default if the address holds it.
Breaking: Deleting a default address now leaves the customer without that default. Flint no longer selects another saved address. Set a replacement explicitly when needed.
Changes to the default billing or shipping address update the corresponding customer address and increase the customer version. Orders without another tax location use the billing default, and checkout prefills from the shipping default.
OpenAPI now gives delivery eligibility and zone expressions, risk predicates, discount wrappers, image sources, and return disposition selectors complete named alternatives. Their existing keys select the variant. Partner webhook sources publish explicit mappings for their existing type values, and webhook envelope alternatives distinguish merchant and partner identities.
Delivery profiles publish nested choices for requirement and resolution_mode. Nullable delivery eligibility updates retain their clear behavior.
Request fields and runtime behavior are unchanged. Use the API reference for the published alternatives and the fulfillment guide for delivery requests.
Use PATCH /v1/me/subscriptions/{subscription_id} for buyer field updates. These routes have been removed:
Removed route
PATCH field
POST /v1/me/subscriptions/{subscription_id}/payment-method
payment_method_id
POST /v1/me/subscriptions/{subscription_id}/reactivate
cancel_at_period_end: false
POST /v1/me/subscriptions/{subscription_id}/delivery
delivery
POST /v1/me/subscriptions/{subscription_id}/billing-interval
billing_interval and billing_interval_count
POST /v1/me/subscriptions/{subscription_id}/quantity
quantity
Both PATCH operations accept expected_version and an optional Idempotency-Key. Buyer fields follow their matching buyer_actions. Scoped card-update sessions can still send payment_method_id and expected_version. A merchant billing_schedule update must be the only mutable field in the request; move the old schedule body inside billing_schedule and keep expected_version at the top level.
On subscription creation and create previews, service_location now uses type: "address" or type: "customer_address". The old source property is rejected as an unknown field, with no alias.
The earlier PATCH rollout also made recorded early_termination_fee_money stay present after contract_end_at, closed subscription request schemas to unknown fields, required at least one plan line item, and made next_retry_at required and nullable. Flint never charges the recorded early termination fee. Merchant subscriptions and their webhooks now include supported_actions; buyers use buyer_actions.
You can now turn on automatic tax without the Dashboard. The connection and the registrations behind it have their own routes:
GET /v1/tax-connection returns whether automatic tax is connected, why not, and what connecting needs. It always returns 200, even before anything exists. Its status is not_connected, provisioning, active, attention_required, or disabled, and status_reason and supported_actions say what to do next.
POST /v1/tax-connection/connect turns on automatic tax. Show the seller every statement in the connection's disclosure, get their agreement, then send seller_attestation.disclosure_version. If the disclosure changed since you read it, the request returns 409 ACTION_NOT_ALLOWED with reason disclosure_changed and current_disclosure_version. Connecting marks open orders that use automatic tax and have calculated tax, without an issued invoice, as tax incomplete.
GET, POST, PATCH, and DELETE on /v1/tax-connection/registrations list, add, edit, and remove the states where the seller collects tax. Each state has one registration, registration_number is write-only, and only US states are accepted. On an active connection, a new registration syncs during the request, and a number the tax service rejects returns 400 INVALID_REQUEST and changes nothing. Active registrations can't be edited or deleted through the API.
Reading takes settings.read and writing takes settings.write. Merchant API keys, CLI tokens, and Dashboard sessions can call these routes; partner app installs can't. Each sandbox keeps its own connection and registrations.
tax_connection.updated sends the connection whenever it or one of its registrations changes. business_details_changed and temporarily_unavailable are worked out when you read the connection, so they send no event.
AUTOMATIC_TAX_CONNECTION_REQUIRED now points to GET /v1/tax-connection and POST /v1/tax-connection/connect. See Tax connection, Tax registrations, and Sales tax.
Account now reads saved wallet cards from either id with flat card details or flint_wallet_card_id with nested card details. Card labels, expiration dates, and filtering of active store copies stay the same.
GET /v1/me/fulfillment-events now returns pending instead of on_hold in previous_status and current_status on every supported API version. Event snapshots do not carry the progress before a hold, so they use the same pending fallback as buyer fulfillment bodies without that context. Other event statuses are unchanged.
Merchant fulfillment event responses and webhooks retain their hold statuses.
Payment intents, refunds, checkout sessions, payout settings, payout destinations, payment method domains, customer addresses, customer email preferences, and package items now return a positive version. Send the version you edited as expected_version on updates and supported lifecycle commands. A stale assertion returns 409 VERSION_CONFLICT with the current version and after_refresh retry guidance. Keep your draft, read the resource again, and reconcile before submitting a new request. Profile updates at /v1/me use the customer's existing version.
Breaking:PATCH /v1/payout-settings requires expected_version whenever the request supplies default_payout_destinations, minimum_balance_by_currency, monthly_payout_days, or weekly_payout_days. Empty collections also require the fence. Supported null clears follow the same requirement. Optional scalar and lifecycle fences are additions. DELETE requests accept one expected_version query parameter.
Email preferences have a separate aggregate version. Updating both categories commits them together. Changes from unsubscribe links and a change to the customer's current email advance the affected preference view. Address default reassignment advances each affected address and the customer's address projection. Package item versions are independent of the package's existing shipment and capacity checks.
Versions order committed changes to the resource's owned state. Expanded children and provider observations have their own ordering. Retained responses recorded before activation use baseline version 1; resources already present at activation start above that baseline. Distinct historical snapshots can share version 1. New resources start at version 1.
POST /v1/credit-notes/{credit_note_id}/issue accepts an optional allocation object. Issuing the note and applying its credit to the invoice succeed together. Omit allocation.amount_money to apply the smaller of the note's available credit and the invoice's outstanding balance. Currency, invoice status, and unpaid-tip restrictions still apply. You cannot provide both allocation and refund.
When you request an allocation, IssueCreditNoteResult includes credit_note_allocation alongside credit_note and invoice. The allocation's idempotency key is issue:<Idempotency-Key>; use it to filter the note's allocations after a lost response. Repeating the issue request with the same key and body recovers the original result. Reusing that key with different allocation inputs returns IDEMPOTENCY_KEY_REUSED.
Issuing without allocation or refund continues to leave the invoice balance unchanged.
API
Orders
Checkout
Gift-cards
Change a gift card purchase's face value before payment#
PATCH /v1/orders/{order_id}/line-items/{order_line_item_id} accepts gift_card_face_value_money, a non-null USD Money object, with the order's version as expected_version. Checkout credentials can send it with expected_version alone, or together with gift_card_recipient.
The value must fall within the custom amount range stored on the line's offer snapshot and cannot exceed 200000 cents. A line whose offer has no range accepts only its current value. An invalid value returns 400 INVALID_REQUEST with param: gift_card_face_value_money. The field applies only to an unpaid gift card purchase line with no funding. A funded line, or a line that is not a gift card purchase, returns 409 ACTION_NOT_ALLOWED with reason field_locked. A stale expected_version on a request that includes this field returns 409 VERSION_CONFLICT.
Flint reprices the line as the chosen face value times the offer's price, divided by its reference face value, and recalculates the line, the order total, and payment_collection. Sending the current face value leaves version unchanged.
API
Gift-cards
Gift card idempotency keys no longer conflict with automatic payments and refunds#
Gift card API requests can use an Idempotency-Key that matches a key used by an automatic gift card payment or refund without blocking that operation. Existing requests still replay their original results.
Breaking change
API
Invoices
Invoice payment attempts and activities no longer list expected_settlement_at#
Breaking:InvoicePaymentAttempt no longer lists expected_settlement_at. Flint never stored an ACH settlement estimate for invoice payment attempts, so responses never included the field. This includes payment attempts in collect and checkout session results, active_payment_attempt on buyer invoices, and invoice_payment_attempt.* webhooks. An ACH debit attempt stays processing until the debit settles or fails; listen for invoice_payment_attempt.succeeded or invoice_payment_attempt.failed.
InvoiceActivity also drops expected_settlement_at. The field read the same unset estimate, so payment-processing activities never included it.
The invoice reference also describes behavior that hasn't changed:
Invoice reads return collection and payment_due in the shape draft writes accept. merchant_default and customer_default resolve when the draft is written. See Defaults and reading back what you wrote.
reference is your reference and po_number is the buyer's purchase order number; both are printed. external_reference_id is your sync key and isn't printed.
currently_due_money is what the next collect call or checkout session charges. To total what is past due, add the outstanding_money of the schedule entries whose status is due or overdue.
When a subscription renewal waits on stock, Flint issues an open invoice with collection_block_status: inventory_blocked and refuses collection on it. When stock returns, Flint voids the invoice with collection_block_status: resolved and charges the renewal on its order. Earlier docs said the invoice became collectible again. See Collection blocks.
These changes apply to all supported API versions.
Merchant lists now support selected related resources through expand, including orders, payments, invoices, catalog items, returns, and payouts. For example, request /v1/returns?expand=order to include each return's order summary, or /v1/return-policies?expand=current_revision to include each policy's current revision. Policy revisions remain opt-in.
Expanded order summaries now include buyer_contact when the order retains recorded contact information. This includes guest orders without a customer record. The contact comes from the order, so it does not change when the customer's current email changes.
Inventory level and movement detail reads now support expand=inventory_item, using the same inventory item representation as their lists.
Expansion requires read access to each related resource. It preserves list order, IDs, and pagination tokens. Buyer and checkout credentials keep their existing expansion access.
Breaking change
API
Onboarding
Sandboxes
Onboarding uses the credential environment and readiness actions#
These changes apply immediately to every supported API version:
The credential selects the environment. An onboarding session token always acts in the merchant's default sandbox, a sandbox key acts in its sandbox, and a live key acts in live. To onboard another sandbox, create its key and use that key.
sandbox_id is no longer accepted on GET /v1/onboarding/state, POST /v1/onboarding/advance, POST /v1/onboarding/api-key, or POST /v1/merchant-account-sessions. POST /v1/api-keys also rejects the removed field.
OnboardingState.next_step uses ReadinessAction: action_type, owner, optional required_fields, and optional merchant_account_session. Submit advance_onboarding to POST /v1/onboarding/advance, use create_merchant_account_session to create a browser session, and use create_api_key to issue the first sandbox key. wait_for_review means poll state.
Action owners are integrator, merchant, or flint. code, machine_completable, submit_endpoint, submit_method, and launch are removed from onboarding steps.
Email verification no longer returns next_step. Read GET /v1/onboarding/state after verification.
requested_capabilities is one array schema. Include accept_card_payments and receive_payouts; optionally include accept_ach_debit_payments.
Update onboarding clients before deploying this server change. The CLI compatibility release must be installed before this change ships.
Breaking change
API
Orders
Inventory
Fulfillment
Order discounts and line-item fulfillment requirements renamed#
These changes apply immediately to every supported API version, including order.* webhook snapshots:
Order.discounts replaces applied_discounts. Its schema is OrderDiscount, replacing AppliedDiscount. The order_discount_id field, ad_ ID prefix, and discount routes stay the same.
OrderLineItem.fulfillment_requirements replaces fulfillment. Its schema is OrderLineItemFulfillmentRequirements; its direct and components fields stay the same.
Resolving an inventory exception keeps inventory_exception_reason as the original cause. Read inventory_exception_status: resolved for the outcome. The admin_resolved reason is removed. A merchant's resolution note appears in inventory_exception_resolution_message, which buyers cannot read.
Shipment and package creation schemas now publish the existing requirement to send external_system with external_reference_id.
Update order readers and webhook handlers to use the renamed fields.
Breaking: These nested payment intent routes are removed:
POST /v1/orders/{order_id}/payment-intents/{payment_intent_id}/capture
POST /v1/orders/{order_id}/payment-intents/{payment_intent_id}/cancel
Call POST /v1/payment-intents/{payment_intent_id}/capture or /cancel for every payment intent, including one owned by an order. Both routes use payments.payment_intents.write, accept an empty body, and return the payment intent flat in data. Omit order_payment_attempt_id; Flint finds the owning attempt. Read the order separately with GET /v1/orders/{order_id} or order webhooks.
Branch on the payment intent's supported_actions to choose an action. Remediation no longer returns the next-action values capture_order_payment or cancel_order_payment; it uses capture_payment_intent or cancel_payment_intent with the canonical route.
Order-owned confirmation still uses POST /v1/orders/{order_id}/pay. Refunds still use POST /v1/refunds.
These changes apply to all supported API versions.
POST /v1/organizations requires parent_organization_id. Omitting it, sending null, or sending a blank string returns 400 INVALID_REQUEST with detail code REQUIRED and param: "parent_organization_id". Flint creates each merchant's top-level organization; the API creates organizations below it.
PATCH /v1/organizations/{organization_id} can move an organization and its descendants under another active organization you can manage. Sending parent_organization_id: null returns 400 INVALID_REQUEST with detail code INVALID_VALUE; an organization cannot be detached from its parent.
PATCH /v1/merchant no longer accepts organization_id. Sending it returns 400 INVALID_REQUEST with detail code UNKNOWN_FIELD. Merchant responses always include organization_id, which Flint sets when creating the merchant.
Organization deletion is still refused with 409 RESOURCE_IN_USE while it has active child organizations or a merchant that isn't closed belongs to it, including your merchant's own organization. Delete child organizations from the bottom up. After deletion, API keys receive 404 on reads and no longer see the organization in lists, including with status=archived.
New partner apps have no client secret by default. Register a public JWK under /v1/partner-apps/{partner_app_id}/credentials, and authenticate code exchange, refresh, and revocation with RFC 7523 private_key_jwt assertions. Supported algorithms are ES256, ES384, PS256, RS256, and EdDSA. Discovery advertises the methods and algorithms for both token and revocation endpoints. To issue a client secret at creation, set client_secret_enabled: true explicitly.
Each assertion has iss and sub equal to the app's client_id, a single-string aud equal to the Flint issuer, an expiry at most 5 minutes ahead, and a unique jti. Assertions work once. Never combine an assertion with HTTP Basic or a client_secret form field.
Credential IDs start with pacr_. List, create, get, and delete credentials through the app's credentials routes. Credentials are immutable, and an app can have up to 20 active credentials. Register a replacement before deleting an old key; deleting stops that key from authenticating immediately.
Existing secret-based apps keep working. Add a credential, switch your workers, check its last_used_at, then PATCH the app with client_secret_enabled: false to end both current and previous secrets. The app also reports client_secret_last_used_at, updated at most hourly. To enable a secret again, use rotate-secret; setting client_secret_enabled: true on PATCH returns 400 INVALID_REQUEST.
Authorized dashboard sessions can use the partner-app management routes, with fresh identity verification for credential creation and secret rotation. Read the Partner app installs guide for registration, assertion signing, and migration examples.
Image moderation and attachment reconciliation now send payment_link.updated when they change a payment link's image. The event includes the payment link's updated image and version, just like an update through the payment links API.
A standard payment link line item can now offer several variants of one product. Send variant_ids instead of variant_id, with an optional default_variant_id, and the checkout page shows a control for each of the product's options. The buyer's order gets an ordinary variant line.
Create and update.variant_ids takes 1 to 100 unique variant IDs of one product, all active and priced in one currency. default_variant_id must be one of them. A line item has one source, so variant_ids can't be combined with variant_id, bundle_id, or ad hoc fields, and event links refuse it. Reads and payment_link.created and payment_link.updated webhooks return variant_ids, default_variant_id, the product's product_id, and a read-only resolved_price_range.
Public read. The line's resolved_line_items entry adds product_options and available_variants. Each available variant has its name, selected_options, price, image, modifiers, and is_sold_out, which is advisory and takes no hold.
Resolve.POST /v1/payment-links/{payment_link_id}/resolve accepts variant_selections, keyed by line item key. A line with a default can be left out of the map. Starting checkout still holds no stock; a variant that sold out before payment fails with INVENTORY_UNAVAILABLE.
Active links. You can change variant_ids and default_variant_id on an active link while every variant stays in the same product. Deactivating or archiving a variant is blocked only when it would leave an active link's variant_ids line with no active variant.
POST /v1/payment-reviews/{payment_review_id}/approve and POST /v1/payment-reviews/{payment_review_id}/decline now return 409 CONCURRENT_MODIFICATION when another write wins a race during review resolution. Previously, these conflicts returned 500 INTERNAL_ERROR.
The response sets remediation.retry to same_request. Retry the same request with the same Idempotency-Key.
Breaking: Payout destination routes move from /v1/payout-settings/destinations to /v1/payout-destinations. Use GET /v1/payout-destinations to list them and GET, PATCH, or DELETE /v1/payout-destinations/{payout_destination_id} for an individual destination. The old paths are removed. Operation IDs and the money_movement.payout_settings.read and money_movement.payout_settings.write scopes stay the same.
The destination list filter is now available_payout_methods. Repeat the parameter or send comma-separated values to match any listed method. The old available_payout_method parameter is rejected. GET /v1/payouts?method= now accepts standard, instant, and other, including combinations such as method=standard,instant.
PATCH /v1/payout-settings no longer accepts default_payout_destinations. Sending it returns 400 INVALID_REQUEST with param: default_payout_destinations, as for any unknown field. Payout settings responses still include the read-only map.
Deleting a payout destination always archives it and emits payout_destination.archived. An archived destination remains readable by ID. You can't delete the active default destination. A failed deletion returns the error without disabling the destination. Processor-driven disables still emit payout_destination.disabled.
Money movement list responses no longer declare meta.request_id. Use the response's top-level request_id.
Breaking change
API
Webhooks
Credentials use Authorization and public headers use consistent names#
Send credentials as Authorization: Bearer <token>. Authenticated routes refuse X-API-Key, X-Onboarding-Session-Token, and X-Developer-Session-Token, including when a valid Authorization header is also present. The response is 401 INVALID_CREDENTIAL with reason malformed and a param naming the obsolete header. Remove that header before retrying. Unauthenticated routes ignore these headers.
Demo creation and reset require Flint-Challenge-Token, which replaces X-Turnstile-Token. Get the token from Flint's hosted bot check on the page that offers the demo.
Flint-Rate-Limited-Reason uses these values: global_ip, api_key, customer, merchant, setup_flow, demo_session, resource, and feedback_intake. Update comparisons that use the previous kebab-case values.
Webhook deliveries send Flint-Webhook-Endpoint-Id in place of X-Flint-Webhook-Endpoint-ID. Delivery rate callbacks send Flint-Signing-Key-Ids in place of X-Flint-Key-IDs. Update receivers to read the new names before deploying this server change.
These changes apply across all supported API versions. Flint continues to generate its own request ID and treats a caller's X-Request-Id as separate tracing metadata.
Breaking change
API
Returns
Subscriptions
SDK
Explicit types for return and subscription line inputs#
<!-- Coordinated production cutover: production currently has no users, so the temporary write failures below are acceptable. Keep production closed to users until both apps run the reviewed commit. Record the previous backend and Dashboard image SHAs, then select backend and dashboard in deploy-production.yml with the same source_sha. The workflow deploys the report worker, backend, then Dashboard sequentially. Between the backend and Dashboard updates, the old Dashboard's untagged receipt, replacement, and subscription-line creation writes fail with 400 INVALID_REQUEST. Selecting both apps does not eliminate this window. If the Dashboard deploy fails, finish deploying Dashboard from that source_sha, or roll both backend (including its report worker) and Dashboard back to their recorded previous images as one recovery operation. Keep production closed throughout recovery; do not leave a mixed-version pair running. Verify the affected writes after both app deployments complete, before admitting users. -->
Return and subscription line inputs now require an explicit type, and return policy scopes require match_type. These changes apply to every supported API version:
Return replacement lines use variant with variant_id, bundle with bundle_id, or custom with name. A replacement update still keeps a line by its return_replacement_line_item_id, and each kept line also sends type. Buyer previews accept only variant and bundle.
Return receipt lines use matched, unverified, or excess. Matched and excess lines require return_line_item_id; unverified lines require unverified_item. Requests no longer accept verification_status. Receipt responses still include it.
Creating a subscription line uses variant or bundle, with the matching catalog ID and quantity.
Return policy scopes require match_type: all or match_type: include. Omitting it no longer selects all items.
Include these tags in nested arrays, return previews, and replacement updates. A missing tag returns 400 INVALID_REQUEST naming the required field. A field that belongs to another type returns a NOT_ALLOWED detail before the operation runs.
Use POST /v1/developer/sandboxes/{sandbox_id}/api-keys to create a test API key bound to a sandbox. Its operation ID is createSandboxAPIKey. The request, response, required scopes, and live-key requirement are unchanged; onboarding session tokens can still use the route.
The former /test-key route returns 404. Update callers to use /api-keys. This change applies immediately to every supported API version.
API
Subscriptions
Dashboard and Account use subscription PATCH updates#
Dashboard updates billing schedules through PATCH /v1/subscriptions/{subscription_id} with billing_schedule. Keeping a subscription clears its scheduled cancellation with cancel_at_period_end: false on the same endpoint.
Account uses PATCH /v1/me/subscriptions/{subscription_id} to change the saved card, delivery, billing interval, or quantity, and to undo a scheduled cancellation. A card-update link sends only payment_method_id; it grants no access to change other subscription fields.
The existing per-field API routes remain available. Their removal will follow after these app updates are deployed everywhere.
Merchant subscription responses now include supported_actions: the actions allowed by the subscription's state. The array can contain cancel, pause, resume, skip_cycle, renew, retry_payment, and change_plan. New actions may be added, so check for the actions you use.
The field appears in reads, lists, write results, renewal and plan-change results, and subscription.* webhook objects. Merchant subscription ACTION_NOT_ALLOWED error details carry the same list. A listed action can still be refused for a transient reason, such as a renewal already in progress or an unusable saved payment method.
Buyer subscription responses continue to use buyer_actions. Buyer responses and refusals omit supported_actions. Undo a scheduled cancellation with cancel_at_period_end: false on PATCH; reactivation is a field update, so it is not listed in supported_actions.
These webhook changes apply immediately to every supported API version:
subscription.payment_failed is removed. Use subscription.past_due for entry into dunning, subscription_payment_retry.failed for a manual retry failure, and subscription.dunning_exhausted when automatic retries end. subscription.payment_succeeded still reports a paid period advance.
invoice.delivery_succeeded and invoice.delivery_failed are removed. Use invoice_delivery_attempt.sent, .failed, and .suppressed. Their data.object is the delivery attempt, including invoice_delivery_attempt_id and the new read-only invoice_id. The delivery-attempt list also includes invoice_id. A first successful invoice send still sends invoice.sent; a reminder sends only the delivery-attempt event.
customer_deletion_request.processing and .failed report each entry into those statuses, including after a retry.
fulfillment.status_changed is removed. Terminal transitions send fulfillment.completed, .canceled, or .failed. Other changes, including accept, hold, and release, send fulfillment.updated.
custom_domain.updated replaces custom_domain.status_changed. Archiving a domain sends custom_domain.archived; repeating the archive sends nothing.
merchant.updated reports changes to the merchant profile, business name, status, API version, logo, or icon. Readiness changes still send merchant.readiness_updated.
Update endpoint subscriptions and test-event requests to current names. Stored subscriptions and events map custom_domain.status_changed to custom_domain.updated. Removed event subscriptions are dropped. Custom domain and merchant events remain merchant-only. The new invoice delivery attempt, deletion request, and fulfillment events support partner delivery with the resource's read permission.
Breaking change
API
Webhooks
Webhooks verify with Flint’s public keys by default#
New webhook endpoints default to signing_methods: ["jwt"]. Flint signs every delivery attempt with ES256. Verify the bearer JWT with Flint's public JWKS, using the endpoint ID as the audience and checking the raw-body hash. JWT-only endpoints have no shared secret issued, stored, or returned. The Webhooks guide includes a Node verification example and key-cache rules.
This default applies across supported API versions. Existing endpoints keep their signing methods. To migrate one, PATCH signing_methods to ["jwt", "hmac"], deploy JWT verification, then replace the set with ["jwt"]. Removing hmac deletes its current and previous secrets and their expiry. New attempts, including queued retries, use the new configuration; an attempt already authorized before the update may still sign with the earlier configuration. URLs with a username or password are invalid with JWT signing.
To keep shared-secret verification on a new endpoint, explicitly send ["hmac"] or ["jwt", "hmac"]. These create responses return secret once. signing_methods is always present on endpoint responses; PATCH replaces it, requires the current expected_version, and rejects empty, unknown, and duplicate values. Adding hmac through PATCH without a secret returns 409 ACTION_NOT_ALLOWED with reason secret_not_issued. Call rotate-secret to issue the first secret and add hmac, or to rotate an existing secret.
Delivery rate callbacks continue to use Standard Webhooks HMAC signatures.
After an outage, queued webhook deliveries now retry in bounded batches. Due retries for each endpoint run one at a time, with a short pause between deliveries in a batch, to reduce bursts against your endpoint.
Retry delays, attempt limits, and delivery signatures stay the same. Delivery order is still not guaranteed across initial deliveries, retries, and manual resends.