Skip to content
Changelog

Week of November 9, 2026

122 changes to the Flint API, SDKs, and docs, newest first, from November 9, 2026 to November 14, 2026. The newest changes are on the changelog.
  • Breaking change
  • API
  • Returns

Restocking percentages must be valid on every return policy revision#

When you create a return policy or add a revision, a percent restocking fee must be from 1 through 100 percentage points with at most four decimal places, whatever the revision's eligibility_result.

Previously, ineligible revisions accepted percentages outside this range. They now return a validation error at revision.restocking_fee.percent. Ineligible revisions still store valid fees without applying them. Eligible and review_required revisions keep the same validation.

Before sending an ineligible revision, remove its restocking fee or set a percentage within the range. The OpenAPI schemas now publish the range unconditionally.

  • API
  • Returns

Preview store credit before requesting a return#

POST /v1/return-previews and POST /v1/me/return-previews with mode: eligibility now include explicitly selected eligible store-credit quantities in eligibility.refund_estimate. buyer_store_credit_amount_money estimates the credit after policy deductions using the same remaining settled value as approval. store_credit_destination is new_gift_card, delivered by email.

The existing refund totals and tender_estimates still cover original-payment refunds only. A store-credit-only selection has zero refund totals and an empty tender list. refund_estimate is null when neither refund nor store-credit quantities qualify. The store's inspection and final decision can change the estimate; nothing is reserved.

  • Breaking change
  • API
  • Subscriptions

Subscription quantities now live on lines#

Breaking: subscription and subscription-plan APIs no longer accept or return the subscription quantity multiplier or quantity_options. This includes merchant and buyer reads, plan summaries, scheduled changes, subscription PATCH, change-plan, and previews. Plan create and PATCH no longer accept quantity choices or reset fields. Subscription line PATCH accepts variant swaps; use change-quantity to edit quantities. Line creation still accepts quantity.

For example, these old terms billed six seats:

JSON
{
  "quantity": 3,
  "line_items": [{ "quantity": 2 }]
}

The equivalent terms now put all six seats on the line:

JSON
{
  "line_items": [{ "quantity": 6 }]
}

For digital seats, mark the plan's seat line allow_quantity_adjustment: true and set min_quantity and max_quantity for buyers. The line quantity is the seat count; nothing multiplies it. Merchants can set line quantities from 1 to 9,999. For physical goods sold together, use a bundle line whose components describe the box contents, and set the number of boxes on that line.

At signup, send plan line IDs under terms.line_items on POST /v1/subscriptions or the subscription inside a create preview:

JSON
{
  "terms": {
    "type": "subscription_plan",
    "subscription_plan_id": "plan_123",
    "line_items": [{ "subscription_plan_line_item_id": "spli_123", "quantity": 6 }]
  }
}

Signup and change-plan overrides identify target plan lines. To change an existing subscription, use its saved subscription line IDs:

JSON
{
  "billing_starts": "period_end",
  "line_items": [{ "subscription_line_item_id": "sli_123", "quantity": 6 }]
}

Send this body to POST /v1/subscriptions/{subscription_id}/change-quantity with an Idempotency-Key. line_items is required, contains 1 to 50 distinct subscription line IDs, and leaves omitted lines unchanged. next_renewal changes quantities immediately and bills them at the next unpaid renewal. period_end keeps current quantities until the next charged renewal. prorated_now charges the difference for eligible digital lines now and keeps the billing period and anchor. Preview the immediate charge using subscription preview mode quantity_change, billing_starts: prorated_now, and the same line_items.

Buyer /v1/me quantity changes require the frozen adjustable line and respect its bounds. Buyers may use period_end or prorated_now; previews support prorated_now.

Removed request fields return 400 UNKNOWN_FIELD, including an explicit legacy quantity: 1. New subscription.* webhook payloads use the same Subscription projection and omit the removed fields. Previously stored webhook payloads remain unchanged.

Regenerated SDKs carry this breaking contract in SDK 8.0.0. Replace scalar subscription quantity inputs and reads with line quantities before upgrading. Checkout and payment-link quantity fields are being removed in a separate contract change.

Checkout sessions and payment links use the same line quantities. Checkout create and PATCH, including payment-link checkout, no longer accept subscription_terms.quantity. Returned CheckoutSubscriptionTerms no longer includes quantity or quantity_options, and PaymentLinkSubscriptionPreview no longer includes quantity_options. Old fields sent by callers return HTTP 400 with detail UNKNOWN_FIELD.

Before, a checkout multiplier of three applied to a plan line containing two seats:

JSON
{
  "subscription_terms": {
    "quantity": 3
  }
}

Now, select six seats on the identified plan line:

JSON
{
  "subscription_terms": {
    "line_items": [
      { "subscription_plan_line_item_id": "spli_01ARZ3NDEKTSV4RRFFQ69G5FAV", "quantity": 6 }
    ]
  }
}

The same input sets the number of physical bundles when the identified line is a bundle. Buyers may change only an adjustable line within its frozen bounds. Merchant credentials may set any line from 1 to 9,999. Billing interval and gift recipient choices remain available.

  • API
  • Payments

Order payment attempts include their order ID#

OrderPaymentAttempt and BuyerOrderPaymentAttempt now include order_id, the order the attempt belongs to. It appears beside order_payment_attempt_id in reads, lists, payment results, and embedded attempts. Use both IDs to address the attempt under /v1/orders/{order_id}/payment-attempts/{order_payment_attempt_id}.

  • Breaking change
  • API
  • Credit_notes

Buyer credit notes use top-level routes#

Breaking: the three buyer credit-note routes have moved. The old paths are removed.

Old routeNew route
GET /v1/me/invoices/{invoice_id}/credit-notesGET /v1/me/credit-notes?invoice_id={invoice_id}
GET /v1/me/invoices/{invoice_id}/credit-notes/{credit_note_id}GET /v1/me/credit-notes/{credit_note_id}
GET /v1/me/invoices/{invoice_id}/credit-notes/{credit_note_id}/pdfGET /v1/me/credit-notes/{credit_note_id}/pdf

With a customer session, omit invoice_id to list issued and voided notes across the buyer's invoices. With an invoice access token, the list stays limited to that invoice. The exact invoice_id filter, status, page_size, and page_token follow the usual list conventions. Notes on other buyers' invoices and unknown IDs return 404. PDF content and private, no-store caching are unchanged.

The pinned CLI catalog no longer lists the removed commands. The replacement commands will be flint me credit-notes list --invoice-id, flint me credit-notes get, and flint me credit-notes pdf get when the CLI regenerates its catalog.

See Show credit notes to the buyer.

  • Breaking change
  • API
  • Checkout
  • Settings

Checkout-created orders report checkout origin#

Orders created by subscription plan and Quick Pay checkout sessions now report origin: "checkout" and their payments report payment_flow: "checkout", replacing api. This applies whoever created the session. Order list filters, inventory origin_policies, and return policy channel scopes use checkout for these new orders. Review any policy that treats api and checkout differently.

Payment-link orders keep payment_link. Opening a checkout session on an existing order preserves that order's origin. Existing orders retain their recorded origin. Subscription billing orders, such as renewals, use subscription. Payment limits keep their existing surfaces: subscription for signup and checkout for Quick Pay.

GET /v1/settings/effective now fills unset checkout payment options with card, Apple Pay, and Google Pay; the session lifetime with 86400 seconds; required buyer fields with false; and the default line-item tax category with general. It adds read-only payment_limits.effective_max_amounts and effective_min_amounts for every supported exact payment option and surface. Effective maximums include support approvals. Stored settings and payment enforcement keep their behavior.

  • API
  • Checkout
  • Refunds

Read refunds from a checkout session#

GET /v1/checkout-sessions/{checkout_session_id} now includes refunds: all buyer-visible refunds on the session's order, including ordinary store refunds and payment returns. Items use the same BuyerRefund projection as /v1/me/refunds, with status, amount and currency, creation and update times, and parent IDs. Earlier payment and tender details are included only as the buyer projection already exposes them.

The array is [] when there are no refunds. Both merchant and checkout credentials receive the buyer projection, with coarse failure categories and no processor codes, store reasons, or staff notes and reason codes. The field is omitted from other responses and webhooks.

The buyer projection also gains failure_reason and the parent payment_intent_id when applicable. A failure is reported as refund_failed or refund_abandoned. For refund_abandoned, tell the buyer the refund could not be completed and to contact the store to get their money back. This additive change does not add a public way to abandon a refund or change how money moves.

  • Breaking change
  • API
  • Invoices
  • Subscriptions
  • Returns

Child creates name their parent version#

Replace expected_version on these creates:

  • POST /v1/credit-notes/{credit_note_id}/allocations: expected_credit_note_version.
  • POST /v1/invoices/{invoice_id}/manual-payments: expected_invoice_version.
  • POST /v1/subscriptions/{subscription_id}/line-items: expected_subscription_version.
  • POST /v1/return-policies/{return_policy_id}/revisions: expected_return_policy_version (still required).
  • POST /v1/returns/{return_id}/line-items: expected_return_version.

Send the parent's version from your last read. Stale versions still return 409 VERSION_CONFLICT, and idempotency replay keeps the same behavior. The old field returns 400 INVALID_REQUEST at expected_version.

GET /v1/invoices/{invoice_id}/late-fees and GET /v1/subscriptions/{subscription_id}/line-items now list that parent's children. Both accept page_size and page_token, return next_page_token, and sort by child ID in ascending order. They accept the same credential types as their creates, with read scopes.

  • Breaking change
  • API
  • Payment_intents
  • Orders

Create order payments through the payment intents collection#

POST /v1/orders/{order_id}/payment-intents is removed. Send order_id in the body of POST /v1/payment-intents instead. Both standalone and order-owned creates use payments.payment_intents.write; creating an order leg no longer uses commerce.orders.write.

JSON
{
  "order_id": "ord_01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "capture_method": "manual"
}

The remaining order-leg fields and rules stay the same. Omit amount_money to use the order's outstanding balance. Send expected_order_version to refuse creation if the order changed since your last read. Customer, receipt, tip and bank-debit purpose come from the order, so their standalone create fields aren't accepted with order_id.

The response still returns the payment intent flat in data, with payment_collection for online payments. Confirm order legs through the order's pay route. List an order's payments with GET /v1/payment-intents?order_id=ord_...; order_id is an exact-match filter.

  • Breaking change
  • API
  • Invoices
  • Orders
  • Payment-links

Custom lines can declare a product type for ACH#

Custom lines on invoices, orders, and payment links now accept optional product_type: physical, digital, service, or fee. Set "product_type": "service" on a custom service line to identify its purpose for ACH debit. Custom lines reject gift_card.

Omitting the field leaves a custom line unclassified. Stored line responses return product_type: null for unclassified lines. ACH debit requires a resolvable purchase purpose; card payments remain available without classification. Classification does not change tax, delivery, or inventory.

Catalog variant and bundle lines reject product_type because they use the catalog's classification. Their delivery-preview response schemas now explicitly exclude this field.

Issued invoices keep their frozen classification. Void and reissue an unclassified invoice to change it.

  • Checkout

Open your Flint wallet with a texted code#

In Flint's hosted checkout, returning buyers can receive a code at the mobile number they added to their Flint wallet. Confirming it opens their wallet's cards and addresses. An emailed code remains available, and removing or replacing the number ends its access in open checkouts.

Headless checkouts keep using the store's saved-details number or the buyer's email.

  • Breaking change
  • API
  • Invoices
  • Subscriptions

Invoice credits and subscription previews use distinct money names#

Update these public field names:

  • Invoice activities and schedule entries rename credit_money to credited_money. The amounts keep their existing meaning.
  • Subscription plan-change and quantity-change previews rename credit_money to credit_adjustment_money. This is the credit for unused paid time. Its amount and nullable presence stay the same on merchant and buyer previews.
  • Breaking change
  • API
  • Invoices

Invoice pricing totals move out of the snapshot#

Read pricing_amounts on the invoice instead of snapshot.pricing_amounts. Read pricing_amounts.total_money instead of the flat total_money.

These paths apply to merchant and buyer invoice reads, mutation results, expanded invoice summaries, checkout session invoice results, and invoice webhook objects. Expanded summaries now include the same pricing fields as full invoices.

Draft pricing previews the backing order. Issuing an invoice freezes its pricing, including the additive and inclusive tax amounts. Late fees stay outside the billed total.

  • Breaking change
  • API
  • Invoices

Invoice payments and balances now use settlement_amounts#

Invoice payments and balances move into settlement_amounts on merchant and buyer reads, mutation results, expanded invoice summaries, and invoice webhook objects. Their flat copies are removed.

  • Read settlement_amounts.paid_money, settlement_amounts.refunded_money, settlement_amounts.outstanding_money, settlement_amounts.written_off_money, settlement_amounts.currently_due_money, and settlement_amounts.late_fee_money.
  • Read settlement_amounts.credited_money instead of flat credit_money. It measures allocated credit notes, minus reversed allocations.
  • On merchant and buyer invoice lists, send sort_by=settlement_amounts.outstanding_money. The old flat sort name is rejected. Ordering and pagination keep their existing behavior.
  • InvoiceSettlementAmounts extends the shared five-field SettlementAmounts core with credited_money, currently_due_money, and late_fee_money.
  • settlement_amounts.net_collected_money is payments minus refunds, never below zero. Invoice dispute losses do not reduce it. Buyer invoices now include written_off_money in the group.

Invoice pricing moved into pricing_amounts. Collection, credit allocation, write-offs, and refunds keep their existing behavior.

  • API
  • Invoices
  • Subscriptions

Invoice and subscription references include parent IDs#

Invoice late fees and activity rows now include required invoice_id. Invoice snapshot lines include required order_id beside order_line_item_id.

Subscription lines include required subscription_id, including frozen lines in a scheduled plan change. Renewal estimate lines include required nullable subscription_id; it is null when subscription_line_item_id is null for a new or replacement line.

Subscription delivery destinations and service locations include required nullable customer_id beside a saved customer_address_id. It is null when the saved address reference is absent or withheld from the buyer projection. Merchant and buyer responses and webhook snapshots carry the same parent IDs for references they expose. Saved-address request inputs still accept customer_address_id alone.

  • Breaking change
  • API
  • Invoices
  • Payments

Invoices offer Apple Pay and Google Pay by default#

New buyer_initiated invoices use card, apple_pay, and google_pay when no payment options are configured. Previously, this fallback offered only card.

An explicit collection.payment_policy takes precedence over invoices.payment_policy, then checkout payment options, then the platform default. Explicitly empty option lists are still rejected. The default resolves when the draft is written and its policy is stored. Existing drafts and issued invoices keep their stored policies when settings change.

Apple Pay and Google Pay appear only on supported devices over HTTPS with the payment domain registered. Account readiness, platform blocks, and invoice amount limits still apply. Automatic invoice recovery stays card-only, and external invoices offer no online payment.

To keep new buyer-initiated invoices card-only, set invoices.payment_policy.enabled_payment_options to ["card"] or send that option list in collection.payment_policy.

See invoice collection.

  • API
  • Payments
  • Partners

Marketplaces can split one payment between sellers#

A marketplace that collects a payment as the merchant of record can divide it between its sellers. Create the payment with splits, one entry per seller install, and each split moves into the seller's own Flint balance after the payment's funds are available and any dispute has closed. The seller's normal payouts carry it to its bank account.

The new Marketplaces and seller splits guide covers the whole flow:

  • Declaring payment_splits and your seller terms, and how sellers approve them.
  • Creating a payment with splits, and initializing Stripe.js without stripeAccount.
  • When sellers are paid, with pending_reason and funds_available_at.
  • Refunds with and without split_reversals, disputes, and negative seller balances that the marketplace covers.
  • Reconciling with the six split balance transaction types, and the payment_split.* events.

It also tells splits apart from split tender, where one order is paid with several payment methods, and from inventory transfers. The marketplace page on withflintpay.com summarizes the same rules.

Live splits need Flint's approval. Test mode works now and needs no review. Live splits are switched off by default and are available after Flint approves your platform for splits. Flint's Platform Agreement says Flint doesn't accept splits yet and that it will publish the rules for sending, reversing, and recovering split funds before it does. A live request with splits returns 409 MERCHANT_NOT_READY with reason payment_splits_unavailable.

Splits don't cover checkout sessions, payment links, invoices, subscriptions, saved payment methods, paying a seller's bank account directly, or holding a split until delivery.

The API descriptions of the payment_splits capability and an environment grant's payment_splits no longer say that no request accepts splits. Build payments into your platform, Migrating from Stripe, and the platform pages now describe splits where they previously said Flint can't split one payment across sellers.

  • Breaking change
  • API
  • Orders
  • Payment_intents

Create a ConfirmationToken for every payment collection#

payment_collection.stripe.elements.next_step now returns create_confirmation_token for every payment-mode read. Previously, merchant-authenticated order reads returned collect_payment_source; checkout-session and standalone payment intent reads already returned create_confirmation_token. The unused collect_payment_source enum value is removed.

After elements.submit(), call stripe.createConfirmationToken({elements}) and send its ID as payment_source: {credential_type: "stripe_confirmation_token", stripe: {confirmation_token: "ctoken_..."}} on order pay. Standalone confirm keeps its current top-level credential_type: "stripe_confirmation_token" and stripe.confirmation_token fields. Follow submit_to: pay_order on order reads and confirm_payment_intent on standalone reads.

Setup collection still returns collect_setup_payment_source with mode: "setup". Create a PaymentMethod with stripe.createPaymentMethod for that step. Existing PaymentMethod and saved-card inputs remain accepted; this change unifies the browser guidance. See Embedded payments.

  • Breaking change
  • API
  • Payment-intents
  • Orders

One payment credential on confirm and order pay#

Payment credentials now use the same payment_source object on standalone confirm and order pay. Its credential_type selects one closed branch:

BeforeNow
Confirm: top-level credential_type, payment_source_token, payment_method_id, or stripeConfirm: payment_source contains the discriminator and its matching fields.
credential_type: token with payment_source_token on confirm or token on paycredential_type: stripe_payment_method with stripe.payment_method, inside payment_source.
credential_type: payment_method with payment_method_idThe same fields inside payment_source, with optional customer_presence (present by default, or absent for merchant charges using a reusable saved card).
credential_type: stripe_confirmation_token with stripe.confirmation_tokenThe same fields inside payment_source.
Confirm: top-level credential_type: reader, reader_id, optional tipThe same reader fields inside payment_source. Reader scopes, credentials, restrictions, and behavior are unchanged.
Confirm: credential_type: attachedOmit payment_source, for example {}.
Order confirm_payment_intents: credential fields beside payment_intent_idEach item is {payment_intent_id, payment_source?}. Omit its payment_source to use the attached source.
Order setup_payment_source: credential_type: token, tokencredential_type: stripe_payment_method, stripe.payment_method. Other branches are refused.

For example, confirm a standalone payment with:

JSON
{
  "payment_source": {
    "credential_type": "stripe_payment_method",
    "stripe": {"payment_method": "pm_card_visa"}
  }
}

A Stripe PaymentMethod is a provider credential. A Flint saved payment method uses the payment_method branch instead. Invoice collection and subscription scheduling keep their plain payment_method_id.

Omitting payment_source confirms an attached source in requires_confirmation, or refreshes and returns the state and action in requires_action. Nothing attached returns 400 INVALID_REQUEST, detail REQUIRED at payment_source.

Error params follow the submitted shape, such as payment_source.stripe.payment_method and payment_intents[0].payment_source.payment_method_id. Conflicting credentials return INVALID_REQUEST with NOT_ALLOWED and conflicting_fields naming the discriminator. Update request bodies and error-field handling together.

  • Breaking change
  • API
  • Payments
  • Subscriptions

Separate payment lifecycle actions from buyer tasks#

Payment intent and subscription expanded summaries now carry the same required supported_actions array as the full merchant resource. Order and invoice payment attempts also carry this array. An attempt lists cancel while it can be canceled, or [] when it cannot. Capture acts on a payment intent; resuming an order attempt uses the order's pay route. Attempt refusals no longer list the nonexistent attempt actions capture or resume.

Buyer payment intents, payment attempts, and their expanded copies omit supported_actions, including retained responses. Buyer tasks stay in buyer_actions. Merchant subscriptions omit buyer_actions; buyer subscriptions keep it, including update_quantity and retry_payment.

retry_payment is removed from the merchant subscription action vocabulary. To retry a past-due subscription's payment, create a payment retry with POST /v1/subscriptions/{subscription_id}/payment-retries. The buyer's retry_payment task uses the matching /v1/me child-create route.

  • API
  • Refunds

Refund line item and tax references include their order#

Refund line item allocations now include required order_id beside order_line_item_id. Tax breakdown refunds also include required order_id, including entries that reference order_charge_id and entries nested under line item allocations.

Refund responses, refund lists, embedded refunds, events, and webhook payloads that return these references carry the same order IDs. Request fields are unchanged.

  • API
  • Checkout

Manage remembered buyers from your buyer account#

GET /v1/me/remembered-buyers lists every working remembered buyer for the customer's email at your business, up to ten, newest use first. POST /v1/me/remembered-buyers/{remembered_buyer_id}/revoke forgets one. Both require a full customer session and never list or touch identities remembered across stores on Flint's checkout host. Customer-session responses omit code_channel.

When the required notice email is configured, confirming a checkout code with remember_buyer: true can now remember the buyer. Flint sends a merchant-branded notice once for each new remembered device, including headless checkouts and custom domains. Renewing its checkout token sends no additional email. The notice links to a confirmation page that can forget only that device without signing in. Opening the link changes nothing, and removing the device leaves saved cards saved.

See Remembered buyers for the routes and notice behavior.

  • Breaking change
  • API
  • Returns
  • Invoices

Return completion and invoice attempt success statuses#

Breaking: Return and ReturnLineItem resolution_status now use completed instead of fulfilled. The Return aggregate uses partially_completed instead of partially_fulfilled. ReturnResolution status now uses completed instead of fulfilled. These names apply to merchant and buyer responses, list filters, expansions, and webhook snapshots.

The meanings stay the same. A completed resolution means every linked Refund succeeded, any buyer balance was collected, and any replacement Order's fulfillment_status is fulfilled or not_applicable. Canceled approved quantity still counts as completed in a Return's value summary. Read the Return's status to distinguish cancellation from delivered value. Only the Return aggregate can be partially_completed.

Breaking: InvoicePaymentAttempt status now uses succeeded instead of settled. Subscribe to invoice_payment_attempt.succeeded instead of invoice_payment_attempt.settled. A successful attempt can pay part of the invoice balance. invoice.paid still means the invoice balance was cleared. The settled_at and fulfilled_at timestamp field names stay the same.

  • Breaking change
  • API
  • Returns
  • Webhooks

Separate Return lifecycle actions from buyer tasks#

Merchant Returns omit buyer_actions. Buyer Returns retain their tasks in buyer_actions and omit merchant supported_actions, including nested Return lines and resolutions. Use the available withdraw, ship_items, and pay_balance tasks to build buyer controls.

A requested or open Return lists process. Merchant lifecycle action lists and refusal details depend on stored state, independently of the credential's scopes. Permission checks still apply when a caller attempts the action. Return webhook objects carry the same action lists as merchant reads.

checkout_session is removed from the Return resolution action vocabulary. When a resolution's action_reason is buyer_payment, create a checkout session with type return_resolution. This child create remains available through the buyer's pay_balance task.

  • Breaking change
  • API
  • Returns

Return policy schemas publish validation limits#

Return policy schemas now publish nonnegative revision priorities, return windows from 1 through 158,112,000 seconds, scope lists with at most 100 unique values, and policy versions starting at 1.

For eligible and review_required revisions, a percent restocking fee must be from 1 through 100 percentage points with at most four decimal places. The schema applies the range conditionally. An ineligible revision stores the fee but ignores it. The percent range is not enforced on an ineligible revision, but the four-decimal precision limit still applies.

Names must contain 1 through 255 bytes after surrounding whitespace is trimmed. The list query allows up to 255 bytes after trimming; a blank query is ignored. Product, variant, and location scope values must be nonblank and at most 255 bytes before trimming. Category handles are trimmed first, must be unique after trimming, and must contain 1 through 100 ASCII characters using lowercase letters and digits separated by single hyphens.

These corrections can change generated client validation. API validation and fee calculations are unchanged. Raw string length limits are omitted where they would reject accepted inputs with surrounding whitespace.

  • API
  • Returns
  • Inventory

Return references include their parent IDs#

Return responses now include required parent IDs beside child references. Return line references carry return_id, order line references carry order_id, receipt and inspection line references carry return_receipt_id or return_inspection_id, and policy revision references carry return_policy_id. These fields appear in lists, previews, and webhook snapshots too. A nullable reference has a null parent ID when the reference is null.

Buyer responses include the IDs of the buyer's own Return and Order. Merchant-only receipt, inspection, and policy references stay private. Eligibility request line items still use the order named by the enclosing request.

  • Breaking change
  • API
  • Checkout
  • Payment-methods

Confirm a saved checkout card after paying#

POST /v1/orders/{order_id}/pay now accepts save_payment_method: true without a mobile number when save_payment_method_requires_verification is true. Previously, the buyer had to confirm their email before paying. The new card stays pending for the customer with the payment's email and works for nothing until the buyer confirms an emailed code on the receipt.

For a save without a number, payment_method_save reports status: "pending" and email_confirmation_required: true, with no phone_last_digits. Request purpose: "confirm_saved_payment_method", channel: "email", then confirm the code. The card is saved by email. The code goes only to the email given with the payment while it is still the customer's email. A save with no number refuses channel: "sms".

Pending saves also report email_confirmation_required: true from the moment a save is pending when a number alone cannot save the card. Previously, this became true only after the buyer confirmed a texted code. Read the flag before requesting a receipt code: when true, request an emailed code first. Confirming it saves the card by email without adding the number. A caller that confirms a texted code first can still finish with an emailed code, saving the card with the number.

Checkout customer verifications with channel: "sms" and purpose use_saved_payment_methods now include the read-only boolean can_use_email_code. Offer an emailed code only when it is true: the email would open cards saved by email at your business, or a Flint wallet where the checkout offers one. An explicit email request still works when the flag is false and keeps its neutral response.

The 24-hour confirmation window, request limits, and subscription signup and setup verification requirements are unchanged. An emailed code still opens only cards saved by email; it never opens cards saved with a phone number. See saved cards and headless checkout.

  • Breaking change
  • API
  • Checkout

Saved cards require a fresh code for a new delivery address#

A saved-card payment now returns 409 ACTION_NOT_ALLOWED with reason verification_required when the checkout's customer came from a confirmed code, the delivery address is new to that buyer, and the paying credential's last confirmed code is more than 15 minutes old. This applies to headless checkouts and buyers who typed their email as well as remembered buyers.

Read pay_to_new_address_requires_verification on the checkout session before offering Pay. When it is true, request a code with {"purpose": "pay_to_new_address"}, confirm it, and retry the payment with the same credential. Confirmation keeps the credential and the cards its proof opens, and refreshes the code confirmation for 15 minutes. Code requests use the existing limits.

Earlier paid orders and saved addresses at your business count as known destinations. For a Flint wallet card, addresses in that wallet count too. Pickup, orders that ship nothing, merchant-named customers, newly entered cards, Apple Pay, and Google Pay are unaffected.

Read Pay with a saved card to a new address for the request and routing rules.

  • Breaking change
  • API
  • Returns

Return creates use top-level collections#

Breaking: four create routes have moved. The old routes are removed. Send return_id in the JSON body at the new route:

Old routeNew route
POST /v1/returns/{return_id}/inspectionsPOST /v1/return-inspections
POST /v1/returns/{return_id}/receiptsPOST /v1/return-receipts
POST /v1/returns/{return_id}/dispositionsPOST /v1/return-dispositions
POST /v1/returns/{return_id}/resolutionsPOST /v1/return-resolutions

Each collection supports GET with an exact return_id filter. Individual reads stay at /v1/return-inspections/{return_inspection_id}, /v1/return-receipts/{return_receipt_id}, /v1/return-dispositions/{return_disposition_id}, and /v1/return-resolutions/{return_resolution_id}.

Permissions, parent version checks, inventory effects, and resolution effects keep the same behavior. Receipts, inspections, and dispositions still require Idempotency-Key; resolutions accept an optional key. Retry a lost response with the same key and body. Reusing a key at the same route for a different Return returns 409 IDEMPOTENCY_KEY_REUSED.

  • Breaking change
  • API
  • Subscriptions
  • Payments
  • Webhooks

Subscription retries name their payment intent#

Breaking: SubscriptionPaymentRetry replaces order_payment_attempt_id with payment_intent_id. Update merchant reads, /v1/me reads, and handlers for subscription_payment_retry.created, subscription_payment_retry.succeeded, and subscription_payment_retry.failed to use the payment intent ID. The webhook payload change applies to data.object; event names stay the same.

A retry is a command to charge again. payment_intent_id names the payment it starts and is set before the charge is sent. It is omitted while the retry is pending or when no payment intent was created. Read that payment intent for its status and history. A retry that needs buyer authentication ends failed with last_payment_error.code: authentication_required; update the subscription's payment method before retrying.

Breaking: The first billing period's charge of an API-created subscription, including retries of that first charge, now reports payment_flow: subscription_initial instead of subscription_renewal. Setup fees also use subscription_initial. Later billing periods keep subscription_renewal. Update filters and reports that treated every recurring charge as a renewal. Existing payment intents retain their recorded flow.

See Recover with a new card and the webhook catalog.

  • Breaking change
  • API
  • Subscriptions
  • Checkout

Subscription quantities use individual lines#

The subscription multiplier now accepts only 1 or omission. This applies to subscription creation, merchant and buyer updates, plan changes, quantity changes, previews, and checkout subscription_terms.quantity, including checkouts opened from payment links. Other values return 400 INVALID_REQUEST at the quantity field.

On plan creation and updates, quantity_options accepts only omission, [], or [1]. Other lists return 400 INVALID_REQUEST.

Use individual subscription line quantities for seats or multiple units. Existing subscriptions at quantity 1 keep the same prices and can still update and preview when their stored terms include older quantity options.

  • Breaking change
  • API
  • Subscriptions
  • Refunds
  • Webhooks

Full automatic inventory refunds cancel signup subscriptions#

When Flint automatically refunds an entire subscription signup order because inventory cannot be fulfilled, its subscriptions now become canceled immediately. Previously, they stayed active and could renew. Flint clears the next billing date, stops renewal billing, and sends the usual cancellation email to the buyer. The full refund is the only refund; cancellation adds no proration.

The subscription and its subscription.canceled webhook report cancellation_reason: "signup_order_refunded" and a canceled_at timestamp. A partial automatic refund or a full refund requested by the merchant leaves the subscription unchanged.

  • Breaking change
  • Webhooks
  • Sdks

Webhook types exclude fields that deliveries leave out#

Breaking: OpenAPI webhook object schemas now exclude the GET-only fields listed in the webhook event catalog. Regenerating SDKs removes these fields from webhook object types and their previous attributes.

For example, payment intent webhook objects exclude processing_fee_money, add_on_fees, and merchant_net_money. Checkout session webhook objects exclude computed branding and payment method saving fields. Read the resource with GET when you need these values.

Webhook deliveries keep their existing payloads. GET response types retain their fields.

  • API
  • Inventory
  • Checkout

Carry cart stock holds into checkout#

Your merchant server can send inventory_reservation_ids on POST /v1/delivery-quotes and POST /v1/delivery-selections to carry merchant-created cart holds into the order. The quote counts eligible held stock without changing it. The selection transfers matching held units into the order's hold in the same transaction. Unused cart units stay held, and remaining demand uses available stock.

Both inputs require a merchant credential with delivery write access. Checkout credentials that send the field get 400 INVALID_REQUEST before any reservation lookup. The buyer can pay after the merchant server selects delivery. Reservations from another merchant or environment, expired holds, and reservations owned by an order or payment are refused as not found. The existing release-before-checkout path remains available, for buyer-driven checkout and orders without delivery.

Partial adoption emits inventory_reservation.updated with the previous line quantities. Full adoption closes the cart reservation with closed_reason: adopted and emits inventory_reservation.released. Selections that omit or change the IDs acquire stock normally and cannot rely on the quote’s routing credit.

See Holding stock outside a Flint order and Collect delivery.

  • API
  • Checkout

Prefill the recipient's name on a checkout session#

POST /v1/checkout-sessions now accepts prefill.shipping_recipient_name: who receives the delivery. Send it with shipping_address so the buyer has nothing to type.

The name is optional, accepted without an address, and trimmed. It must contain 1 to 200 characters. Both your API key and the checkout credential read it under prefill. The buyer can edit it, and it never changes the customer record. Payment-link resolve keeps its email-only prefill.

  • Breaking change
  • API
  • Checkout
  • Promotions
  • Gift-cards

Checkout offers gift card and promotion code entry only when there is something to redeem#

Order.gift_card_tender_enabled now requires the merchant to have at least one gift card that is not closed in the order's environment. USD, order mutability, and subscription restrictions still apply. A spent but open card counts because a refund can restore its value.

The new required CheckoutSession.can_apply_promotion_code boolean says whether to offer code entry. When code entry is unset on the session, payment link, and checkout.promotion_codes_enabled, it is offered only while an active code promotion's schedule includes now in that environment. Explicit on and off overrides keep their behavior, and merchant promotions.codes_enabled: false still wins. Ended sessions and sessions in recovery report false.

Both hints are recomputed on reads. A newly issued card or activated promotion appears on the next read of an existing checkout. promotion_config.codes_enabled keeps its stored true, false, or null value. With null, a valid code still applies even if the hint last reported false. Gift card application is unchanged.

Headless checkouts can use these booleans to show entry fields. The promotion hint is included in session lists and webhook snapshots and ships in the next regular SDK release. See checkout sessions and gift cards.

  • API
  • Customers

Save addresses when creating a customer#

POST /v1/customers now accepts an optional addresses array. Each entry uses the same shape and validation as the saved address create request, including recipient_name, address, optional phone and label, and the billing and shipping default flags.

Flint saves the customer and addresses together. A validation or storage failure saves neither. At most one entry may be each default. Defaults appear as billing_address and shipping_address in the create response. Omit addresses or send [] to create without saved addresses.

An invalid US or Canadian subdivision returns 400 INVALID_REQUEST with param such as addresses[0].address.state. This uses the subdivision validation shipped for saved addresses. Existing saved addresses remain readable, and updates that omit address do not revalidate their subdivision.

With on_email_conflict: return_existing, an existing customer and its saved addresses stay unchanged. Submitted addresses are still validated.

  • Breaking change
  • API
  • Customers
  • Subscriptions
  • Payment-methods

Clear subscriptions and saved cards when approving customer deletion#

Approve a customer deletion with cancel_subscriptions: true, remove_payment_methods: true, or both in the same decision: "approve" body. Flint cancels subscriptions immediately through the usual cancellation path, then detaches and archives saved cards before erasing personal data.

Both options default to false. Only send them when approving; they are refused with decision: "reject", even when set to false. Existing requests that omit both options keep their behavior.

Read canceled_subscription_ids and removed_payment_method_ids on the deletion request to follow completed work. Progress survives failures. If the request becomes failed, approve again with the original options or omit them to resume. The options cannot change after the first approval.

See Clear subscriptions and saved cards.

  • Breaking change
  • API
  • Customers

Staff can request a customer email correction#

Staff and integrations can start, list, retrieve, and cancel email changes under /v1/customers/{customer_id}/email-change-requests. The new inbox confirms through a link valid for seven days. The change affects only this store's customer, revokes its sessions and emailed links, and never moves cards saved with Flint. The old inbox receives a notice with the store's contact details.

Two breaking changes apply to EmailChangeRequest, including the buyer's /v1/me responses:

  • Replace the removed confirmed boolean with status === "confirmed". status can also be pending, canceled, or expired.
  • Handle new_email: null after confirmation, cancellation, or expiry. Flint erases the address at that point.

The resource also returns requested_by, confirmed_at, and canceled_at. Merchant responses include supported_actions; buyer responses omit it. These changes apply to both supported API versions during the breaking-change window. See Customer email changes.

  • Breaking change
  • API
  • Errors
  • Delivery-methods

Delivery input errors identify the field to correct#

Invalid delivery configuration and preview inputs that previously returned 500 INTERNAL_ERROR now return 400 INVALID_REQUEST. This includes invalid external_reference_id values and status changes, invalid origin types or location collections, and missing preview currency or line items. Invalid history filters, revision-list page sizes, and revocation targets also identify the input to correct.

Each refusal includes param and a detail with REQUIRED, INVALID_VALUE, UNKNOWN_FIELD, or NOT_ALLOWED. When two inputs conflict, the detail includes the other input in conflicting_fields. Correct the named inputs before retrying with a new Idempotency-Key.

A delivery method PATCH reports an invalid origin as caller input only when the request supplies that origin. If a pricing-only or other unrelated PATCH encounters a corrupt stored origin, it returns 500 INTERNAL_ERROR without param, instead of blaming an omitted input.

Failures in stored delivery revisions, captured renewal destinations, or server-generated delivery commands remain 500 INTERNAL_ERROR without param. Recorded errors retain their original bytes when replayed.

  • Breaking change
  • API
  • Delivery
  • Inventory
  • Subscriptions

Delivery reservation summaries use the inventory owner vocabulary#

Breaking: delivery response schemas now match the values Flint returns.

  • DeliveryInventoryReservationSummary.owner_type is order, matching InventoryReservation.owner.type for stock held by a delivery selection. The response previously sent fulfillment_selection, while the schema listed delivery_selection, payment_attempt, and order_balance_hold. Update comparisons to order.
  • DeliveryInventoryReservationSummary.required_next_action has been removed. Flint never returned this field or any of its advertised values: none, retry_payment, replace_selection, or contact_merchant. Remove references to the field from generated client types.
  • SubscriptionDeliveryOption.unavailable_reason no longer lists pickup_unavailable. Subscription delivery previews evaluate shipment and local delivery methods. Checkout delivery quotes still support pickup_unavailable.

Regenerate clients from the updated OpenAPI schema. Reservation summary statuses remain active and closed.

  • API
  • Delivery
  • Checkout

Delivery quotes report a waiting method's price when it is already known#

Delivery quote candidates of type input_required can now include expected_amount_money. The session's derived delivery reports the same field. It is the charge a fixed-price method will quote once its missing input arrives, in the order's currency.

Shipment and local delivery candidates report their own fixed price. Waiting pickup candidates report it only when every pickup method that could serve their choice group has fixed pricing with the same amount. Different prices, a non-fixed method, or an unknown fixed amount make all waiting pickup candidates in the group omit the field. Unavailable methods are excluded from the comparison.

Free pickup at every store reports {"amount": 0, "currency": "USD"} while the buyer chooses a store. An omitted field means the price is not known yet, never zero. Available, unavailable, and cannot-calculate outcomes omit it. Pickup-location previews do not carry the field.

An expected amount never enters the order's amounts. To show a total before a complete address, quote from the country shown in the address form and select an offered option. The order includes that real selection's delivery charge while missing address members still block payment.

See Delivery quotes and Show a total before the address.

  • API
  • Webhooks
  • Partners

Environment grants send updated events#

The new environment_grant.updated webhook event reports changes to a grant's permissions, approved platform_fee_cap, and split approval. It is available for every supported API version through your app's partner_app event subscriptions.

When a merchant authorizes different permissions or a higher fee cap, or you narrow your app's permission manifest or lower its fee cap, each changed grant sends this event. Pending grants send it when their requested permissions or cap change. Revoked grants send it when their stored cap is lowered or removed.

The event carries the current grant in data.object and includes data.previous_attributes with the changed fields as they were. A change that also updates the install's permissions still sends partner_app_install.permissions_updated. A request that changes nothing sends no event.

See partner app events in the webhook events catalog.

  • Breaking change
  • API
  • Errors

Failed requests free their idempotency key#

A new keyed request that fails before changing anything now releases its Idempotency-Key, including validation, state, readiness, and database failures. Correct the request and reuse its key. Previously, a 4xx could be recorded and replayed for that key.

Error next_steps now describe the key's disposition. Recorded results still replay. After effects begin, uncertain outcomes keep their key reserved; read the outcome before sending anything new.

Previously recorded errors still replay. Older reservations that cannot prove no work started stay reserved and may require recovery. IDEMPOTENCY_KEY_IN_PROGRESS carries Retry-After: 1 or 2.

See Idempotency for retry and recovery instructions.

  • Breaking change
  • API
  • Fulfillments

Fulfillment updates no longer accept expand#

Breaking: PATCH /v1/fulfillments/{fulfillment_id} no longer accepts the expand query parameter. The response returns an unexpanded fulfillment, consistent with other write operations.

Remove expand from fulfillment update requests. Requests that still send it return 400 INVALID_REQUEST with an UNKNOWN_FIELD detail naming expand, as other write operations do for unknown query parameters.

To read related resources after an update, call GET /v1/fulfillments/{fulfillment_id} with expand=order, expand=shipments, or expand=packages. Repeat expand to request more than one relationship. Expansion requires commerce.orders.read.

  • Breaking change
  • API
  • Orders
  • Delivery
  • Inventory

Set delivery while creating or updating an order#

Send delivery on POST /v1/orders to select shipment or local delivery while creating the order. Flint quotes the exact delivery_method_id and saves the selection, delivery charge and inventory hold together. You can then pay the order in a second call. Merchant keys and partner tokens need orders write and delivery write access.

On PATCH /v1/orders/{order_id}, sending delivery requires expected_version. The preference fully replaces the previous one. Send delivery: null to clear a provisional direct-order selection, its charge and its hold. Requests that omit delivery keep their existing version requirements. The OpenAPI schema now publishes this conditional requirement.

Use expected_amount_money to refuse a changed delivery amount before changing the order or its holds. Cart inventory_reservation_ids can supply matching held stock; unused units remain in the cart. Draft Quick Pay invoice orders accept delivery until the invoice is issued.

Read the selection ID from governing_delivery_selection_id and its address from delivery_destination. The delivery summary adds only the selected method, type and recipient. See Orders.

  • Breaking change
  • API
  • Errors
  • Inventory
  • Returns

Inventory and return errors distinguish request inputs from stored state#

Invalid internal inventory reservation and reallocation commands, inconsistent routing evidence, and incomplete return lifecycle inputs now return 500 INTERNAL_ERROR without param. These failures previously surfaced as request validation errors. Stored receiving locations missing their required postal address also return 500 without naming a request input. Flint must investigate these failures; changing an unrelated request field does not resolve them.

Delivery evaluation resolves combined origin collections in batches. Multiple valid pickup methods can together contain more than 1,000 distinct locations without a size refusal. This also applies when inventory is tracked. The published per-method limit and pickup result limit are unchanged.

If a return decision inherits a receiving location from a saved policy and that location is missing or inactive, the operation now returns 409 ACTION_NOT_ALLOWED with reason configuration_required, no param, and retry none. Update the return policy's receiving location, or supply an active receiving_location_id with a postal address in the decision.

When the decision explicitly supplies the unavailable location, the response remains 400 INVALID_REQUEST with detail INVALID_VALUE at that decision's receiving_location_id path. Creating a policy or publishing a revision with an unavailable receiving location also returns 400 at revision.receiving_location_id rather than a state-conflict error. Activating a saved revision uses the stored-state classification.

Recorded errors retain their original bytes when replayed.

  • Breaking change
  • API
  • Invoices
  • Checkout
  • Orders

Invoice delivery and address are fixed at issue#

Issuing an invoice fixes its order's delivery and address. POST /v1/delivery-quotes, POST /v1/delivery-selections, selection release, and direct destination changes for an issued invoice return 409 ACTION_NOT_ALLOWED with reason configuration_required. The error identifies the invoice in details[0]. This applies to checkout and merchant credentials. Reading delivery stays available.

Breaking: invoice buyers could previously change delivery after issue, leaving the invoice's frozen total out of step with its order. Invoice checkouts now collect the fixed balance without offering delivery choices. To change delivery or the address, the merchant voids the invoice and issues a new one.

Set delivery through the delivery field on PATCH /v1/orders/{order_id} before issuing, or on POST /v1/orders. Issue returns 409 ACTION_NOT_ALLOWED with reason configuration_required if a shippable order lacks a delivery selection or charge, or if automatic or external tax needs a delivery address that isn't set. The error identifies the order and the missing setup.

Use ordinary checkout sessions or payment links for buyer-chosen shipping. See Invoicing for invoice collection.

  • Breaking change
  • API
  • Developers

OpenAPI schemas support Python and Go client generation#

The OpenAPI document now uses named union references and equivalent forms for null-only values, conditional constraints, and reference overlays. You can generate Python clients with OpenAPI Generator and Go clients with oapi-codegen. Request and response validation remains the same.

Regenerate your client from the updated document. Generated Go type names may change where component names previously conflicted with client response wrappers or enum names.

For oapi-codegen, include skip-prune with types,client so components referenced only by webhooks are included. Generation is verified with OpenAPI Generator 7.27.0 for Python and oapi-codegen v2.8.1 for Go.

  • Breaking change
  • API
  • Orders
  • Inventory

Order child references include their order#

POST /v1/orders/{order_id}/line-items and POST /v1/orders/{order_id}/charges now accept expected_order_version instead of expected_version. Send the order's version from your last read to reject a create based on an outdated order. The old field is rejected.

Both paths also support GET, with page_size and page_token. Results are sorted by child ID in ascending order. Each result includes order_id.

Order line items, charges, activity rows, fulfillment line item and charge references, and inventory reservation lines now include the referenced order's order_id. Buyer order and fulfillment projections include it too. Inventory reservation lines omit it when they have no order parent.

  • API
  • Orders
  • Customer-account

Order lists include active payment attempts#

Superseded by Payment attempts use processing while Flint resolves the outcome.

GET /v1/orders and GET /v1/me/orders now include active_payment_attempt on each order with an active attempt. Use its status to show a payment that is processing, finalizing, or waiting for capture, even while payment_status is still unpaid or partially_paid. Bank debits that remain in progress after their collection window ends are included.

Buyer list rows use the same field visibility as buyer single-order reads. List rows do not carry pending client actions or payment collection guidance. Read the individual order before offering payment actions.

  • API
  • Orders
  • Invoices
  • Gift-cards

Order tax and gift card restoration references include their order#

Tax breakdowns now include required order_id beside their line item or charge reference. Order and invoice responses, buyer projections, previews, and webhook snapshots carry the same parent ID. Flat order tax rows name the order too.

Gift card loads include the original purchase's order_id in purchase_restoration, beside order_line_item_id, including serialized load snapshots.

Variant line responses require product_id whenever variant_id is present. Bundle lines have no single parent product; each component names its own product. Create inputs continue to accept variant_id alone, because it determines the product.

Delivery quote line items, pickup availability quantities, and selection choices also include required order_id. Merchant and checkout projections carry the parent ID; checkout credentials can read only their own session's order.

  • Breaking change
  • API
  • Orders
  • Fulfillment

Pack bundle components separately#

Package items now include required, nullable bundle_component_id. For bundle rows, quantity counts component units. For a non-bundle line, the field is null.

Send the component ID when creating or updating package items, including items in packages created with a fulfillment or shipment. Every bundle-line create and PATCH requires an explicit ID, even when the fulfillment has only one component for that line. A missing ID returns 400 INVALID_REQUEST with detail REQUIRED; a component outside that line returns detail INVALID_VALUE. Both name the item's bundle_component_id in param. Stored legacy allocations without a recorded component still read as null and count against their sole component when checking capacity and shipping progress.

Capacity is now separate for each order line and bundle component. An allocation above one component's fulfillment quantity returns 409 LIMIT_EXCEEDED, even when another component has capacity. Update integrations that previously sent one combined quantity for a bundle line to send separate component rows. A package can contain both rows. With single_package fulfillment creation, Flint allocates all requested components automatically.

The existing package.updated event continues to signal contents changes. List the package's items to read their component IDs. No new event is added. See fulfillment and shipping.

  • Breaking change
  • API
  • Payment_intents
  • Orders

Payment authentication uses a Flint URL by default#

New confirmations now default to client_action_type: "url" instead of "stripe". This applies to standalone confirm, every order pay action, setup, and payments Flint starts for renewals and automatic invoice collection. Open the returned client_action.url as a redirect, popup, or iframe, then read or continue the payment to learn its outcome.

Integrations using Stripe.js must send client_action_type: "stripe" explicitly when starting the confirmation. Use the returned client secret only with handleNextAction: it can also confirm the underlying payment with another card.

Omitting the field on a continuation preserves the existing action type, including in-flight Stripe actions. Reader payments still work when the field is omitted; explicitly requesting url for a reader remains invalid. For a provider step that cannot open as a URL, continue with client_action_type: "stripe" after the provider_action_unsupported refusal.

Flint's API returns no Stripe client secret for URL actions. Stripe's hosted authentication page receives the secret to run the challenge, so the browser holds it during hosted 3DS2. If a payment is confirmed with a payment method Flint didn't approve, Flint doesn't count the charge and returns it to the buyer. The payment intent ends canceled with cancellation_reason: payment_returned.

See Server-confirmed payments and Embedded payments for return destinations, completion messages, and the explicit Stripe.js path.

  • Breaking change
  • API
  • Payments

Seller splits on payments#

Merchant payment intent responses now include splits, an array of the current PaymentSplit children. Payments without splits return []. Buyer and checkout bearer responses omit the field. These are the same objects the split GET routes return; changing a child does not advance the payment intent's version or send payment_intent.updated.

merchant_net_money subtracts each split's committed amount alongside processing, add-on, and platform fees. Splits canceled before collection or because seller approval ended commit nothing. A failed split commits only what was taken back before it failed, because the remainder returns to the collecting merchant. Refunds do not reduce the commitment.

Standalone payment creation now accepts 1 to 25 seller splits. Capture accepts final amounts for every uncanceled split, including on order-owned payments. Splits participate in idempotency and cannot be replaced through PATCH. Amount changes that leave too little for stored splits return LIMIT_EXCEEDED with minimum_money. See seller splits and partial capture.

Requests with splits cannot include platform_fee. The request schema checks this exclusion before looking up resources.

Order payment creation and order pay with action: "pay" also accept seller splits. On pay, their total must fit the processor payment after gift cards; splits aren't accepted when gift cards cover the whole order or its balance is zero. See seller splits on orders.

  • API
  • Payments
  • Webhooks

Payment split events#

Collecting merchants can subscribe to payment_split.created, payment_split.updated, payment_split.succeeded, payment_split.failed, and payment_split.canceled. Each snapshot matches the split's GET response and includes its reversals. Sellers receive balance_transaction.created when money reaches or leaves their balance.

A split's public version advances once per committed change. Retries that change no public fields send no event. Split changes do not advance the parent payment intent's version or send payment_intent.updated.

  • Breaking change
  • API
  • Partners

The Flint Platform Agreement is published#

The platform terms a partner app accepts before Flint reviews it as a platform now have a text: the Flint Platform Agreement. It covers the share of each platform fee Flint withholds and when Flint releases it, how withheld fees cover your merchants' unrecovered losses first, your starting limits, pauses, merchants you create, and disconnects.

  • PartnerApp.platform.current_terms. platform_terms_version is 2026-11-12, and url is https://withflintpay.com/legal/platform-terms. It was 2026-11-01 with url null.
  • The placeholder no longer counts. Version 2026-11-01 had no text. An app that accepted only it has platform_terms in platform.requirements again, its platform capabilities are inactive with inactive_reason requirements_due, and supported_actions lists accept_platform_terms. Accept 2026-11-12 with POST /v1/partner-apps/{partner_app_id}/accept-platform-terms to restore them.
  • Later versions. Flint announces a new version at least 30 days before it is required. current_terms then shows acceptance_due_at, and your earlier acceptance keeps platform_terms met until that date.

Read the version from current_terms rather than hard-coding it. See Accept the platform terms.

  • API
  • Payments
  • Readers

Stripe Reader S710 support#

A smart_reader can now be a Stripe Reader S710 as well as an S700. The S710 is the S700 with optional 4G/LTE cellular, at the same price, and Flint recommends it. Register either reader with the pairing code it shows. Both work the same way through Flint.

A registered S710 returns model: stripe_reader_s710, a new value of the extensible reader_model enum. Treat values your code doesn't recognize as other. In a sandbox, registration_code: simulated-s700 still registers the simulated reader. A reader of any other model is unregistered and returns 400 INVALID_REQUEST with param: "registration_code", as before.

  • API
  • Checkout

Remember returning buyers in checkout#

Checkout code confirmations accept remember_buyer and an optional remembered_buyer_token. When remembering is available, a right code returns a one-time identity token. Keep it on your backend or in an HttpOnly cookie.

Use POST /v1/remembered-buyers/lookup to read a masked email and the channel for a new code. After the buyer presses a button, send the token instead of email on a use_saved_payment_methods code request. The request uses recognition's existing caps. A remembered identity never opens saved cards; the buyer must still confirm a code.

POST /v1/remembered-buyers/revoke forgets the identity, including from a paid receipt. Tokens expire 90 days after the last confirmed code and are replaced when another confirmation remembers the buyer. Remembering issues no token while the required notice email is unavailable.

Read Remember a returning buyer for the complete flow.

  • API
  • Developers
  • Customers

Filter request logs by customer#

Customer session requests now carry customer_id on their request log summaries and details. The caller still identifies the session. Invoice access, checkout session, and API key requests omit customer_id.

Use GET /v1/api-request-logs?customer_id=cus_... to review requests across a customer's sessions, such as after a session leaks. The filter requires developer.request_logs.read; a key with only developer.request_logs.self.read gets 403 INSUFFICIENT_SCOPE at customer_id.

Request log reproductions now use a bearer placeholder matching the buyer caller: <CUSTOMER_SESSION_SECRET>, <INVOICE_ACCESS_TOKEN>, or <CHECKOUT_CREDENTIAL>. Every other caller keeps <API_KEY>. Replace the placeholder with the matching credential before sending the request. Customer session refresh requests use no Authorization header and a JSON body with refresh_token: "<CUSTOMER_SESSION_REFRESH_TOKEN>"; substitute the session's refresh token.

See API request logs and Customer sessions.

  • API
  • Developers
  • Customers

Request logs include customer session refreshes#

POST /v1/customer-sessions/refresh now appears in request logs with a customer_session caller. Successful rotation keeps the same session ID. Reusing a rotated refresh token revokes that session and records the failed request with the affected session as its caller. Later attempts with a rotated refresh token are logged too.

Unknown, malformed, or expired refresh tokens and rate-limited requests (429) leave no log. Refresh requests never store request or response bodies. Buyer-side header rules, 30-day client-detail retention, and customer deletion erasure apply to these rows too.

Use GET /v1/api-request-logs?caller_type=customer_session with developer.request_logs.read to review refreshes alongside buyer account requests. See Debug API requests.

  • API
  • Returns

Buyer return errors identify unavailable reasons#

When a buyer submits an inactive or archived return reason to POST /v1/me/returns, the 404 RESOURCE_NOT_FOUND error now includes details[0].resource_type: return_reason. Both param and details[0].param name the line's return_reason_id, for example line_items[0].return_reason_id. Refresh the offered reasons before submitting again.

Orders the buyer does not own still return a not-found error without return-reason details. Merchant requests retain 409 ACTION_NOT_ALLOWED with the reason's status.

  • Breaking change
  • API
  • Payments
  • Disputes

Split payment client setup and balance transactions#

Breaking: payment client account_id is required and nullable. This applies to client_confirmation.stripe, payment_collection.stripe, and payment client actions' .stripe object. A string means initialize Stripe.js with that connected account as stripeAccount. On a payment with splits, the value is null: initialize Stripe.js with publishable_key alone and omit stripeAccount before creating its confirmation token or completing an authentication action. Setup authority keeps its connected account ID.

Breaking: dispute response sessions use stripe_payment_id. In POST /v1/disputes/{dispute_id}/response-sessions, replace client_session.stripe.components[].stripe_payment_intent_id with stripe_payment_id. Pass the value unchanged to Connect.js setPayment or the React payment prop. Ordinary payments use a Stripe PaymentIntent ID; split payments use the collecting merchant's destination payment ID, beginning py_. The dispute's Flint payment_intent_id keeps its meaning.

Both changes apply to API versions 2026-02-01 and 2026-09-07 during the breaking-change window.

Balance transactions now expose six marketplace movement types: payment_split, payment_split_reversal, payment_split_reinstatement, payment_split_failure, seller_shortfall_coverage, and seller_shortfall_coverage_reversal. Their related_resource can name a payment_split; use the same value in the related_resource_type filter. See Balance transaction types.

  • API
  • Payments

Choose seller shares on refunds#

Refund creates accept split_reversals to choose exactly how much each seller gives back. Omit it for cumulative allocation, or send [] to fund the whole refund as the collecting merchant.

PaymentRefund.split_reversals and Dispute.split_reversals report each fixed seller allocation, including its split and reversal IDs. Read PaymentSplit.reversals to track recovery and reinstatement. See Refund a split payment.

  • API
  • Checkout
  • Subscriptions

Subscription checkouts can ask for the email code before payment#

POST /v1/checkout-sessions/{checkout_session_id}/customer-verifications now accepts purpose: "save_payment_method" with channel: "auto" when the checkout's order starts a subscription. Make the request as the buyer leaves the email field.

When the email needs proof before saving the renewal card, Flint emails a code and returns 200 with channel: "email". When no code is needed, a limit was reached, or no code can be sent, it returns 409 ACTION_NOT_ALLOWED with reason not_offered. A repeat request returns the same live verification without sending another email.

The request uses saved-details recognition's limits and reveals the same existing-customer match as the refusal at payment. Keep handling verification_required at payment for buyers who skip the step or reach a limit. Explicit email requests keep their existing limits and behavior. See Headless subscription signup.

  • Breaking change
  • API
  • Merchants

A support email is required before initial live payments#

Before initial live activation, explicitly submit profile.support_email when advancing onboarding. Buyers see this address on receipts and in their account. Flint does not silently use the business email.

The onboarding action advance_onboarding includes profile.support_email in required_fields while the address is missing. Advancing live onboarding without it returns 409 MERCHANT_NOT_READY, with reason onboarding_required and param: profile.support_email.

New payment requests missing the required support email return the same error. Merchant readiness directs callers to advance_onboarding, with profile.support_email in required_fields.

Existing live merchants keep taking payments when the address is missing. Their onboarding profile still lists the outstanding field so they can add it. New charges require the address before initial activation; existing payment recovery, refunds, and payouts keep their current rules.

See Merchant onboarding for the request fields and readiness responses.

  • Breaking change
  • API
  • Fulfillments

Fulfillment creates use top-level collections#

Breaking: four create routes have moved. The old routes are removed. Send the parent ID in the JSON body at the new route:

Old routeNew routeBody parent
POST /v1/orders/{order_id}/fulfillmentsPOST /v1/fulfillmentsorder_id
POST /v1/fulfillments/{fulfillment_id}/shipmentsPOST /v1/shipmentsfulfillment_id when direction is outbound; return_id when it is return
POST /v1/shipments/{shipment_id}/packagesPOST /v1/packagesshipment_id
POST /v1/fulfillments/{fulfillment_id}/eventsPOST /v1/fulfillment-eventsfulfillment_id

Return shipments still require return_line_items. Flint resolves their original fulfillment from those lines. Each direction rejects the other parent ID. Inline packages, inventory consumption, permissions, and fulfillment event deduplication keep the same behavior.

Fulfillment creation still requires Idempotency-Key. The other three creates accept an optional key. Save a separate key for each create: reusing one key at the same route with a different parent returns 409 IDEMPOTENCY_KEY_REUSED. Retry a lost response with the same key and body.

See the fulfillment guide for updated examples.

  • Breaking change
  • API
  • Errors

Update schemas declare when an empty body is invalid#

Update request schemas now declare minProperties: 1 wherever the API already rejects an empty JSON object ({}). Generated clients and schema validators can identify that these updates need at least one field.

Runtime validation is unchanged. Update requests that already accept {} continue to accept it.

  • Breaking change
  • API
  • Errors
  • Webhooks

Webhook errors preserve validation inputs#

Merchant and partner-source webhook endpoints use the same URL validation contract: 400 INVALID_REQUEST, detail INVALID_VALUE, and param: url. Validation errors keep the field supplied by the validator. Unsupported api_version values identify api_version.

Unexpected internal failures while processing webhook endpoints now return 500 INTERNAL_ERROR without param. They previously could return 400 INVALID_REQUEST and blame a webhook_endpoint input that the request does not accept. The response no longer exposes the underlying internal error message. Follow the response's retry guidance.

Recorded errors retain their original bytes when replayed.

  • API
  • Subscriptions

Order now availability accounts for delivery holds#

A subscription's renew buyer action now reports is_available: false with unavailable_reason: delivery_hold while an active or upcoming delivery hold exists. Read delivery_hold or upcoming_delivery_hold for the cause and who can fix it. Reload the subscription after resolving the delivery problem before offering order now.

unavailable_reason can gain values. Show a general message for a reason you do not recognize.

  • Breaking change
  • API
  • Subscriptions
  • Customer-accounts

Read buyer subscription retry and stock-wait state#

The retry_payment buyer action now reports unavailable_reason: "in_progress" while a retry is pending or processing, and limit_reached when the buyer has no retries left. Both conditions previously reported not_in_state. Update clients that switch on these reasons. Cancellation, delivery holds, and inventory waits still take precedence with not_in_state.

While a subscription is past_due, the action carries retry_payment.remaining_retries, max_retries (currently 3), and active_subscription_payment_retry_id when a retry is running. Retries the store starts count too. The options remain present when the action is unavailable, including sign_in_required. Read a running retry with GET /v1/me/subscriptions/{subscription_id}/payment-retries/{subscription_payment_retry_id} until it succeeds or fails, and keep showing processing after a reload.

Buyer subscriptions now include inventory_wait with started_at only. Merchant references stay private. The subscription's status is unchanged; the renewal waits for stock without charging until it ships. A stock wait no longer makes update_payment_method required or sets its deadline, unless the existing cardless or expiry rules need a new card.

The retry routes, errors, idempotency, and merchant webhook payloads are unchanged. See buyer action options and payment recovery.

  • Breaking change
  • API
  • Delivery
  • Checkout

Delivery schemas require selectable option IDs and publish pricing limits#

Delivery schemas now describe the fields and limits Flint already enforces:

  • Every option in a quote choice group's options requires delivery_option_id. Use it when creating a selection. Preview options still omit it.
  • An available caller-supplied outcome requires both window_start_at and window_end_at, or a nonempty offered_windows list. When either timestamp is supplied, both are required, including when offered_windows is also supplied. Its expires_at must be strictly later than evaluation time plus minimum_option_lifetime_seconds, no later than the quote expiry, and no later than selection_guarantee_expires_at.
  • Tiered pricing has 1 to 25 bands, and a rate table has 1 to 100 rates, in request and response schemas. The existing runtime limits are unchanged.
  • The caller.tier_key tiered pricing basis now has a valid discriminator mapping in both request and response schemas. It uses the same numeric bands as quantity and money bases and forbids unit.

Regenerate clients and schema validators to pick up these required fields, alternatives, and collection bounds. Delivery configuration describes the pricing inputs, and delivery quotes explains which options can be selected.

  • Breaking change
  • API
  • Customers

Buyer email changes keep Flint cards at the previous address by default#

Confirming a buyer email change no longer moves cards saved with Flint by default. POST /v1/me/email-change-requests/{email_change_request_id}/confirm accepts optional move_flint_wallet, which defaults to false.

Only customer sessions that can access GET /v1/me/flint-wallet/cards may send the field: a live email-code sign-in at a Flint-hosted account. Other sessions, including sessions your server creates, receive 400 INVALID_REQUEST with a NOT_ALLOWED detail at move_flint_wallet if they send either value.

For eligible sessions, confirm returns flint_wallet_outcome when the previous email had saved cards: moved, kept, or new_email_has_wallet. The last outcome means the new email already has a Flint wallet, so the cards stayed at the previous email. Merchant credentials never receive this field. Creating the email-change request is unchanged.

See Customer accounts for the confirmation flow.

  • Breaking change
  • API
  • Invoices
  • Disputes

Lost disputes no longer reopen invoice balances#

A lost dispute previously reduced an invoice's paid_money and reopened its outstanding_money. Now paid_money stays gross of disputes. A loss does not change outstanding_money, currently_due_money, or status: a paid invoice stays paid, and a partially paid invoice keeps the same remaining balance.

Reminders, late fees, and automatic collection do not restart because of a dispute loss. Collecting the lost amount again requires a new invoice. A later win restores no invoice balance because the loss did not remove any payment. Refund behavior and refund capacity are unchanged: a lost dispute still consumes refund capacity. Inquiries and disputes on payment_returned payments add no invoice balance.

Invoice reads and webhook snapshots use this rule, including payment schedules and late fees. A dispute that changes no invoice field advances no invoice version and sends no invoice event. Follow the dispute resource and its events for the outcome.

  • Breaking change
  • API
  • Payments
  • Refunds

Affirm refund windows use the stored capture time#

Affirm's 120-day refund window now starts at the payment's stored capture time. Previously, Flint used the latest payment attempt's update time, falling back to the payment's creation time. Later attempt updates could extend the deadline.

PaymentIntent.refund_expires_at and the refund_window_expired refusal on POST /v1/refunds now use the same stored capture time for direct and order refunds. A refund at exactly the published deadline is still accepted; one second later it is refused.

When the capture time is missing, refund_expires_at is null. Flint no longer refuses submission with reconciliation_required for missing settlement evidence; the provider decides whether the refund is still allowed. Canceled payments, including payments whose captured money Flint returns, have refund_expires_at: null and remain ineligible for merchant refunds.

Refetch the PaymentIntent before scheduling an Affirm refund instead of relying on a deadline cached before this change. An expired window can require reimbursing the buyer outside Flint. An earlier failed Affirm refund still prevents another submission through Flint.

  • Breaking change
  • API
  • Payments

Card-present payments#

Payment intents now accept payment_options: ["card_present"]. Present a card on a smart reader through the existing order pay or standalone confirm route, using credential_type: "reader" and reader_id. Add tip: {"enabled": true} to show a smart reader's tip screen.

The OpenAPI request schemas enforce that card_present is the only payment option and has no payment_return_url. These constraints apply to the new option; existing online payment requests remain valid. Reader confirmations accept exactly one selection, and readers cannot be used for setup. Card-present intents return no payment_collection.

Payment intents and order payment attempt legs expose reader_id. Card summaries include the card-present read and verification details, and PIN declines have specific failure codes. See Card-present payments and Pay on a reader.

  • Breaking change
  • API
  • Errors
  • Delivery-methods

Delivery errors distinguish configuration inputs from internal failures#

Delivery method validation now identifies the invalid entry in configuration.quote_input_fields, or the invalid field or format in configuration.recipient_requirements. Duplicate entries identify the later value. These configuration refusals keep their existing status and detail code.

Inconsistent delivery authority, selection amounts, and server-generated commands are internal failures. They return 500 INTERNAL_ERROR without param. Subscription renewal no longer treats these internal command failures as a rate being unavailable. Report the request_id to Flint support so Flint can investigate.

Pre-write command refusals keep their existing idempotency handling. Recorded responses keep their original bytes when replayed.

  • Breaking change
  • API
  • Errors
  • Customers
  • Subscriptions
  • Payment-links

Error responses identify public inputs and invalid saved terms#

Sending customer_id on a /v1/me operation now returns 400 INVALID_REQUEST with detail code UNKNOWN_FIELD, replacing NOT_ALLOWED. Each detail names the submitted field or query parameter, including nested object fields and array indexes. The top-level param repeats details[0].param. Remove the unknown input before sending the request again.

Deleting a subscription line now returns 500 INTERNAL_ERROR, without param, if the remaining saved billing terms have an invalid quantity or an amount that cannot be computed. This replaces 400 INVALID_REQUEST with an INVALID_VALUE detail. The deletion makes no changes. Report the request_id to Flint support so Flint can investigate the invalid saved terms.

A deletion that leaves valid billing terms still succeeds, including a deletion that removes an invalid line.

Adding or swapping subscription merchandise that cannot use the subscription's delivery preference returns 400 INVALID_REQUEST with detail code NOT_ALLOWED at the submitted variant_id or bundle_id. This includes a physical item added to a subscription without a delivery preference. These errors no longer report REQUIRED at delivery, or NOT_ALLOWED at line_items, which subscription line operations cannot accept.

If a subscription line write finds invalid saved fulfillment terms, it returns 500 INTERNAL_ERROR without param, replacing a validation error at delivery or line_items. A saved physical line without a delivery preference, or a saved line whose frozen profile supports only pickup, requires Flint to investigate. The write makes no changes.

Resolving a subscription payment link whose saved plan exceeds the prepayment quantity limit now returns 409 ACTION_NOT_ALLOWED with reason configuration_required, without param, and with retry mode none. Reduce the plan's line or modifier quantity or change its billing or delivery cadence, then resolve the payment link again. For example, a physical line with quantity 1,000, annual billing, and monthly delivery exceeds the 9,999 limit when its prepayment line is computed.

Plan create and update now reject a physical line whose quantity multiplied by one fewer than the deliveries per billing period exceeds 9,999 for any offered billing cadence. This is the prepayment line for deliveries after the first. The response is 400 INVALID_REQUEST with detail code INVALID_VALUE at line_items[i].quantity. With 12 deliveries, quantity 909 is accepted (909 × 11 = 9,999) and 910 is rejected. Prepayment modifier quantity and amount scaling are also checked; an overflow names line_items[i].modifiers[j].quantity. Resolution returns the same configuration refusal for a saved plan with a modifier scaling overflow.

Resolving a subscription payment link whose saved plan has an amount that cannot be computed because its saved money is outside the accepted input limits returns 500 INTERNAL_ERROR without param, replacing 400 INVALID_REQUEST with an INVALID_VALUE detail. These saved terms cannot be created through plan writes. Report the request_id to Flint support. Both resolution failures create no checkout session or order, and resolution accepts no subscription quantity input.

Recorded error responses keep their existing details and input paths when replayed.

Fresh error paths use each operation's public inputs. References to saved configuration that the operation cannot change are omitted from non-validation errors. For example, a payment-intent capture error no longer names order_id, and a product create error names default_variant.delivery_profile_id instead of delivery_profile_id.

  • Breaking change
  • API
  • Orders
  • Fulfillment

Fulfillment components and due times#

Fulfillment line items, buyer fulfillment line items, and OrderLineItemFulfillmentQuantities now include required, nullable bundle_component_id. Fulfillment inputs require the same field: send a component ID from the order line's bundle_components, or null when the line isn't a bundle component. A bundle row's quantity counts component units. This lets you create a replacement fulfillment for bundle components a failed fulfillment released.

Missing bundle component IDs return 400 INVALID_REQUEST with detail REQUIRED; unknown components return detail INVALID_VALUE, both at line_items[i].bundle_component_id. Types a line cannot fulfill return detail NOT_ALLOWED at line_items[i].order_line_item_id. Fully assigned, fulfilled, canceled, or refunded lines return 409 ACTION_NOT_ALLOWED. Quantities above a positive remaining amount return 409 LIMIT_EXCEEDED with available_quantity. These refusals happen before any effects.

Pickup fulfillment details rename expires_at to pickup_due_at; local delivery details rename it to delivery_due_at. Update create and patch inputs and response readers to use the new names. These are times by which someone should act. Passing either time does not change status or send an event automatically.

See fulfillment for component identity, quantity limits, and overdue work.

  • Breaking change
  • API
  • Errors

Idempotency failures preserve committed outcomes#

A successful keyed mutation now returns its success response when Flint cannot store its replay result. Flint retries that write for up to 30 seconds before returning the success. A credential issued by the successful request stays active.

If you lose the response, keep the same Idempotency-Key. A retry replays a recorded result, reports that it is still in progress, or returns IDEMPOTENCY_RECOVERY_REQUIRED. Follow the route's recovery guidance before starting another operation.

Other idempotency storage failures now preserve what happened:

  • A failed claim returns 503 SERVICE_UNAVAILABLE, retry: same_request, and Retry-After: 2. The handler did not run, but the reservation may have been written. A lost acknowledgment can leave the key reserved without a created resource; a later retry can return IDEMPOTENCY_RECOVERY_REQUIRED. Contact support with the original key and request_id; do not rely on a retry to reclaim the key.
  • A failed reservation clear returns the original application error.
  • An uncertain database write returns 503 SERVICE_UNAVAILABLE with reason outcome_unknown, retry: none, and no Retry-After. Keep its key and read the outcome before sending another operation.

Breaking: these failures previously returned a generic 500, or a retryable 503 without an outcome reason. Successful mutations now retain their normal success response, and uncertain writes require reading the outcome before retrying.

  • API
  • Errors

Unused idempotency reservations recover after 30 seconds#

If Flint reserves an Idempotency-Key but never starts work, a retry with the same key can now continue after 30 seconds. The original request cannot perform effects or remove the retry's reservation after takeover.

Older reservations retain their recovery behavior. If a retry returns IDEMPOTENCY_RECOVERY_REQUIRED, follow the route's recovery guidance before starting another operation.

  • API
  • Payments
  • Readers
  • Docs

In-person payments with readers and Tap to Pay#

Flint now takes card payments in person, in the US and in USD, on two kinds of reader. A Stripe Reader S710 (or S700) is driven by your server through Flint, with no reader SDK. Tap to Pay on iPhone and Android runs in your app with the Stripe Terminal SDK. A counter sale is an ordinary Flint order, so tips, capture, refunds, receipts, and payouts work as they do online. There is no offline mode.

The new In-person payments guide walks through pairing a reader, a counter sale, Tap to Pay, tips, holds, refunds, failures, and testing.

  • Card-present payments. Pay an order with a reader payment source, or confirm a payment intent that offers card_present. See Pay on a reader and Card-present payments.
  • Tap to Pay. A payment on a Tap to Pay reader waits in requires_action with a card_presentment pending action. Your app collects the card with the Terminal SDK, and your server resumes the attempt. Tap to Pay lists the calls.
  • Tips on the reader. tip: {"enabled": true} shows a smart reader's tip screen. The tip is recorded in the payment's tip_money and joins the order's tip when the payment is captured. See Tips on the reader.
  • Final amount, tip, and overcapture. Capture takes final_amount_money and tip_money, and request_overcapture: true lets one capture collect above the hold where the card network allows it. Payment intents report overcapture and captured_tip_money. See Manual capture.
  • Carry-out. An order's handover replaces the delivery selection for goods the buyer leaves with, and creates and completes a handover fulfillment when the order is paid. See Sell for carry-out with a handover.
  • Platform fees. A partner app can set platform_fee when it captures a standalone payment, and a fee cap can include a fixed amount per payment. See Platform fees.
  • Test cards. A simulated reader, Stripe's physical test card amounts, and the Terminal SDK's simulator are in Testing and the test cards reference.

Receipt emails, receipt PDFs, and the hosted receipt show the entry method, card application, verification, and tip for card-present payments. Readers need the scopes payments.readers.read and payments.readers.write, which partner apps can request.

  • API
  • Invoices
  • Payments

Retry invoice checkout declines with a new card#

Superseded by Read and cancel invoice payments through payment intents.

When an invoice checkout payment fails, its invoice payment attempt now becomes failed with last_payment_error in the same transaction that finishes the order payment attempt. The existing invoice_payment_attempt.failed webhook reports the failure.

After a decline, send action: "pay" again with the same checkout session's credential, a new payment_source, and a new Idempotency-Key. Flint reuses the session's single unconfirmed payment intent when it covers the amount being collected. Previously, this request required you to select the declined leg explicitly with confirm_payment_intents.

Replaying either request's key returns that attempt's recorded result without another charge. Processing payments, including ACH debits, and authorized payments cannot be replaced. Multiple selectable legs still require explicit selection.

See Invoice checkout payments and Retry after a decline. These changes apply to all supported API versions.

  • Breaking change
  • API
  • Partners
  • Webhooks

Pending merchant action routing reports expires_at#

Breaking: PartnerApp.merchant_action_routing.until is renamed expires_at, with no alias. Partner app responses and partner_app.* webhook payloads use the new name.

The value is unchanged: an RFC 3339 timestamp for when routing switches from the previous destination in url to the current merchant_action_url. The object is still present only while a move to another registrable domain is pending, and is omitted once expires_at is reached. Flint's timestamp fields end in _at, and this one now follows that rule.

See Merchant action URL.

  • API
  • Partners
  • Payouts
  • Disputes
  • Webhooks

Run money and dispute operations through your install#

A platform can now show each merchant its money and handle its chargebacks with the partner app token, without asking the merchant for a separate API key. Build payments into your platform lists what an install can and can't do in one place, and the x-flint-partner-access value on each OpenAPI operation says whether it accepts a partner app token.

What an install can do, with the scope the merchant approved:

  • Read money. money_movement.balances.read, money_movement.balance_transactions.read, money_movement.payouts.read, and money_movement.payout_settings.read let the token read balances, balance transactions, payouts, payout settings, and payout destinations. A payout destination shows bank_name, country, and the masked last4.
  • Answer disputes. payments.disputes.read lists and reads disputes. payments.disputes.write accepts them, opens response sessions for Stripe's dispute component, and, in test mode, simulates outcomes. See Read money and answer disputes.
  • Brand checkout and set domains. settings.read and settings.write read and change branding, legal links, and checkout, customer account, and invoice presentation defaults, and manage custom domains. merchants.profile.write changes the business name, logo, and icon in live mode. See Brand checkout and set custom domains.
  • Receive the events. An endpoint with the installed_merchants source receives dispute.*, payout.*, payout_destination.*, payout_settings.updated, balance.updated, and balance_transaction.* while the grant holds the read scope of the event's resource. See Installed-merchant events.
  • See readiness and catch up. The app owner's install reads show each grant's merchant_readiness, and GET /v1/webhook-events/stream accepts a partner app token to recover missed events for one merchant.

What stays with the merchant's own credential:

  • Creating or canceling a payout, and changing payout settings, payout destinations, and default destinations. An app can't request money_movement.payouts.write or money_movement.payout_settings.write.
  • The balances, payouts, payments, tax_documents, and account_management components of merchant account sessions. An install token opens only account_onboarding and notification_banner.
  • Reports and their events, payment method domains, the tax connection, tax registrations, and tax calculation callbacks.
  • The settings and profile fields that change money, when buyers are charged, risk limits, tax, legal identity, verified business details, and the account email. Sending one returns 400 INVALID_REQUEST with a NOT_ALLOWED detail and saves nothing.

Each token acts only in its grant's merchant and environment. Revoking the install or the grant, or removing a permission, ends access on the next request.

The detailed notes for each change are in Partner app installs can read balances and payouts and answer disputes, Partner app installs can brand checkout and set custom domains, and Partner apps can receive dispute, payout, and balance events.

  • API
  • Orders
  • Invoices

Read an order's invoice and filter invoiced orders#

Orders now return nullable invoice_id, including rows on GET /v1/me/orders. Quick Pay invoice orders return the new origin: invoice value. has_invoice=true and has_invoice=false filter GET /v1/orders and GET /v1/me/orders by whether an invoice is linked, including voided invoices.

  • API
  • Orders
  • Refunds

Replace items on a paid order#

POST /v1/orders/{order_id}/edits now accepts add_line_items, in the same shape as the line item create route and order edit preview. Remove unshipped units and add their replacement in one edit. Removed value and released charges pay for added items first; the rest is refunded. Stock and tax commit with the edit.

The edit returns add_line_items, each with order_line_item_id, quantity, and total_money, plus added_total_money. Each added order line returns order_edit_id; other lines return null. Order and order-edit webhooks carry these fields too.

Only variant, bundle, and custom lines with a delivery requirement can be added. Added lines use normal pricing and tax without reapplying promotions, and do not join the existing delivery selection. Unsupported kinds return 400 INVALID_REQUEST with detail NOT_ALLOWED at add_line_items[i].

A preview can show a balance due. Committing one returns 409 LIMIT_EXCEEDED with reason order_edit_balance_due and maximum_money equal to the removed value plus released charges, without changing the order. Add items worth at most that amount, remove more, or sell the extra items on a new order.

See Edit a paid order for the request, response, and refund recovery.

  • Breaking change
  • API
  • Payment_intents
  • Orders

Open payment and setup authentication with a Flint URL#

Superseded by Payment authentication uses a Flint URL by default.

PendingPaymentAction.client_action is now a closed union selected by type: url or stripe. Previously every action carried client_action.stripe; check type before reading a branch. The Stripe branch retains its existing fields. Every pending action also includes expires_at.

For a standalone payment intent, send client_action_type: "url" to POST /v1/payment-intents/{payment_intent_id}/confirm. Open the returned Flint URL as a redirect, popup, or iframe. Flint's API returns a Stripe client secret only for client_action_type: "stripe". With url, Stripe's authentication page receives what it needs to run the challenge, including the client secret in its URL for hosted 3DS2. The browser holds that secret during the challenge. The URL expires 12 hours after the step was created.

If a payment is confirmed with a payment method Flint didn't approve, Flint doesn't count the charge and returns it to the buyer. The payment intent ends canceled with cancellation_reason: payment_returned.

New confirmations now default to url, as described in Payment authentication uses a Flint URL by default. Send client_action_type: "stripe" explicitly when using Stripe.js handleNextAction. That secret can also confirm the underlying payment with another card, so use it only with handleNextAction. A continuation retains its existing type; a different explicit type returns 409 ACTION_NOT_ALLOWED, reason field_locked, on client_action_type.

Confirm also accepts payment_return_url. Flint adds only payment_intent_id when returning the buyer there. Without it, a completion page posts flint.payment_action.completed to its parent and opener. Check the message's event.origin against the origin of the returned Flint action URL before trusting it. Read the payment intent to learn its outcome. Return destinations support HTTPS and native app schemes; test mode also accepts HTTP loopback destinations. Credentials, queries, fragments, and executable schemes are refused.

Every order pay action also accepts client_action_type and payment_return_url, including setup and resume. With a checkout credential, omit payment_return_url; checkout sessions use their own configured return URL. Order and setup URL actions appear in order_payment_attempt.pending_actions and permitted attempt reads. Each expires at the attempt's 30-minute cancel time. Setup returns use payment_method_id instead of payment_intent_id, including in the completion message, with exactly one subject key. Pay replays return no URL token or Stripe secret; read the attempt to recover its permitted current actions. See Server-confirmed payments.

A payment method whose next step cannot open as a URL returns 409 ACTION_NOT_ALLOWED, reason provider_action_unsupported. No URL action is published, and the type remains unlocked. Continue with client_action_type: "stripe". Idempotent confirm replays return current_payment_action: null; action authority is not retained in the replay record.

Reader credentials do not support URL actions. With credential_type: "reader", omit client_action_type or send "stripe". Sending "url" returns 400 INVALID_REQUEST, detail INVALID_VALUE, with param: client_action_type, before payment starts.

  • API
  • Fulfillment
  • Payments

Payment reviews hold fulfillment#

An open or resolving Flint payment review on an order payment now places a Flint-owned payment_review fulfillment hold. New fulfillments start on hold too, and forward actions are blocked while the payment hold is active.

Approving releases the payment hold and restores only the fulfillments it held, when no other payment hold covers the order. Your own holds stay in place. Expiry, refunds, disputes, and payment cancellation release the payment hold but leave fulfillment on_hold for you to reevaluate. Send release_hold explicitly before advancing this work. Declining keeps the payment hold active, including if a failed refund reopens the review.

Provider stops and review holds release independently. PaymentIntent.fulfillment_hold and payment_intent.fulfillment_hold_updated still describe provider stops only. Use the payment review events to follow review decisions.

  • Breaking change
  • API
  • Partners

Platform fee loss coverage transaction types#

PlatformFeeBalanceTransaction.type now publishes loss_coverage for fees applied to a merchant's unrecovered loss and loss_coverage_reversal for coverage returned after recovery. Both values are accepted by the type filter on GET /v1/platform-fee-balance-transactions.

A reserve-funded loss_coverage follows its reserve_release and links to it in related_balance_transaction_ids. Coverage from held available fees while the platform is paused has no reserve release. A loss_coverage_reversal links to the loss's coverage entries.

The OpenAPI schema for amount_money now uses SignedMoney, removing an incorrect nonnegative minimum. Amounts already returned by the API keep their values and JSON shape. Regenerate clients that validate these amounts against the previous schema so they accept negative debits.

See Platform fee balance transactions.

  • API
  • Partners
  • Payments
  • Docs

Platform fees, from the cap to the payout, in one walkthrough#

A partner app can charge a platform fee on the payments it creates for merchants that installed it, within the cap each merchant approved. This release collects the guides in one place.

  • Build payments into your platform. A new step follows Classboard and Tidewater Yoga: set platform_fee_cap, the studio approves it, platform_fee on a checkout session, a refund with refund_platform_fee, and the fee's balance and payouts. Paying out to the studio is now Step 7.
  • Partner app installs. A short example of the same flow, next to the cap.
  • Live fees. Live platform fees need Flint's approval of your app as a platform, which the guides describe in Become an approved platform. Test mode doesn't need it. Subscriptions, invoices, and payment links accept no fee, and Flint doesn't split one payment across sellers.
  • SKILL.md, llms.txt, and the Stripe migration table. SKILL.md names platform_fee and refund_platform_fee, llms.txt names platform_fee, and the migration table maps Stripe's application fees to platform fees.
  • API
  • Subscriptions
  • Checkout
  • Orders

Charge once for several subscription deliveries#

Physical plans accept delivery_interval and delivery_interval_count on create and PATCH. They must be set together, and every offered billing interval must cover 1 to 24 whole deliveries. Send both as null to return to one delivery per period.

  • Subscriptions expose the frozen cadence, deliveries_per_period, remaining_prepaid_deliveries, and next_delivery_at, including buyer reads and subscription webhook objects.
  • Checkout subscription terms and priced preview blocks expose the delivery cadence and deliveries per period.
  • Delivery orders expose prepayment_order_id and subscription_delivery_number, and use the prepaid_delivery discount source. No new charge is made for these orders.
  • Receipts distinguish the prepaid line with a label such as "Box, deliveries 2 to 6".

Holds, skips, and pauses move paid deliveries without consuming them. Period-end cancellation and end_after wait for the last paid delivery; immediate cancellation stops future deliveries and refunds remain manual. Changes that would affect deliveries already paid for return 409 ACTION_NOT_ALLOWED with reason prepaid_deliveries_remaining.

See Prepaid deliveries for setup, delivery counters, held deliveries, cancellation, and refunds.

  • API
  • Developers
  • Customers

Request logs include buyer account and invoice access requests#

Authenticated reads and writes under /v1/me now appear in request logs and resource timelines. A customer session records a customer_session caller; invoice access records an invoice caller. Unknown, expired, or revoked credentials and rate-limited buyer account and invoice access requests (429) leave no log.

The published sentence "buyer-side callers never expose them" is withdrawn. Request log details now show ip_address and user_agent for checkout sessions, customer sessions, and invoice access, whenever stored. When your server relays a buyer's request, the IP address is your server's address.

Requests under /v1/me never store request or response bodies. Buyer-side headers keep only content metadata, API version, idempotency, request ID, and trace headers. Other headers, including authorization and client forwarding headers, are omitted. Headers are kept for 14 days, buyer-side IP addresses and user agents for 30 days, and summaries and the rest of the detail for 90 days. Deleting a customer removes the client details, headers, bodies, and query parameters from their own buyer requests.

Use GET /v1/api-request-logs?caller_type=customer_session or caller_type=invoice with developer.request_logs.read. A key with only developer.request_logs.self.read continues to see only its own requests. See Debug API requests.

  • API
  • Sandboxes

Failed sandbox resets stop retrying#

Sandbox resets retry after 1, 2, 4, 8, 16, 32, and 60 minutes, then stop after at most eight attempts. Each attempt counts when it starts, including interrupted attempts. The new nullable Sandbox.reset_failed_at timestamp records when the reset stopped. A later successful reset clears it.

If deletion has not started, the sandbox keeps its previous data and accepts requests again. If deletion has started, requests return 409 ACTION_NOT_ALLOWED with reason sandbox_reset_failed, without Retry-After. Reset the sandbox again with a new idempotency key to resume, or archive it with a live credential if it is not the default sandbox. Archiving after a stopped reset deletes both sets of data in the background.

Requests during automatic retries still return 409 OPERATION_IN_PROGRESS with reason sandbox_resetting and Retry-After.

See Reset a sandbox.

  • Breaking change
  • API
  • Orders
  • Invoices
  • Webhooks

Voiding a Quick Pay invoice closes its unpaid order#

Voiding a Quick Pay invoice now also closes its order with closed_reason: invoice_voided when the order is open, has no collected payment, and has no fulfillment. Previously, the order stayed open. There is no option to keep an eligible order open.

The void sends invoice.voided and, when the order closes, order.closed, with no order.updated. The closure's previous_attributes includes status and closed_reason. An already closed or canceled order, an order with collected payment, or an order with a fulfillment stays unchanged. A retried void sends no order event and preserves the order's version.

  • Breaking change
  • API
  • Orders
  • Disputes

Orders expose disputes and exclude losses from net collected money#

Order settlement_amounts.net_collected_money previously meant paid_money - refunded_money. It now means paid_money - refunded_money - dispute_lost_money, never below zero. Update revenue calculations that assume the old formula. paid_money stays gross of disputes, and a lost dispute does not reopen outstanding_money or change payment_status.

Orders now return dispute_status, plus disputed_money and dispute_lost_money in settlement_amounts. A later win removes its principal from the lost amount. Partial disputes count only the disputed principal; inquiries and disputes on payment_returned payments contribute no money. Dispute fees stay outside order settlement amounts.

Order reads and order webhook snapshots use the corrected net collected amount. Expanded order summaries and buyer orders share the settlement money fields; buyer orders omit dispute_status. Expanded payment intent summaries now include their dispute_status for merchant reads. Merchant activity lists add dispute_opened and dispute_closed with dispute_id, outcome, principal, and a zero balance delta; buyer activity lists omit them.

A change to the order's dispute summary advances version and sends order.updated, unless the same commit sends a payment or refund status event instead. Dispute events can arrive before order.paid; check the paid snapshot's dispute_status before fulfilling. List individual cases with GET /v1/disputes?order_id=....

  • API
  • Orders
  • Risk

Orders identify active payment reviews#

Orders now include active_payment_review_id, the earliest open or resolving review on a counted payment. It is null when none remains. Buyer credentials omit the field.

Review pointer changes send order.updated. If the same transaction pays the order, order.paid carries the pointer instead. Check it before shipping from your own system.

Merchant order activity logs include payment_review_opened and payment_review_closed, with payment_review_id and a zero balance change. The close description names the outcome. Buyer activity lists omit these rows.

  • Api-keys
  • Webhooks

Monitor API key creation, changes, and revocation#

api_key.created, api_key.updated, and api_key.revoked report API key lifecycle changes. The events cover creation through the API and Dashboard, edits to name, access, scopes and expiry, explicit revocation, install-linked revocation, and sandbox archive. Each payload contains the API key's GET representation, including created_by, and never its secret.

Test-key events go to the key's sandbox endpoints; live-key events go to live endpoints. Partner apps cannot subscribe to these events. Passing expires_at and updates to last_used_at send no event. Existing keys receive no historical events, and revoking a key does not revoke keys it created.

See API key events and If a key leaks.

  • Breaking change
  • API
  • Api-keys
  • Authentication

Auth context describes each credential type#

These changes apply immediately to every supported API version.

GET /v1/auth-context returns one of five credential shapes: api_key, cli_login, workload_identity, partner_app, or onboarding_session. Each shape contains only its own fields. Dashboard sessions receive 401 INVALID_CREDENTIAL with reason wrong_credential_type.

  • mode (test or live) replaces environment. Test credentials include sandbox_id; live credentials omit it.
  • cli_login replaces the oauth value of auth_type.
  • API keys report access and current resolved scopes. Their nullable partner_app_install_id identifies an install link.
  • CLI, workload, and partner tokens report access: restricted and their current scopes.
  • Onboarding sessions report their user, sandbox, role capability, session expiry, and fresh verification expiry. They have no access or scopes.

Migration#

Select the response shape using auth_type. Replace reads of environment with mode, and handle cli_login where you previously handled oauth. Read only fields belonging to that credential type. Use can_manage_api_keys and fresh_verification_expires_at for onboarding sessions.

The CLI OAuth contexts response adds mode and retains a deprecated environment alias for CLI 0.17.0. Device authorization and reauthorization continue to accept environment as an alias for mode.

  • API
  • Checkout

Read a checkout's verification code requests#

GET /v1/checkout-sessions/{checkout_session_id}/customer-verifications lists a checkout's code requests, and GET /v1/checkout-sessions/{checkout_session_id}/customer-verifications/{checkout_session_customer_verification_id} reads one. Before, a headless checkout that reloaded between sending a code and confirming it lost the code request's ID and could only send another code, which replaced the first and counted against the checkout's limits.

Only the checkout's own credential can read. The list returns requests that haven't reached expires_at, by created_at descending and then by ID descending, and pages with page_size and page_token. After expires_at, the list leaves a request out and reading it by ID returns 404 RESOURCE_NOT_FOUND. A read returns the fields the create response returns, with email always masked, such as b•••@example.com. It never returns the code, a hash or token, or whether Flint sent a code, and a request reads the same whether or not Flint sent one. Reads send nothing and use no tries.

The CheckoutSessionCustomerVerification schema, the create and confirm routes, and their responses don't change. See Restore the code form after a reload.

  • Payments
  • Disputes
  • Billing

Countered dispute fees on new offers#

Offers created after this release include card_dispute_countered, charged at cost when evidence is submitted to counter a card dispute and Flint paid the processor's countered fee. The default maximum is $50.00 per fee, in USD. Existing offers remain unchanged: an offer without this rule carries no new countered event fee.

After a full win, Flint issues one billing credit against the original countered assessment once the processor returns that fee to Flint. Partial wins and losses receive no credit. The received fee, card_dispute, remains charged even on a win.

A countered fee already deducted from your connected balance stays in its dispute balance transactions and is not charged again in merchant billing. Stripe charges no countered fee for businesses in Mexico or Japan or for Smart Disputes counters; Flint bills none when Stripe charges none. Marketplace destination-charge disputes remain outside this event-fee flow.

Read GET /v1/merchant-billing-entries?dispute_id=... to reconcile the countered charge, its collection, and any later credit. Processing fees explains the amounts and payer rules.

  • API
  • Customers

Read customer verifications before linking purchases#

Your server can now retrieve a verification with GET /v1/customer-verifications/{customer_verification_id} or list a customer's verifications with GET /v1/customer-verifications?customer_id={customer_id}. Both require an API key with customers.read or customers.write.

The list requires customer_id, accepts page_size and page_token, and returns every status ordered by created_at descending, then customer_verification_id descending. Both reads return the fields that create and confirm return, with status and supported_actions computed when read. Use the current status when deciding whether to confirm a code or link guest purchases. Reading before linking is optional; linking checks the current state.

Flint deletes a verification 8 days after its code and its time to link have expired. Customer deletion also removes its verifications. After deletion, the single read returns 404 RESOURCE_NOT_FOUND, and the verification no longer appears in the list.

See Build your own customer account for the verification and linking flow.

  • Breaking change
  • API
  • Errors

Resource ID filters and empty request bodies are checked together#

These changes apply immediately to every supported API version.

Resource ID filters. The filters below now publish an ID prefix pattern. A malformed ID returns 400 INVALID_REQUEST with detail INVALID_VALUE at the filter, instead of an empty page. Its message names the resource and allowed prefix. Send the full ID returned by Flint, including its prefix and uppercase suffix. A well-formed ID that matches no visible resource still returns an empty page. Filters that refer to several resource types accept each type's prefix, including legacy and sandbox IDs.

OperationFilters with new patterns
GET /v1/api-request-logscaller_id, resource_id
GET /v1/balance-transactionsrelated_resource_id
GET /v1/bundlesdelivery_profile_id
GET /v1/checkout-sessionsorder_id, payment_link_id, customer_id
GET /v1/credit-notesinvoice_id, customer_id
GET /v1/customer-deletion-requestscustomer_id
GET /v1/delivery-location-setsdelivery_method_id
GET /v1/delivery-methodsdelivery_zone_id, delivery_location_set_id, delivery_rate_callback_id, location_id
GET /v1/delivery-rate-callbacksdelivery_method_id
GET /v1/delivery-zonesdelivery_method_id
GET /v1/deviceslocation_id
GET /v1/disputespayment_intent_id, order_id, customer_id
GET /v1/fulfillment-eventsfulfillment_id, shipment_id, package_id, order_id
GET /v1/fulfillment-notificationsfulfillment_id, order_id, fulfillment_event_id
GET /v1/fulfillmentsorder_id, customer_id, location_id
GET /v1/gift-card-funding-dispositionsdispute_id
GET /v1/gift-card-loadsgift_card_id, order_id
GET /v1/gift-card-notificationsgift_card_id
GET /v1/gift-card-redemptionsgift_card_id, order_id
GET /v1/gift-card-transactionsgift_card_id, order_id, source_id
GET /v1/inventory-adjustmentsinventory_item_id, location_id
GET /v1/inventory-countsinventory_item_id, location_id
GET /v1/inventory-levelsinventory_item_id, location_id
GET /v1/inventory-movementsinventory_item_id, location_id, return_id, return_disposition_id, source_reference_id
GET /v1/inventory-receiptsinventory_item_id, receiving_location_id, inventory_reservation_id, return_id, return_disposition_id
GET /v1/inventory-transfersinventory_item_id, origin_location_id, destination_location_id
GET /v1/invoicescustomer_id, order_id, subscription_id
GET /v1/me/fulfillment-eventsorder_id, fulfillment_id, shipment_id, package_id
GET /v1/me/fulfillmentsorder_id
GET /v1/me/gift-card-transactionsgift_card_id
GET /v1/me/invoicesorder_id
GET /v1/me/orderssubscription_id
GET /v1/me/packagesshipment_id, fulfillment_id, order_id
GET /v1/me/payment-intentsorder_id, invoice_id
GET /v1/me/refundsorder_id, return_id
GET /v1/me/returnsorder_id, return_reason_id
GET /v1/me/shipmentsorder_id, fulfillment_id, return_id
GET /v1/me/subscriptionsdelivery_method_id, subscription_plan_id
GET /v1/merchant-signupspartner_app_id
GET /v1/orderssubscription_id, return_id, return_resolution_id, payment_link_id
GET /v1/packagesshipment_id, fulfillment_id, order_id
GET /v1/partner-app-installspartner_app_id
GET /v1/partner-apps/{partner_app_id}/installsmerchant_id
GET /v1/payment-intentsorder_id, customer_id, invoice_id, return_id, return_resolution_id
GET /v1/payment-methodscustomer_id
GET /v1/payoutspayout_destination_id
GET /v1/platform-fee-balance-transactionspartner_app_id, platform_fee_id
GET /v1/platform-fee-balancespartner_app_id
GET /v1/platform-feespartner_app_id, partner_app_install_id, merchant_id, payment_intent_id
GET /v1/productsdelivery_profile_id
GET /v1/products/{product_id}/variantsdelivery_profile_id
GET /v1/promotion-codespromotion_id, customer_id
GET /v1/promotionsproduct_id, variant_id, bundle_id
GET /v1/readerslocation_id, device_id
GET /v1/refundsorder_id, payment_intent_id, customer_id, credit_note_id, return_id, return_resolution_id
GET /v1/return-dispositionsinventory_location_id, replaces_return_disposition_id, return_id, return_inspection_line_item_id, return_line_item_id, return_receipt_line_item_id
GET /v1/return-inspectionsinspection_location_id, return_id, return_line_item_id, return_receipt_id
GET /v1/return-receiptsreceiving_location_id, return_id, return_line_item_id, shipment_id
GET /v1/return-resolutionscorrects_return_resolution_id, return_id, return_line_item_id, return_policy_revision_id
GET /v1/returnscustomer_id, order_id, receiving_location_id, return_reason_id
GET /v1/returns/{return_id}/line-itemsfulfillment_id, order_line_item_id, return_reason_id
GET /v1/shipmentsorder_id, fulfillment_id, return_id
GET /v1/subscription-delivery-migrationsfrom_delivery_method_id
GET /v1/subscription-offersproduct_id, variant_id
GET /v1/subscriptionscustomer_id, delivery_method_id, subscription_offer_id, subscription_plan_id
GET /v1/webhook-endpointspartner_app_id
GET /v1/webhook-eventswebhook_endpoint_id, partner_app_id, resource_id, api_request_log_id, request_id
GET /v1/webhook-events/streamafter_event_id

Caller-owned external references, external actor/source IDs, provider event IDs, client request IDs, trace IDs, and OAuth protocol inputs keep their existing formats.

Operations without a published request body. Authentication and other protocol checks run first. A malformed body no longer masks an authentication failure. An absent body or {} passes. Any JSON member returns 400 INVALID_REQUEST with detail UNKNOWN_FIELD at that member, alongside every other schema failure, up to 50 details. For example, {"note":"accepted"} on acceptDispute now names note as an unknown field. Malformed JSON or a non-object JSON root returns detail INVALID_VALUE at body.

The operations below publish no request body. Send no body when calling them. OAuth protocol routes and operations with a declared non-JSON body retain their protocol behavior.

Method and resourceOperations
DELETE /v1/bundlesdeleteBundle
DELETE /v1/categoriesdeleteCategory
DELETE /v1/checkout-sessionsdeleteCheckoutSessionCurrentDeliverySelection
DELETE /v1/custom-domainsdeleteCustomDomain
DELETE /v1/customersdeleteCustomerAddress, deleteCustomerTaxExemption
DELETE /v1/delivery-location-setsdeleteDeliveryLocationSet
DELETE /v1/delivery-methodsdeleteDeliveryMethod
DELETE /v1/delivery-profilesdeleteDeliveryProfile
DELETE /v1/delivery-rate-callbacksdeleteDeliveryRateCallback
DELETE /v1/delivery-zonesdeleteDeliveryZone
DELETE /v1/devicesdeleteDevice
DELETE /v1/inventory-allocation-policiesdeleteInventoryAllocationPolicy
DELETE /v1/inventory-itemsdeleteInventoryItem
DELETE /v1/invoice-payment-termsdeleteInvoicePaymentTerm
DELETE /v1/locationsdeleteLocation
DELETE /v1/me/addressesdeleteMeAddress
DELETE /v1/me/gift-cardsremoveMeGiftCard
DELETE /v1/me/payment-methodsdeleteMePaymentMethod
DELETE /v1/modifier-groupsdeleteModifierGroup
DELETE /v1/modifier-setsdeleteModifierSet
DELETE /v1/ordersdeleteOrderCharge, deleteOrderLineItem, removeOrderGiftCard
DELETE /v1/packagesdeletePackageItem
DELETE /v1/partner-appsdeletePartnerApp, deletePartnerAppCredential
DELETE /v1/payment-methodsdeletePaymentMethod
DELETE /v1/payout-destinationsdeletePayoutDestination
DELETE /v1/price-listsdeletePriceList, deletePriceListPrice
DELETE /v1/productsdeleteProduct, deleteProductVariant
DELETE /v1/promotion-codesdeletePromotionCode
DELETE /v1/promotionsdeletePromotion
DELETE /v1/readersdeleteReader
DELETE /v1/return-policiesdeleteReturnPolicy
DELETE /v1/return-reasonsdeleteReturnReason
DELETE /v1/returnsdeleteReturnLineItem
DELETE /v1/risk-listsdeleteRiskList, deleteRiskListItem
DELETE /v1/risk-rulesdeleteRiskRule
DELETE /v1/sandboxesdeleteSandbox
DELETE /v1/subscription-offersdeleteSubscriptionOffer
DELETE /v1/subscription-plansdeleteSubscriptionPlan
DELETE /v1/subscriptionsdeleteSubscriptionLineItem
DELETE /v1/tax-calculation-callbacksdeleteTaxCalculationCallback
DELETE /v1/tax-connectiondeleteTaxRegistration
DELETE /v1/test-clocksdeleteTestClock
DELETE /v1/webhook-endpointsdeleteWebhookEndpoint
DELETE /v1/workload-identitiesdeleteWorkloadIdentity
GET /v1/analyticsgetAnalyticsOverview, getPaymentVolumeTimeseries, getSubscriptionAnalytics
GET /v1/api-keysgetAPIKey, listAPIKeys
GET /v1/api-request-logsgetAPIRequestLog, listAPIRequestLogs
GET /v1/auth-contextgetAuthContext
GET /v1/balance-transactionsgetBalanceTransaction, listBalanceTransactions
GET /v1/balanceslistBalances
GET /v1/bundlesgetBundle, listBundleComponents, listBundles
GET /v1/categoriesgetCategory, listCategories
GET /v1/checkout-sessionsgetCheckoutSession, getCheckoutSessionCurrentDeliverySelection, getCheckoutSessionDeliverySelection, listCheckoutSessionDeliverySelections, listCheckoutSessions
GET /v1/credit-notesgetCreditNote, getCreditNoteAllocation, getCreditNotePDF, listCreditNoteAllocations, listCreditNotes
GET /v1/custom-domainsgetCustomDomain, listCustomDomains
GET /v1/customer-deletion-requestsgetCustomerDeletionRequest, listCustomerDeletionRequests
GET /v1/customersgetCustomer, getCustomerAddress, getCustomerEmailPreferences, getCustomerTaxExemption, listCustomerAddresses, listCustomerTaxExemptions, listCustomers
GET /v1/delivery-location-setsgetDeliveryLocationSet, listDeliveryLocationSets
GET /v1/delivery-methodsgetDeliveryMethod, listDeliveryMethods
GET /v1/delivery-profilesgetDeliveryProfile, listDeliveryProfiles
GET /v1/delivery-quotesgetDeliveryQuote, listDeliveryQuotes
GET /v1/delivery-rate-callbacksgetDeliveryRateCallback, listDeliveryRateCallbacks
GET /v1/delivery-revocationsgetDeliveryRevocation, listDeliveryRevocations
GET /v1/delivery-zonesgetDeliveryZone, listDeliveryZones
GET /v1/devicesgetDevice, listDevices
GET /v1/disputesgetDispute, listDisputes
GET /v1/feedback-reportsgetFeedbackReport, listFeedbackReports
GET /v1/filesgetFile
GET /v1/fraud-warningsgetFraudWarning, listFraudWarnings
GET /v1/fulfillment-eventsgetFulfillmentEvent, listFulfillmentEvents
GET /v1/fulfillment-notificationsgetFulfillmentNotification, listFulfillmentNotifications
GET /v1/fulfillmentsgetFulfillment, listFulfillments
GET /v1/gift-card-funding-dispositionsgetGiftCardFundingDisposition, listGiftCardFundingDispositions
GET /v1/gift-card-loadsgetGiftCardLoad, listGiftCardLoads
GET /v1/gift-card-notificationsgetGiftCardNotification, listGiftCardNotifications
GET /v1/gift-card-redemptionsgetGiftCardRedemption, listGiftCardRedemptions
GET /v1/gift-card-transactionslistGiftCardTransactions
GET /v1/gift-cardsgetGiftCard, listGiftCards
GET /v1/inventory-adjustmentsgetInventoryAdjustment, listInventoryAdjustments
GET /v1/inventory-allocation-policiesgetInventoryAllocationPolicy, getInventoryAllocationPolicyRevision, listInventoryAllocationPolicies, listInventoryAllocationPolicyRevisions
GET /v1/inventory-countsgetInventoryCount, listInventoryCounts
GET /v1/inventory-itemsgetInventoryItem, listInventoryItems
GET /v1/inventory-levelsgetInventoryLevel, listInventoryLevels
GET /v1/inventory-movementsgetInventoryMovement, listInventoryMovements
GET /v1/inventory-receiptsgetInventoryReceipt, listInventoryReceipts
GET /v1/inventory-reservationsgetInventoryReservation, listInventoryReservations
GET /v1/inventory-transfersgetInventoryTransfer, listInventoryTransfers
GET /v1/invoice-payment-termsgetInvoicePaymentTerm, listInvoicePaymentTerms
GET /v1/invoicesgetInvoice, getInvoiceManualPayment, getInvoicePDF, getInvoicePaymentAttempt, listInvoiceActivities, listInvoiceDeliveryAttempts, listInvoiceManualPayments, listInvoicePaymentAttempts, listInvoices
GET /v1/locationsgetLocation, listLocations
GET /v1/megetMe
GET /v1/me/addressesgetMeAddress, listMeAddresses
GET /v1/me/deletion-requestsgetMeDeletionRequest, listMeDeletionRequests
GET /v1/me/email-preferencesgetMeEmailPreferences
GET /v1/me/flint-walletlistMeFlintWalletCards
GET /v1/me/fulfillment-eventslistMeFulfillmentEvents
GET /v1/me/fulfillmentsgetMeFulfillment, listMeFulfillments
GET /v1/me/gift-card-transactionslistMeGiftCardTransactions
GET /v1/me/gift-cardsgetMeGiftCard, listMeGiftCards
GET /v1/me/invoicesgetMeCreditNote, getMeCreditNotePDF, getMeInvoice, getMeInvoicePDF, listMeCreditNotes, listMeInvoices
GET /v1/me/ordersgetMeOrder, getMeOrderReceiptPDF, listMeOrderActivities, listMeOrders
GET /v1/me/packagesgetMePackage, listMePackages
GET /v1/me/payment-intentsgetMePaymentIntent, listMePaymentIntents
GET /v1/me/payment-methodsgetMePaymentMethod, listMePaymentMethods
GET /v1/me/refundsgetMeRefund, listMeRefunds
GET /v1/me/return-resolutionsgetMeReturnResolution
GET /v1/me/returnsgetMeReturn, listMeReturns
GET /v1/me/shipmentsgetMeShipment, listMeShipments
GET /v1/me/subscriptionsgetMeSubscription, getMeSubscriptionPaymentRetry, listMeSubscriptionPaymentRetries, listMeSubscriptions
GET /v1/me/ticketslistMeTickets
GET /v1/merchantgetMerchant
GET /v1/merchant-billing-balancesgetMerchantBillingBalance, listMerchantBillingBalances
GET /v1/merchant-billing-entrieslistMerchantBillingEntries
GET /v1/merchant-billing-invoicesgetMerchantBillingInvoice, listMerchantBillingInvoices
GET /v1/merchant-signupsgetMerchantSignup, listMerchantSignups
GET /v1/modifier-groupsgetModifierGroup, listModifierGroups
GET /v1/modifier-setsgetModifierSet, listModifierSets
GET /v1/onboardinggetOnboardingState
GET /v1/openapi.jsongetOpenAPISpec
GET /v1/ordersgetOrder, getOrderCurrentDeliverySelection, getOrderEdit, getOrderPaymentAttempt, getOrderReceiptPDF, listOrderActivities, listOrderEdits, listOrderPaymentAttempts, listOrders
GET /v1/packagesgetPackage, getPackageItem, listPackageItems, listPackages
GET /v1/partner-app-installslistMerchantPartnerAppInstalls
GET /v1/partner-appsgetPartnerApp, getPartnerAppCredential, getPartnerAppInstall, listPartnerAppCredentials, listPartnerAppInstalls, listPartnerApps
GET /v1/payment-intentsgetPaymentIntent, listPaymentIntentActivities, listPaymentIntents
GET /v1/payment-linksgetPaymentLink, getPaymentLinkPublic, listPaymentLinks
GET /v1/payment-method-domainsgetPaymentMethodDomain, listPaymentMethodDomains
GET /v1/payment-methodsgetPaymentMethod, listPaymentMethods
GET /v1/payment-reviewsgetPaymentReview, listPaymentReviews
GET /v1/payout-destinationsgetPayoutDestination, listPayoutDestinations
GET /v1/payout-settingsgetPayoutSettings
GET /v1/payoutsgetPayout, listPayouts
GET /v1/platform-fee-balance-transactionsgetPlatformFeeBalanceTransaction, listPlatformFeeBalanceTransactions
GET /v1/platform-fee-balanceslistPlatformFeeBalances
GET /v1/platform-feesgetPlatformFee, listPlatformFees
GET /v1/price-listsgetPriceList, getPriceListPrice, listPriceListPrices, listPriceLists
GET /v1/productsgetProduct, getProductOption, getProductVariant, listProductOptions, listProductVariants, listProducts
GET /v1/promotion-codesgetPromotionCode, listPromotionCodes
GET /v1/promotionsgetPromotion, listPromotions
GET /v1/readersgetReader, listReaders
GET /v1/refundsgetRefund, listRefunds
GET /v1/report-downloadsgetReportDownload
GET /v1/reportsgetReport, listReports
GET /v1/resource-timelinesgetResourceTimeline
GET /v1/return-dispositionsgetReturnDisposition, listReturnDispositions
GET /v1/return-inspectionsgetReturnInspection, listReturnInspections
GET /v1/return-policiesgetReturnPolicy, getReturnPolicyRevision, listReturnPolicies, listReturnPolicyRevisions
GET /v1/return-reasonsgetReturnReason, listReturnReasons
GET /v1/return-receiptsgetReturnReceipt, listReturnReceipts
GET /v1/return-resolutionsgetReturnResolution, listReturnResolutions
GET /v1/returnsgetReturn, getReturnLineItem, listReturnActivities, listReturnLineItems, listReturns
GET /v1/risk-listsgetRiskList, getRiskListItem, listRiskListItems, listRiskLists
GET /v1/risk-rulesgetRiskRule, getRiskRuleAttributes, listRiskRules
GET /v1/sandboxesgetSandbox, listSandboxes
GET /v1/settingsgetEffectiveSettings, getSettings
GET /v1/shipmentsgetShipment, listShipments
GET /v1/subscription-delivery-migrationsgetSubscriptionDeliveryMigration, listSubscriptionDeliveryMigrationFailures, listSubscriptionDeliveryMigrations
GET /v1/subscription-offersgetSubscriptionOffer, listSubscriptionOffers
GET /v1/subscription-plansgetSubscriptionPlan, listSubscriptionPlans
GET /v1/subscriptionsgetSubscription, getSubscriptionPaymentRetry, listSubscriptionPaymentRetries, listSubscriptions
GET /v1/tax-calculation-callbacksgetTaxCalculationCallback, listTaxCalculationCallbacks
GET /v1/tax-connectiongetTaxConnection, getTaxRegistration, listTaxRegistrations
GET /v1/test-clocksgetTestClock, listTestClocks
GET /v1/ticketsgetTicket, listTickets
GET /v1/webhook-deliveriesgetWebhookDelivery, listWebhookDeliveries, listWebhookDeliveryAttempts
GET /v1/webhook-endpointsgetWebhookEndpoint, listWebhookEndpoints
GET /v1/webhook-event-typeslistWebhookEventTypes
GET /v1/webhook-eventsgetWebhookEvent, listWebhookEvents, streamWebhookEvents
GET /v1/workload-identitiesgetWorkloadIdentity, listWorkloadIdentities
POST /v1/custom-domainsvalidateCustomDomain
POST /v1/customer-sessionsrevokeCustomerSession
POST /v1/customersrevokeCustomerSessions
POST /v1/delivery-rate-callbackscheckDeliveryRateCallbackConnection, createDeliveryRateCallbackTestDelivery, rotateDeliveryRateCallbackSecret
POST /v1/disputesacceptDispute, createDisputeResponseSession
POST /v1/invoicescancelInvoicePaymentAttempt, sendInvoiceReminder
POST /v1/me/deletion-requestscreateMeDeletionRequest
POST /v1/me/flint-walletcreateMeFlintWalletStoreSetup
POST /v1/me/orderssendMeOrderReceipt
POST /v1/me/sessionrevokeMeSession
POST /v1/partner-app-installsrevokeMerchantPartnerAppInstall
POST /v1/partner-appsrevokePartnerAppEnvironmentGrant, revokePartnerAppInstall
POST /v1/payment-reviewsapprovePaymentReview
POST /v1/readerscreateReaderConnectionSession
POST /v1/sandboxesresetSandbox
POST /v1/tax-calculation-callbackscheckTaxCalculationCallbackConnection, createTaxCalculationCallbackTestDelivery, rotateTaxCalculationCallbackSecret

Quoted first keys in error paths. A param may start with a quoted JSON key, for both a body field and an unknown query name. Examples are ["status[]"] and ["é"]. Read these as one key; later segments follow the same path grammar as metadata["a.b"].

Read Validation errors for detail ordering and the 50-input limit.

  • Breaking change
  • API
  • Partners
  • Webhooks

Platform fee payouts use status events#

platform_fee_payout.updated has been removed. A payout changes only through its status events: platform_fee_payout.created, platform_fee_payout.succeeded, and platform_fee_payout.failed. Its other owned fields are immutable. The linked balance transaction sends balance_transaction.created.

  • API
  • Partners
  • Webhooks

Read and reconcile your platform fee payouts#

GET /v1/platform-fee-payouts and GET /v1/platform-fee-payouts/{platform_fee_payout_id} now show transfers from your partner apps' fee balances to your merchant balance. Read them with your own credentials and money_movement.platform_fees.read.

  • Payout events go to your own merchant endpoints: platform_fee_payout.created, .succeeded, and .failed.
  • Balances show payouts_enabled, payouts_disabled_reason, and next_payout_at.
  • Platform ledger entries show the payout that carried them in platform_fee_payout_id, with an exact filter on that field.
  • Your merchant ledger publishes payout credits as platform_fee_payout, previously other, and transfer reversals as platform_fee_payout_reversal. Their related_resource names the platform fee payout.

See Platform fees for statuses, filters, and reconciliation.

  • Breaking change
  • API
  • Errors
  • Api-keys

Shared errors name the input to change#

These changes apply to fresh errors in every supported API version. Idempotent replays keep the recorded response shape. Update integrations that compare param or validation detail codes.

  • An operation that doesn't accept expand reports INVALID_REQUEST with UNKNOWN_FIELD at expand, including when its value is empty or malformed. Before, the shared expansion parser could report INVALID_VALUE for a query parameter the operation didn't accept.
  • Unsupported query names are one input. A name containing brackets or dots uses the quoted form, such as ["expand[]"], ["expand[0]"], or ["expand.customer"]. It doesn't identify an array item or a nested body field. Invalid values of a published multi-value query parameter use the query name without an index, such as expand.
  • An operation that doesn't accept top-level metadata reports UNKNOWN_FIELD at metadata, whatever value you sent, including duplicate keys. Unknown metadata is collected with other request failures; the first failure can name a query input. Before, shared metadata checks could report INVALID_VALUE at metadata or one of its entries. Operations that accept metadata continue to name a failing entry, such as metadata.order_ref. A duplicate JSON key in an unknown field reports UNKNOWN_FIELD at the first unknown field in its path. Metadata-shaped values inside an unknown field or a field with the wrong type report that field instead of a nested metadata entry.
  • Oversized body errors include a primary detail at body. Unsupported content types include a primary detail at Content-Type. Missing authentication includes a primary detail at Authorization. These errors previously could publish a top-level param without a detail.
  • The top-level param repeats details[0].param for every error code on fresh responses, preserving an explicit input path when the first detail previously omitted it. Read details to identify the inputs associated with additional failures.
  • A credential missing a merchant environment reports INVALID_VALUE at Authorization, because that credential must be replaced. Dashboard requests missing environment selection report REQUIRED at Flint-Sandbox-Id. These errors previously fell back to body.

Headers use their published names without a prefix: Content-Type, Authorization, Idempotency-Key, and X-Request-Id.

  • Breaking change
  • API
  • Subscriptions
  • Webhooks

Subscription attention events follow committed changes#

Every committed subscription attention change sends subscription.updated, including a return to an earlier state. Retrying an unchanged attention update sends no event.

  • Breaking change
  • Webhooks

New resource events omit previous_attributes#

Events reporting a new resource now omit data.previous_attributes. This includes status events sent when the resource is created, such as refund.succeeded beside refund.created, and merchant_billing_invoice.issued.

Previously, some of these events included previous_attributes with null values for every field. There was no prior resource to compare. Treat an absent previous_attributes as no recorded previous values. Events for later changes still include previous values when available.

  • Breaking change
  • Webhooks
  • Merchants

Provider configuration readiness events include capability projections#

merchant.readiness_updated events sent after provider configuration changes now include the same payment and payout capability projections as GET /v1/merchant.

Readiness event payloads use current readiness when Flint records the event. A delayed update no longer sends an earlier readiness snapshot. Event frequency and event keys are unchanged: distinct publishing sources can still send events with unchanged readiness.

  • Breaking change
  • Webhooks
  • Merchants

Readiness events fire only when readiness changes#

Breaking: merchant.readiness_updated now fires only when published readiness changes in that merchant environment. An account observation, payout capability transition, provider configuration update, or processing readiness update that leaves readiness unchanged sends no event. A change to readiness.observed_at alone is silent.

The payload remains the merchant as GET /v1/merchant returns it. Live mode and each sandbox track readiness independently. The first readiness publication in each merchant environment after this release sends once, even if readiness matches an earlier event. While this change rolls out, you may receive another event with unchanged readiness. After rollout, later unchanged observations are silent. Event keys stay unchanged, and delivery retries can still repeat an event.

See Merchant readiness.

  • Breaking change
  • API
  • Errors

Brief database outages return a retryable 503#

When Flint's database is briefly unavailable, such as during a failover, a request that can't reach it now returns 503 SERVICE_UNAVAILABLE on every operation:

  • type is unavailable_error, error_source is flint, and there is no reason.
  • remediation.retry is same_request, as it was for the 500.
  • Retry-After gives a short wait in seconds. Send the same request again after it, with the same Idempotency-Key if you sent one.
  • request_log_url is omitted, because Flint couldn't store the request log.

This covers a lost or refused database connection, a database that is shutting down, refusing connections or failing over, and a database query that timed out. It also covers saving a payment method and the payout readiness check when a readiness read fails this way.

500 INTERNAL_ERROR still means a fault Flint must fix, such as data that can't be read or a broken invariant. Errors with their own code, such as a payment processing 503 PAYMENT_PROCESSING_UNAVAILABLE, are unchanged.

An idempotent request that failed this way is never recorded as a final result. A retry with the same key runs the request again when it failed before Flint reserved the key. Otherwise the retry returns 409 IDEMPOTENCY_KEY_IN_PROGRESS until the original attempt's reservation ends, then resumes or reports the original outcome as Replay And Recovery describes.

Breaking: these requests used to return 500 INTERNAL_ERROR with type internal_error and no Retry-After. Clients that stop on a 500 but retry a 503 now retry them. A request_log_url that couldn't be stored is no longer returned.

  • Breaking change
  • API
  • Delivery
  • Checkout

Delivery selections move to top-level routes#

Breaking: delivery selections now live only at /v1/delivery-selections, like delivery quotes. Six routes are removed:

RemovedUse instead
POST /v1/checkout-sessions/{checkout_session_id}/delivery-selections (createCheckoutSessionDeliverySelection)POST /v1/delivery-selections (createDeliverySelection). The selection acts on the checkout session of the quote named by delivery_quote_id.
DELETE /v1/checkout-sessions/{checkout_session_id}/delivery-selections/current (deleteCheckoutSessionCurrentDeliverySelection)POST /v1/delivery-selections/{delivery_selection_id}/release (releaseDeliverySelection)
GET /v1/checkout-sessions/{checkout_session_id}/delivery-selections/current (getCheckoutSessionCurrentDeliverySelection)Read the session's delivery.delivery_selection_id, or the order's governing_delivery_selection_id, then GET /v1/delivery-selections/{delivery_selection_id}
GET /v1/orders/{order_id}/delivery-selections/current (getOrderCurrentDeliverySelection)The order's governing_delivery_selection_id, then GET /v1/delivery-selections/{delivery_selection_id}
GET /v1/checkout-sessions/{checkout_session_id}/delivery-selections (listCheckoutSessionDeliverySelections)GET /v1/delivery-selections?checkout_session_id=... (listDeliverySelections)
GET /v1/checkout-sessions/{checkout_session_id}/delivery-selections/{delivery_selection_id} (getCheckoutSessionDeliverySelection)GET /v1/delivery-selections/{delivery_selection_id} (getDeliverySelection)

The create request and response are otherwise unchanged. The response of /current reads wrapped the selection in source, mutable, and originating_checkout_session_id. A selection read by ID returns the selection itself: its status says whether it is provisional (selected or locked_for_payment) or committed, and its checkout_session_id names the session that made it.

Release replaces the delete. It names the selection in the path, so it takes no expected_delivery_selection_id. Every DeliverySelection now has supported_actions, which lists release while status is selected. Releasing a selection in any other status returns 409 ACTION_NOT_ALLOWED with current_status and an empty supported_actions, or 409 OPERATION_IN_PROGRESS while a payment owns it.

The list takes checkout_session_id or order_id, one of which is required, and an optional status filter with several values. With a status filter, a page examines at most 500 selections, so keep paging until next_page_token is absent.

The checkout credential now works on the list and the read by ID, for its own checkout session only:

  • On create, the quote must belong to the credential's own session. On the list, checkout_session_id is required and must be the credential's own.
  • A read or release reaches only a selection of the credential's own session.
  • Any other quote, session, or selection returns 404 RESOURCE_NOT_FOUND, the same as one that doesn't exist.

An Idempotency-Key used with the old routes doesn't replay on the new ones. With an API key or partner token, the create's key no longer includes the checkout session, so reusing one key for selections on two checkout sessions is a key-reuse error. Use a new key for each request. See Delivery selections.

  • API
  • Partners
  • Onboarding

Onboard merchants inside your platform#

A platform that Flint approves can onboard a merchant without the owner approving a live key or signing in to Flint. The owner types one emailed code into the platform's form, the platform onboards the merchant with its partner app token, and Flint's emails about finishing verification lead back to the platform's app.

  • Hosted onboarding. POST /v1/onboarding/access-links returns an AccessLink with purpose merchant_onboarding. Redirect the owner to its url and Flint's page opens Account Onboarding and Notification Banner in the credential's mode, so a platform that doesn't embed Connect.js can still verify merchants. The link opens once, within 5 minutes, into a browser session of up to an hour. return_url is required: an HTTPS URL without credentials, and for a partner app install token its origin must be the origin of your merchant_action_url or one of your redirect URIs. A retry with the same Idempotency-Key and body within 24 hours returns the same link to the credential that created it, without extending it. See Onboarding access links.
  • Merchant signups. POST /v1/merchant-signups creates a merchant and installs your app in test and live mode when the owner types the code Flint emails. The signup issues no key, CLI login, or onboarding session. Live signups need Flint to approve the create_merchants capability; before then, test signups work for your own team's addresses. When your app declares payment_splits, the code email also asks the owner to approve receiving split funds.
  • Emails that lead to your app. While your install manages a merchant it created, Flint's emails about finishing verification and the processor's notification link go to your merchant_action_url, with flint_* query parameters. The processor's links for the account, payouts, balances, documents, payments, and disputes, Flint's dispute and payout notices, and risk and review notices still lead to Flint's sign-in, so the owner keeps a Flint login for them. See Emails that lead to your app.
  • In the Dashboard. An app's Platform tab sets merchant_action_url. Connected apps marks an install created through a signup, and an owner who can manage connected apps sees a dismissible banner that names your app when they sign in to Flint.
  • Disconnecting. The first revoke of a signup's install ends everything it gave you, returns those emails to Flint for good, and emails the owner once that they can sign in to Flint to manage their account.

Build payments into your platform now follows one studio from signup to payout, and covers studios that already have a Flint account.

  • Breaking change
  • API
  • Orders
  • Checkout

Order changes release the delivery selection in the same request#

Breaking: a change to an order that releases its checkout's delivery selection now releases it in the same request, with any credential. The order the change returns is the order after the release:

  • charges no longer has the selection's delivery charge, and the totals, tax, and discounts no longer include it.
  • governing_delivery_selection_id is null, and inventory_reservation_id is null when the reservation was the selection's stock hold. That stock is released.
  • The checkout session stays open and reads delivery_selection_required: true. The selection's last lifecycle event is released with reason order_mutated.

Before, the response still showed the delivery charge and its total, and the release happened on the next read of the order or session. A storefront that rendered the response showed a total that payment then refused with 409 ACTION_NOT_ALLOWED and reason configuration_required.

These changes release a selection: adding or removing a line item, changing a quantity, modifiers, or a line price, applying or removing a discount or promotion code, and changing inventory_routing_source. A tip, a tax location, the buyer's contact, metadata, notes, a charge, and a declined payment keep a selection that is still usable. The response to a tip, tax, or charge change now shows the kept selection in governing_delivery_selection_id, where before it showed null until the next read. A selection that a payment holds is never released by a change.

Edits to an open, unpaid order also release a provisional selection that has expired, no longer matches the order, has a revoked backing quote, or depends on revoked delivery configuration. Closing an order releases its provisional selection too. This includes tip, metadata, and note changes, and subscription renewal orders without a checkout session. The response already excludes the delivery charge; another read is not needed to remove it. An expired selection records expired with reason selection_expired or calculation_expired; other unusable selections record released with the applicable reason.

While the selection held tracked stock, a new quantity on a tracked line, a new or removed tracked line, or a new inventory_routing_source used to return 409 RESOURCE_IN_USE naming the selection's reservation. Those changes now release the selection and its hold. Stock kept for the rest of a partly paid order isn't the selection's, so the same changes still return 409 RESOURCE_IN_USE with that reservation in details[0].blocking_resources.

The release sends order.updated, and inventory_level.updated when stock was held. No delivery selection or checkout session event is sent.

Render the order your change returns, and ask the buyer to choose delivery again when governing_delivery_selection_id is null. See Keep the selection through later changes.

  • API
  • Partners
  • Webhooks

Read your partner apps' platform fees, balances, and ledger#

A platform can now see what its partner apps earned.

  • GET /v1/platform-fees and GET /v1/platform-fees/{platform_fee_id}. Each fee shows the installed merchant, the payment, its status (pending, succeeded, or canceled with a canceled_reason), what the request asked for, what Flint charged, and the share Flint held in your reserve.
  • GET /v1/platform-fee-balances. One balance per partner app and currency: available_money, pending_money until Flint's own funds are available, and reserve_money.
  • GET /v1/platform-fee-balance-transactions and its single-entry read. Every movement of a balance: platform_fee, reserve_hold, and reserve_release today.
  • money_movement.platform_fees.read. The new scope these routes require, separate from developer.partner_apps.read. Partner app tokens can't read them.
  • Events. platform_fee.created, platform_fee.updated, platform_fee.succeeded, and platform_fee.canceled go to the owning merchant's own endpoints in the fee's mode.
  • Sandbox resets. When an installed merchant resets the sandbox a test payment was in, Flint cancels that payment's pending fee with payment_not_completed.

See Platform fees.

  • Webhooks
  • Subscriptions

Subscription notices record the subscription's current version#

subscription.trial_ending, subscription.renewal_upcoming, and subscription.end_upcoming now record the subscription at the version current when Flint sends the notice, as does a subscription.dunning_exhausted that leaves the subscription past_due. These events change nothing, so they carry no data.previous_attributes. Before, Flint read the subscription when it prepared the event, so the payload could include a later change.

Each notice is still sent once for the date it announces. A trial end that moves, or a renewal that's rescheduled, is announced again.

If Flint retries one of these notices while this change deploys, it can arrive twice, with different event IDs.

See Webhook events.

  • Breaking change
  • API
  • Partners
  • Payments
  • Subscriptions

Orders that start a subscription refuse platform fees#

Superseded by Create order payments through the payment intents collection.

Subscriptions don't accept a platform fee: Flint's billing creates the renewals, not a request your app sends, so a fee on the first payment only would mislead. subscription_plan checkout sessions already refused one. Orders whose payment starts a subscription accepted it, and now refuse it too.

RequestBeforeNow
POST /v1/orders/{order_id}/payment-intents on a subscription orderCharged the fee on the first payment400 INVALID_REQUEST with NOT_ALLOWED on platform_fee
POST /v1/orders/{order_id}/pay with action: pay on a subscription orderCharged the fee on the first paymentThe same
POST /v1/checkout-sessions with type: order for an order with a subscribed lineCharged the fee on the session's paymentThe same

A subscription order is a plan's signup order, an order with a subscribed line, an order linked to a subscription, or a renewal order Flint creates. Send these requests without platform_fee. Other orders keep accepting one.

If an open checkout changes to a subscription, its stored fee no longer applies. Any fee on an unpaid payment is canceled as uncollectible before collection.

  • API
  • Sandboxes

Test keys reset their own sandbox, and the default sandbox resets#

A test credential (a test key, a sandbox CLI login, or a sandbox workload token) can now read and reset the sandbox it's bound to, so a CI run needs only one test key and no live key.

BeforeNow
GET /v1/sandboxes/{sandbox_id} with a test credential403 FORBIDDEN with reason live_mode_requiredIts own sandbox with developer.sandboxes.read or developer.sandboxes.write. Any other sandbox_id returns 404 RESOURCE_NOT_FOUND
POST /v1/sandboxes/{sandbox_id}/reset with a test credential403 FORBIDDEN with reason live_mode_requiredResets its own sandbox with developer.sandboxes.write. Any other sandbox_id returns 404 RESOURCE_NOT_FOUND
developer.sandboxes.read and developer.sandboxes.writeLive keys onlyLive and test keys. Full-access test keys hold both, and read-only test keys hold developer.sandboxes.read
Resetting the default sandbox409 ACTION_NOT_ALLOWED with reason unsupported_stateResets it. It stays the default, and its keys, onboarding sessions, and the Dashboard keep working

This applies to keys that already exist: a full-access test key now holds developer.sandboxes.write, so it can reset its sandbox, which deletes the sandbox's data. Where a key shouldn't be able to do that, use a restricted test key without developer.sandboxes.write.

Each sandbox can be reset once every 10 seconds and 500 times per UTC day, across every credential that can reset it. Past either limit, a reset gets 429 RATE_LIMIT_EXCEEDED with Retry-After; a retry with the same Idempotency-Key doesn't count again.

Listing, creating, and archiving sandboxes still take a live credential, and a test credential gets 403 FORBIDDEN with reason live_mode_required there. The default sandbox still can't be archived.

While the default sandbox resets, onboarding session requests that use it get 409 OPERATION_IN_PROGRESS with reason sandbox_resetting and Retry-After, as the sandbox's keys do. 409 OPERATION_IN_PROGRESS responses with reason sandbox_resetting now always carry Retry-After.

Give CI a clean sandbox for each run shows the one-key setup.

  • Breaking change
  • API
  • Delivery
  • Checkout

Delivery selections name the choice group that blocks them, and payment needs a complete address#

Breaking: these delivery refusals changed.

SituationBeforeNow
A choice group offers no option because its methods wait for quote input, such as an address409 DELIVERY_REQUOTE_REQUIRED, reason caller_rates_required409 DELIVERY_REQUOTE_REQUIRED, reason input_required, retry after_refresh
A choice group has no option for this destination and cart409 DELIVERY_REQUOTE_REQUIRED, reason caller_rates_required409 ACTION_NOT_ALLOWED, reason choice_group_unavailable, retry none
Creating a quote on a paid, partially_paid, or invalidated checkout session409 ACTION_NOT_ALLOWED, reason unsupported_state409 ACTION_NOT_ALLOWED, reason terminal_status, with current_status
Paying with a shipment or local delivery selection whose address has no streetAccepted, so the paid order could have only a postal code409 ACTION_NOT_ALLOWED, reason configuration_required, param: delivery_selection.destination_address.line1

caller_rates_required now means only that your server still owes rates for the quote. The two new reasons put one entry in details for each blocking group, with resource_type: delivery_choice_group and the group's delivery_choice_group_id as resource_id. A group that offers the option the buyer chose no longer blocks the selection when another method in it couldn't be calculated.

Selections and addresses:

  • A complete destination_address sent with a selection after a quote priced from a partial address is stored as sent, so the order's delivery_destination has the street. Members the quote priced keep the quote's value. Before, the selection kept the quote's partial address, and only the create response showed the full one.
  • A selection without a complete address is still accepted, as a wallet's is before the buyer approves the payment sheet. Its input_requirements list each missing destination_address member with purpose selection, and the quote lists the same requirements with the same IDs. A complete address has line1, city, and country, plus state and postal_code in the US.
  • Payment refuses until a new selection sends the missing members. The refusal has the same shape as a missing recipient field: next_actions includes update_checkout_session, whose required_fields names every missing field.

The selection create response and later reads now return the same stored address. See Delivery selections and Build your own checkout.