Skip to content
Changelog

Week of November 2, 2026

212 changes to the Flint API, SDKs, and docs, newest first, from November 2, 2026 to November 8, 2026. The newest changes are on the changelog.
  • Breaking change
  • API
  • Payments
  • Refunds

Payment intents publish the Affirm refund deadline#

Superseded by Affirm refund windows use the stored capture time.

Payment intents have a new read-only field, refund_expires_at. It's the last time Flint can refund the payment through its original payment method. Today only Affirm has a refund window: 120 days after the payment settles. The field is null for other payment methods, and for an Affirm payment until it's captured.

GET /v1/payment-intents/{payment_intent_id}, list responses, and payment_intent.* webhooks carry the same value. Schedule your own reminder from it instead of hardcoding 120 days.

Breaking: a refund submitted during the deadline's second used to be refused with 409 ACTION_NOT_ALLOWED and reason refund_window_expired. It's now accepted, so the deadline you read is the last accepted time. Refunds after it are still refused.

  • Breaking change
  • API
  • Checkout
  • Invoices
  • Returns

The checkout session surface embedded is now headless#

The checkout session surface for a checkout your own page renders is now named headless. Its values are hosted and headless. Flint has no checkout to embed in an iframe: a headless session gives your backend checkout_auth_token, and your storefront renders every screen. The new name says that.

Old -> new:

  • Request bodies: "surface": "embedded" -> "surface": "headless" on POST /v1/checkout-sessions, POST /v1/invoices/{invoice_id}/checkout-sessions, POST /v1/me/invoices/{invoice_id}/checkout-sessions, POST /v1/return-resolutions/{return_resolution_id}/checkout-sessions, and POST /v1/me/return-resolutions/{return_resolution_id}/checkout-sessions.
  • List filter: GET /v1/checkout-sessions?surface=embedded -> surface=headless.
  • Responses: CheckoutSession.surface and BuyerCheckoutSession.surface return headless for every headless session, including sessions created before this change. The same applies to the checkout_session.* webhook events Flint records from now on.

A request that sends embedded fails with 400 INVALID_REQUEST, param: "surface", like any other unknown value. There is no alias. page_origin and payment_return_url keep their names and are accepted only when surface is headless.

Webhook events recorded before this change keep embedded in their stored payload, including when Flint retries or resends them and when you read them from GET /v1/webhook-events.

To update your integration:

  1. Send "surface": "headless" wherever you sent "surface": "embedded", and filter lists with surface=headless.
  2. Compare surface against headless in your response and webhook handling. Accept embedded too until no event from before this change can still reach you.

Build your own checkout covers a headless session end to end.

  • Breaking change
  • API
  • Errors

Inputs that can't be sent together name the input to remove#

Superseded by Create order payments through the payment intents collection.

These changes apply immediately to every supported API version.

  • A request that sends inputs that can't be sent together gets 400 INVALID_REQUEST with one NOT_ALLOWED detail per conflict. Before, some endpoints answered with an INVALID_VALUE detail at the enclosing object, such as param: "body" and the message "body has an invalid value.", or with "must match one of the shapes this field accepts."
  • param names the input to remove:
    • When one of the inputs selects a mode, such as type, direction, access, or resolution_type, param is the other input and conflicting_fields names the selector. The message names the selector's value: "return_id can't be sent when direction is outbound."
    • Otherwise param is the input that sorts last in the order details uses, and conflicting_fields lists the others: {"param": "scheduled_issue_at", "conflicting_fields": ["issue"]} with the message "scheduled_issue_at can't be sent with issue."
  • conflicting_fields never repeats the detail's own param. Endpoints that listed both inputs, such as ["refund_type", "amount_money"], now list only the other one: ["refund_type"].
  • An input that must be the only one in its request, such as billing_schedule on PATCH /v1/subscriptions/{subscription_id}, expected_ship_date on PATCH /v1/orders/{order_id}/line-items/{order_line_item_id} (apart from expected_version), or status on the delivery and tax callback PATCH endpoints, gets one detail per other input you sent. Details at the same input are joined: "billing_schedule can't be sent with billing_interval or billing_interval_count."
  • The request schema check, which runs before any other rule, now reports these conflicts together with the request's other shape failures. Four conflicts that only the endpoint enforced are now published in the request schema as a not of their required names:
    • billing_schedule with any other mutable field on PATCH /v1/subscriptions/{subscription_id}
    • amount_money with percent on PATCH /v1/orders/{order_id}/charges/{order_charge_id}
    • inventory_item with inventory_item_id on POST /v1/products (default_variant and variants[]), POST /v1/products/{product_id}/variants, and PATCH /v1/products/{product_id}/variants/{variant_id}
    • payment_source_selection with a nonempty payment_options on POST /v1/orders/{order_id}/payment-intents
  • Conflicts and the request's other shape failures are reported together. A union of alternative shapes keeps its own "must match one of the shapes this field accepts." detail when the request also breaks it for another reason, and drops it when the conflicts explain it: {"promotion": {"promotion_id": "...", "promotion_code": "..."}, "manual": {...}} on POST /v1/orders/{order_id}/discounts reports both "promotion can't be sent with manual." and "promotion.promotion_id can't be sent with promotion.promotion_code."
  • A field that needs another one, such as decline_reason_message without decline_reason on a return decision, is REQUIRED at the missing field instead of the union detail.
  • scopes with access full or read_only on POST /v1/api-keys, PATCH /v1/api-keys/{api_key_id}, POST /v1/sandboxes, and the sandbox API key endpoint is reported by the schema check: "scopes can't be sent when access is full."
  • A conflict that depends on a value or on stored data, rather than on which inputs you sent, is still checked after the shape check and uses the same detail. For example, refunded_at on a credit note refund without processed_by: "merchant" is NOT_ALLOWED at refunded_at with conflicting_fields: ["processed_by"].
  • Replacement lines and receipt lines on returns that send more than one identity, such as variant_id and name, are NOT_ALLOWED instead of INVALID_VALUE.
  • Sending checkout session headers with Authorization lists only Authorization in conflicting_fields, and a repeated Authorization header has no conflicting_fields.

Read Validation errors for the rule. Remove the input in param, or the inputs in conflicting_fields, then send the corrected request.

Endpoints and inputs#

Each endpoint below publishes exclusions for the listed inputs, in its request schema. A path with [] covers every item of that array. An input the schema excludes without naming another input, such as flat_money on an order draft tax component, is an INVALID_VALUE detail at that input: "tax.calculation.components[0].flat_money can't be sent on this request."

  • POST /v1/api-keys: scopes
  • PATCH /v1/api-keys/{api_key_id}: access, scopes
  • POST /v1/bundles: images[].file_id, images[].source_url
  • PATCH /v1/bundles/{bundle_id}: images[].file_id, images[].source_url
  • POST /v1/checkout-sessions: customer_id, discounts, discounts[].promotion.promotion_code, discounts[].promotion.promotion_id, order_id, page_origin, payment_return_url, quick_pay_item, redirects, replace_checkout_session_id, and 3 more
  • POST /v1/checkout-sessions/{checkout_session_id}/delivery-quotes: buyer_location.address, buyer_location.coordinate
  • POST /v1/credit-notes: line_items[].correction.amount_money, line_items[].correction.quantity
  • PATCH /v1/credit-notes/{credit_note_id}: line_items[].correction.amount_money, line_items[].correction.quantity
  • POST /v1/credit-notes/{credit_note_id}/issue: allocation, refund
  • POST /v1/customers/{customer_id}/tax-exemptions: coverage.states
  • PATCH /v1/customers/{customer_id}/tax-exemptions/{customer_tax_exemption_id}: coverage.states
  • POST /v1/delivery-methods: configuration.eligibility.all, configuration.eligibility.any, configuration.eligibility.country, configuration.eligibility.customer_has_email, configuration.eligibility.customer_has_phone, configuration.eligibility.customer_merchant_verified, configuration.eligibility.customer_segment, configuration.eligibility.not, configuration.eligibility.postal_code, configuration.eligibility.radius, and 31 more
  • PATCH /v1/delivery-methods/{delivery_method_id}: configuration, configuration.eligibility.all, configuration.eligibility.any, configuration.eligibility.country, configuration.eligibility.customer_has_email, configuration.eligibility.customer_has_phone, configuration.eligibility.customer_merchant_verified, configuration.eligibility.customer_segment, configuration.eligibility.not, configuration.eligibility.postal_code, and 37 more
  • POST /v1/delivery-previews: buyer_location.address, buyer_location.coordinate, line_items[].bundle_id, line_items[].description, line_items[].fulfillment, line_items[].gift_card_purchase, line_items[].image, line_items[].inventory_demands, line_items[].modifiers[].modifier_id, line_items[].modifiers[].order_line_item_modifier_id, and 10 more
  • POST /v1/delivery-profiles: configuration.allowed_types, configuration.combination_policy, configuration.origin_policy, configuration.origin_policy.location_id, configuration.resolution_mode, configuration.splitting_policy
  • PATCH /v1/delivery-profiles/{delivery_profile_id}: configuration.allowed_types, configuration.combination_policy, configuration.origin_policy, configuration.origin_policy.location_id, configuration.resolution_mode, configuration.splitting_policy
  • PATCH /v1/delivery-rate-callbacks/{delivery_rate_callback_id}: configuration, external_reference_id, name, signing_methods, status
  • POST /v1/delivery-zones: configuration.all, configuration.any, configuration.country, configuration.not, configuration.postal_code, configuration.radius, configuration.state
  • PATCH /v1/delivery-zones/{delivery_zone_id}: configuration.all, configuration.any, configuration.country, configuration.not, configuration.postal_code, configuration.radius, configuration.state
  • POST /v1/discount-previews: discount.manual, discount.promotion, discount.promotion.promotion_code, discount.promotion.promotion_id
  • PATCH /v1/fulfillments/{fulfillment_id}: digital_details, local_delivery_details, pickup_details, service_details
  • POST /v1/fulfillments/{fulfillment_id}/shipments: packages, packages[].buyer_notification_behavior, packages[].return_line_items, packages[].shipped_at, return_id, return_line_items
  • POST /v1/gift-card-loads: source.order_id, source.order_manual_payment_id, source.payment_intent_id, source_created_at
  • POST /v1/gift-card-redemptions: expires_at
  • POST /v1/gift-cards: funding.source.order_id, funding.source.order_manual_payment_id, funding.source.payment_intent_id, funding.source_created_at
  • POST /v1/inventory-adjustments: lines[].source_observation_sequence, source_system.external_source_id
  • PATCH /v1/inventory-counts/{inventory_count_id}: source_system.external_source_id
  • POST /v1/inventory-receipts: source_system.external_source_id
  • POST /v1/inventory-reservations/{inventory_reservation_id}/consume: provenance.source_system.external_source_id
  • POST /v1/inventory-transfers/{inventory_transfer_id}/cancel: provenance.source_system.external_source_id
  • POST /v1/inventory-transfers/{inventory_transfer_id}/depart: provenance.source_system.external_source_id
  • POST /v1/inventory-transfers/{inventory_transfer_id}/receive: provenance.source_system.external_source_id
  • POST /v1/inventory-transfers/{inventory_transfer_id}/report-loss: provenance.source_system.external_source_id
  • POST /v1/inventory-transfers/{inventory_transfer_id}/return-to-origin: provenance.source_system.external_source_id
  • POST /v1/invoice-payment-terms: calculation.day, calculation.days, late_fee_policy.amount_money, late_fee_policy.percent
  • PATCH /v1/invoice-payment-terms/{invoice_payment_term_id}: calculation.day, calculation.days, late_fee_policy.amount_money, late_fee_policy.percent
  • POST /v1/invoices: collection.payment_method_id, collection.payment_policy, issue, order_id, payment_due.due_date, payment_due.invoice_payment_term_id, quick_pay, quick_pay.discounts[].manual, quick_pay.discounts[].promotion, quick_pay.discounts[].promotion.promotion_code, and 30 more
  • PATCH /v1/invoices/{invoice_id}: collection.payment_method_id, collection.payment_policy, payment_due.due_date, payment_due.invoice_payment_term_id, schedule_entries[].amount_specification.amount_money, schedule_entries[].amount_specification.percent, schedule_entries[].due.due_date
  • POST /v1/invoices/{invoice_id}/checkout-sessions: page_origin, payment_return_url, redirects
  • POST /v1/me/gift-cards: code, grant_id, recipient_access_token
  • POST /v1/me/invoices/{invoice_id}/checkout-sessions: page_origin, payment_return_url, redirects
  • POST /v1/me/return-previews: eligibility, eligibility.selection.line_items, resolution, resolution.replacement_line_items, resolution.replacement_line_items[].bundle_id, resolution.replacement_line_items[].variant_id
  • POST /v1/me/return-resolutions/{return_resolution_id}/checkout-sessions: page_origin, payment_return_url, redirects
  • PATCH /v1/merchant: icon.file_id, icon.source_url, logo.file_id, logo.source_url
  • POST /v1/modifier-sets: modifier_groups[].modifier_group, modifier_groups[].modifier_group_id
  • PATCH /v1/modifier-sets/{modifier_set_id}: modifier_groups[].modifier_group, modifier_groups[].modifier_group_id
  • POST /v1/orders: discounts[].manual, discounts[].promotion, discounts[].promotion.promotion_code, discounts[].promotion.promotion_id, line_items[].bundle_id, line_items[].description, line_items[].fulfillment, line_items[].gift_card_purchase, line_items[].image, line_items[].inventory_demands, and 19 more
  • PATCH /v1/orders/{order_id}: requested_tip.amount_money, requested_tip.percent, tax.calculation.components[].percent, tax.charge_calculations[].calculation.components[].flat_money, tax.delivery_charge_calculation.components[].flat_money, tax.line_item_calculations[].calculation.components[].flat_money
  • POST /v1/orders/{order_id}/charges: charge.amount_money, charge.percent, charge.tax.calculation.components[].flat_money
  • PATCH /v1/orders/{order_id}/charges/{order_charge_id}: amount_money, percent, tax.calculation.components[].flat_money
  • POST /v1/orders/{order_id}/discounts: manual, promotion, promotion.promotion_code, promotion.promotion_id
  • POST /v1/orders/{order_id}/fulfillments: digital_details, local_delivery_details, pickup_details, service_details, shipment, shipment.package, shipment.package.buyer_notification_behavior, shipment.package.return_line_items, shipment.package.shipped_at, shipment.packages, and 3 more
  • POST /v1/orders/{order_id}/line-items: line_items[].bundle_id, line_items[].description, line_items[].fulfillment, line_items[].gift_card_purchase, line_items[].image, line_items[].inventory_demands, line_items[].modifiers[].modifier_id, line_items[].modifiers[].order_line_item_modifier_id, line_items[].modifiers[].quantity, line_items[].modifiers[].text, and 8 more
  • PATCH /v1/orders/{order_id}/line-items/{order_line_item_id}: expected_ship_date with any other field except expected_version (description, gift_card_face_value_money, gift_card_recipient, metadata, modifiers, name, quantity, subscription, tax, unit_price_money); modifiers[].text with modifiers[].modifier_id or modifiers[].quantity; tax.calculation.components[].flat_money
  • POST /v1/orders/{order_id}/payment-intents: payment_options, payment_source_selection
  • POST /v1/payment-intents: transaction_purpose
  • POST /v1/payment-links: image.file_id, image.source_url, line_items[].allow_unit_price_adjustment, line_items[].bundle_id, line_items[].default_variant_id, line_items[].description, line_items[].max_unit_price_money, line_items[].min_unit_price_money, line_items[].name, line_items[].suggested_unit_price_money_options, and 4 more
  • PATCH /v1/payment-links/{payment_link_id}: image.file_id, image.source_url, line_items[].allow_unit_price_adjustment, line_items[].bundle_id, line_items[].default_variant_id, line_items[].description, line_items[].max_unit_price_money, line_items[].min_unit_price_money, line_items[].name, line_items[].suggested_unit_price_money_options, and 4 more
  • POST /v1/products: default_variant, default_variant.images[].file_id, default_variant.images[].source_url, default_variant.inventory_item, default_variant.inventory_item_id, images[].file_id, images[].source_url, options, variants, variants[].images[].file_id, and 3 more
  • PATCH /v1/products/{product_id}: images[].file_id, images[].source_url
  • POST /v1/products/{product_id}/variants: images[].file_id, images[].source_url, inventory_item, inventory_item_id
  • PATCH /v1/products/{product_id}/variants/{variant_id}: images[].file_id, images[].source_url, inventory_item, inventory_item_id
  • POST /v1/promotions: application_method.recurrence.period_count
  • PATCH /v1/promotions/{promotion_id}: application_method.recurrence.period_count
  • POST /v1/refunds: amount_money, charges, destinations, gift_card_load_id, line_items, tax_breakdown_refunds, tender_allocations, tender_allocations[].gift_card_redemption_id, tender_allocations[].payment_intent_id
  • POST /v1/reports: as_of_date, interval_end_at, interval_start_at
  • POST /v1/return-policies: revision.allowed_resolution_types, revision.automatic_resolution_type, revision.completion_mode, revision.ineligibility_reason, revision.release_timing, revision.resolution_mode, revision.resolution_selection_mode
  • POST /v1/return-policies/{return_policy_id}/revisions: revision.allowed_resolution_types, revision.automatic_resolution_type, revision.completion_mode, revision.ineligibility_reason, revision.release_timing, revision.resolution_mode, revision.resolution_selection_mode
  • POST /v1/return-previews: eligibility, eligibility.selection.line_items, resolution, resolution.corrects_return_resolution_id, resolution.line_items, resolution.pricing_basis, resolution.replacement_line_items, resolution.replacement_line_items[].bundle_id, resolution.replacement_line_items[].fulfillment, resolution.replacement_line_items[].name, and 1 more
  • PATCH /v1/return-resolutions/{return_resolution_id}: replacement_line_items[].bundle_id, replacement_line_items[].fulfillment, replacement_line_items[].name, replacement_line_items[].variant_id
  • POST /v1/return-resolutions/{return_resolution_id}/checkout-sessions: page_origin, payment_return_url, redirects
  • POST /v1/returns/{return_id}/decide: line_items[].decline_reason_message, line_items[].override_reason_message
  • POST /v1/returns/{return_id}/dispositions: return_inspection_line_item_id, return_receipt_line_item_id
  • POST /v1/returns/{return_id}/inspections: source_system.external_source_id
  • POST /v1/returns/{return_id}/process: line_items[].decision.decline_reason_message, line_items[].decision.override_reason_message, line_items[].resolution.gift_card_refund_destination, line_items[].resolution.replacement_line_items[].bundle_id, line_items[].resolution.replacement_line_items[].fulfillment, line_items[].resolution.replacement_line_items[].name, line_items[].resolution.replacement_line_items[].variant_id, receipt.source_system.external_source_id
  • POST /v1/returns/{return_id}/receipts: line_items[].return_line_item_id, line_items[].unverified_item, source_system.external_source_id
  • POST /v1/returns/{return_id}/resolutions: corrects_return_resolution_id, gift_card_refund_destination, line_items, pricing_basis, replacement_line_items, replacement_line_items[].bundle_id, replacement_line_items[].fulfillment, replacement_line_items[].name, replacement_line_items[].variant_id
  • POST /v1/sandboxes: access, scopes, test_key_name
  • POST /v1/sandboxes/{sandbox_id}/api-keys: scopes
  • POST /v1/shipments/{shipment_id}/packages: buyer_notification_behavior, return_line_items, shipped_at
  • POST /v1/subscription-plans: images[].file_id, images[].source_url, line_items[].bundle_id, line_items[].description, line_items[].modifiers[].modifier_id, line_items[].modifiers[].order_line_item_modifier_id, line_items[].modifiers[].quantity, line_items[].modifiers[].text, line_items[].name, line_items[].tax, and 2 more
  • PATCH /v1/subscription-plans/{subscription_plan_id}: images[].file_id, images[].source_url, line_items[].bundle_id, line_items[].description, line_items[].modifiers[].modifier_id, line_items[].modifiers[].order_line_item_modifier_id, line_items[].modifiers[].quantity, line_items[].modifiers[].text, line_items[].name, line_items[].tax, and 2 more
  • POST /v1/subscription-previews: delivery_method.configuration, delivery_method.configuration.eligibility.all, delivery_method.configuration.eligibility.any, delivery_method.configuration.eligibility.country, delivery_method.configuration.eligibility.customer_has_email, delivery_method.configuration.eligibility.customer_has_phone, delivery_method.configuration.eligibility.customer_merchant_verified, delivery_method.configuration.eligibility.customer_segment, delivery_method.configuration.eligibility.not, delivery_method.configuration.eligibility.postal_code, and 42 more
  • POST /v1/subscriptions: delivery, promotions[].promotion.promotion_code, promotions[].promotion.promotion_id
  • PATCH /v1/subscriptions/{subscription_id}: billing_interval, billing_interval_count, billing_schedule, cancel_at_period_end, delivery, end_after, external_reference_id, metadata, payment_method_id, quantity, and 1 more
  • POST /v1/subscriptions/{subscription_id}/line-items: bundle_id, variant_id
  • POST /v1/subscriptions/{subscription_id}/promotions: promotion.promotion_code, promotion.promotion_id
  • PATCH /v1/tax-calculation-callbacks/{tax_calculation_callback_id}: configuration, external_reference_id, name, signing_methods, status
  • POST /v1/webhook-endpoints: installed_merchant_modes
  • Breaking change
  • API
  • Delivery
  • Webhooks

Bulk delivery assignment runs after the response#

These changes apply immediately to every supported API version.

  • POST /v1/delivery-profiles/{delivery_profile_id}/assign-to-unconfigured returns 202 Accepted instead of 200 OK. Flint checks the profile and its expected_version in the request, then assigns the profile after responding, usually within seconds. A large catalog takes longer.
  • product_variants_updated and bundle_components_updated are replaced by product_variants_unconfigured and bundle_components_unconfigured: the physical variants and bundle components that had no delivery profile when Flint accepted the request.
  • Until Flint reaches an item, reads show it unchanged: no delivery_profile_id and delivery_configuration_status action_required. To follow progress, list items with delivery_configuration_status=action_required; the count falls as batches commit. Items whose profile isn't active also report action_required and aren't changed.
  • product_variant.updated, product.updated, and bundle.updated for the assignment arrive after the response, in batches of at most 250 variants or bundle components, instead of in the request's own commit.
  • An item that gets a profile from another write first keeps it. A newer assignment takes over from one still running. If the profile stops being active before the assignment finishes, the remaining items stay unconfigured.

See Delivery configuration.

  • Breaking change
  • API
  • Delivery
  • Webhooks

Delivery configuration events follow version, and six unused types are removed#

Delivery profiles, zones, and location sets are only active or archived, so no write ever sent these event types. They are removed:

  • delivery_profile.activated and delivery_profile.deactivated
  • delivery_zone.activated and delivery_zone.deactivated
  • delivery_location_set.activated and delivery_location_set.deactivated

A stored endpoint subscription to one of them is dropped when the endpoint is read. Subscribing to them now returns 400 INVALID_REQUEST.

Flint now compares each delivery profile, zone, location set, method, rate callback, and revocation as its GET returns it before and after a write:

  • Each write sends at most one event for each resource, and only when it advances the resource's version.
  • updated events carry data.previous_attributes with the changed fields' earlier values.
  • Changing a rate callback's signing_methods, or rotate-secret issuing its first secret, still sends one delivery_rate_callback.updated, now with the earlier signing_methods in data.previous_attributes. A PATCH that changes signing_methods with other fields sends one event for the whole request.
  • A PATCH whose values match the stored ones, including a signing_methods set equal to the current one, or a status change to the current status, keeps the version and sends no event. Before, it advanced the version and sent updated, activated, or deactivated again. A PATCH that carries a revision field still publishes a new revision and sends updated.
  • Other writes send the same event types as before, including delivery_revocation.created with the method's or rate callback's updated when a revocation fences its current revision.

What to do: remove the six types from enabled_events, and subscribe to created, updated, and archived for these resources. Use data.previous_attributes to find what changed. See delivery configuration events.

  • Breaking change
  • API
  • Delivery

Delivery configuration PATCH publishes a revision only for revision fields#

Each delivery configuration resource now names its revision fields:

ResourceRevision fields
Profile, zone, or location setconfiguration
Methodconfiguration, name, description, display_position, recommendation_priority
Rate callbackconfiguration, signing_methods

A PATCH publishes a new immutable revision exactly when it carries one of these fields, even when every value matches the current one, and these are the fields that require expected_version. Other fields, such as status, metadata, external_reference_id, and a callback's name, advance version and keep the current revision.

What changed for rate callbacks: a PATCH that carries signing_methods used to advance version without publishing a revision, and sending the current set changed nothing. It now publishes a new revision and sends delivery_rate_callback.updated, like a configuration change. A PATCH with a revision field is how you replace a revoked revision: send the current configuration or signing_methods back unchanged when nothing else needs to change. A PATCH of only non-revision fields keeps delivery_revocation_id set.

Delivery profile, zone, location set, and method metadata now uses the limits every other resource uses, checked on the map after a PATCH merges it: up to 50 pairs, keys of 1 to 256 characters, values of 1 to 4,096 characters, and 32,768 bytes in total. The old limits were keys of at most 64 and values of at most 500 characters. Errors name the failing entry, such as param metadata.order_ref, with the same messages as other resources.

POST /v1/delivery-rate-callbacks accepts an optional status, inactive (the default, as before) or active, so you can create a callback ready for active methods without a second request.

The configuration descriptions now state how a PATCH applies them: a method's or rate callback's configuration is a patch object whose keys, including pricing, origin, and eligibility, are each replaced as a whole, and a profile's, zone's, or location set's configuration is replaced as a whole. configuration: {} returns 400 INVALID_REQUEST with param configuration for every resource, as before.

If you relied on a signing_methods PATCH keeping current_delivery_rate_callback_revision_id, read the new ID from the response. See Change configuration.

  • Breaking change
  • API
  • Delivery
  • Checkout

Delivery quotes move to top-level routes#

Breaking: delivery quotes now live only at /v1/delivery-quotes. Two routes are removed:

RemovedUse instead
POST /v1/checkout-sessions/{checkout_session_id}/delivery-quotes (createCheckoutSessionDeliveryQuote)POST /v1/delivery-quotes (createDeliveryQuote) with checkout_session_id in the body
GET /v1/checkout-sessions/{checkout_session_id}/delivery-quotes/{delivery_quote_id} (getCheckoutSessionDeliveryQuote)GET /v1/delivery-quotes/{delivery_quote_id} (getDeliveryQuote)

The create request is otherwise unchanged: send the same destination_address, buyer_location, pickup_location_id, expected_delivery_selection_id, and merchant-only fields as before, plus the required checkout_session_id. The response, status codes, and errors are the same.

Idempotency changes in two ways:

  • An Idempotency-Key used with the old route doesn't replay on the new one.
  • The key's identity no longer includes the checkout session, because the session isn't in the path. With an API key or partner token, reusing one Idempotency-Key for quotes on two checkout sessions is now a key-reuse error. The old route created two quotes. Use a new key for each session.

The checkout credential can no longer send basis_delivery_quote_id; it returns 400 INVALID_REQUEST, like the other merchant-only fields. A basis quote only completes a pending quote with method_results, which already required merchant authentication.

The checkout credential now works on GET /v1/delivery-quotes/{delivery_quote_id} and GET /v1/delivery-quotes, for its own checkout session only:

  • On create and list, checkout_session_id must be the credential's own session. The list requires it with the checkout credential.
  • A read returns only a quote of the credential's own session.
  • Any other session or quote returns 404 RESOURCE_NOT_FOUND, the same as one that doesn't exist.

API keys, dashboard sessions, and partner tokens keep their access, and read the merchant view as before. See Delivery quotes.

  • Breaking change
  • API
  • Delivery
  • Webhooks

Delivery rate callback requests use public field names#

The requests Flint sends to a delivery rate callback now use the API's public names, and Flint reads responses more strictly. If you run a callback server, update its parsing before these changes reach your requests. The DeliveryRateEvaluationRequest and DeliveryRateEvaluationResponse schemas describe the new shapes.

Request body.

  • key_id is now delivery_rate_callback_signing_key_id, the name the rest of the API uses for the HMAC signing key. It is still an empty string for a JWT-only callback.
  • delivery_quote_version is gone. It was an internal counter that no other part of the API exposes.
  • candidates[].execution_legs[].allocations[].allowed_fulfillment_method_ids is now allowed_delivery_method_ids.
  • candidates[].pricing.bases no longer contains choice_group_merchandise_subtotal or order_merchandise_subtotal. Read choice_group.merchandise_subtotal_before_discounts and order.merchandise_subtotal_before_discounts, which carry the same amounts.
  • A request from a delivery preview sends checkout_session_id: null instead of the string preview.

Response body. An outcome may carry only the fields of its own type, plus merchant_reference. Flint now rejects an outcome with window_selection or window_pricing, which it used to ignore and always derived from offered_windows. It also rejects one with another type's field, such as amount_money on an unavailable outcome. Flint reports a rejected outcome's method as cannot_calculate with callback_result_invalid, and the other methods in the response are unaffected. A refused outcome also counts as an invalid response against the callback's circuit breaker: repeated refusals open the circuit, and then every method on that callback reports callback_circuit_open, so run a test delivery first, which reports invalid_response. Outcome keys are matched exactly, so a case variant such as "Type" is refused.

merchant_reference's 500 limit now counts characters, not bytes, for callback responses and for caller-supplied outcomes on POST /v1/delivery-quotes. A reference of up to 500 multi-byte characters is accepted.

In the OpenAPI document, the callbacks' Authorization header is now the DeliveryRateCallbackBearer security scheme instead of a header parameter.

  • Breaking change
  • API
  • Delivery
  • Webhooks

Delivery rate callback secrets follow signing_methods#

signing_methods now controls a delivery rate callback's shared secret, as it does for webhook endpoints. A PATCH /v1/delivery-rate-callbacks/{delivery_rate_callback_id} that adds hmac to a callback without a secret issues the first one and returns it once in that response. That request used to return 409 ACTION_NOT_ALLOWED with reason secret_not_issued.

POST /v1/delivery-rate-callbacks/{delivery_rate_callback_id}/rotate-secret now only replaces an existing secret. On a callback without hmac it returns 409 ACTION_NOT_ALLOWED with reason secret_not_issued and changes nothing; it used to issue the first secret and add hmac. Its operation ID is now rotateDeliveryRateCallbackSecret, and it returns the whole callback with the new secret instead of a DeliveryRateCallbackSigningKeyRotation. Rotating no longer changes the callback's version.

Create, the first-secret PATCH, and rotate-secret return DeliveryRateCallbackWithSecret: the callback plus secret and delivery_rate_callback_signing_key_id, present only when that response issued a secret. DeliveryRateCallback no longer has key_id or secret. The signing key ID on connection checks and test deliveries is now delivery_rate_callback_signing_key_id instead of key_id. The Flint-Signing-Key-Ids request header is unchanged.

A replay of an idempotent request that issued a secret returns it only to the API key that sent the request. If Flint can't return a first secret, it removes the secret and restores the callback's previous signing methods and URL.

Read the secret from data.secret and the key ID from data.delivery_rate_callback_signing_key_id, add hmac with PATCH instead of rotate-secret, and rename key_id on connection checks and test deliveries. See Change signing methods.

  • Breaking change
  • API
  • Orders
  • Fulfillment

Buyers lose the download link after a full refund#

A buyer kept the download link for a digital fulfillment after you refunded them. Buyer reads now return digital_details.delivery_url as null once the buyer no longer has download access:

  • the order is fully refunded (refund_status is refunded), or
  • every line the fulfillment covers is refunded in full.

A partial refund by amount keeps the link. The change covers every /v1/me response that includes the fulfillment, such as GET /v1/me/orders, GET /v1/me/fulfillments, and the order returned by POST /v1/me/orders/{order_id}/send-receipt or a subscription renewal or plan change. The buyer's account stops offering the download. Other buyer credentials, such as a checkout session reading GET /v1/orders/{order_id}, no longer receive the URL either; there it's omitted. Previously these reads returned the URL for as long as it was set.

Flint decides this when the buyer reads, so the fulfillment's version doesn't change and no event is sent. Your own reads and webhooks still show the URL you set, and the URL itself keeps working. If your download link doesn't expire, end access in your app on order.refunded or order.partially_refunded. See Fulfill and ship orders.

  • API
  • Payments

Stripe Elements guidance lists Flint payment options#

The Stripe Elements guidance in payment_collection and setup_collection now lists payment_options. That covers orders and checkout sessions (including payment link resolution and subscription orders), order payment intents, standalone payment intents' payment_collection, the guidance in error.details[].selectable_resources[]. It uses the same values as payment_options elsewhere in the API, in display order: today card, apple_pay, google_pay, affirm, and ach_debit. The list can grow, so skip values you don't recognize.

Stripe Elements still takes processor payment method types, so map the options when you create Elements: card for card, apple_pay, and google_pay; us_bank_account for ach_debit; and affirm for affirm. Set the Payment Element's wallets option so it shows only the wallets listed; Stripe's default can show a wallet Flint refuses. The server-confirmed payments guide shows both steps.

payment_method_types and digital_wallets are deprecated. They use Stripe's names (us_bank_account) and have no enum. They still carry the same values, and a later release removes them. Read payment_options instead.

  • API
  • Partners
  • Disputes

Embed a merchant's payments and disputes with the payments component#

POST /v1/merchant-account-sessions accepts payments in components. It mounts Stripe Connect's payments element, so a platform can show a merchant's payments and their disputes in its own product, the way it already shows payouts and balances.

  • Dispute responses. The merchant can submit evidence or accept a dispute in the component. Flint records the result from the processor's dispute events, so dispute.* webhooks and GET /v1/disputes stay accurate.
  • No refunds or capture in the component. Those stay on POST /v1/refunds and the PaymentIntent capture and cancel routes, so every refund and capture has a Flint record and updates its order.
  • Scopes. An API key or CLI login needs payments.payment_intents.read and payments.disputes.write besides merchants.account_sessions.write; otherwise the request returns 403 INSUFFICIENT_SCOPE with param naming the component.
  • Merchant credentials only. A partner app install token can't open payments and gets 400 INVALID_REQUEST with detail NOT_ALLOWED. Use the merchant's own API key or CLI login.

See Payments component.

  • Breaking change
  • Subscriptions
  • Promotions
  • Webhooks

Used-up subscription promotions stay listed until the renewal is recorded#

Breaking: when a renewal payment uses up a subscription promotion, it now stays in the subscription's promotions until the renewal is recorded. This applies to a once promotion and to the last cycle of a repeating one. The promotion leaves promotions in the same change that advances completed_cycles, which also advances version and sends that change's subscription event. Before, it could leave the list later, with no new version and no event.

Discounts aren't affected: a used-up promotion never discounts another charge.

  • Breaking change
  • API
  • Refunds

Refunds say who initiated them#

Every refund now has initiated_by. It's merchant for every refund you or your integration asks for, including refunds from Returns, credit notes, order edits, and declined payment reviews. It's flint when Flint refunds a payment on its own because it captured money it can't apply to the order, for example a card charge that went through after Flint had reported the payment as failed. Both values are read-only, and the vocabulary is extensible.

Refunds also have pending_reason. manual_review means a pending refund is waiting while Flint's team checks it before the money goes back, and nothing is needed from you. It's null otherwise.

Breaking: refunds Flint makes on its own change in three ways.

  • reason is payment_returned instead of other. Only Flint sets it: requests that send payment_returned get 400 INVALID_REQUEST with an INVALID_VALUE detail. GET /v1/refunds?reason=payment_returned lists these refunds.
  • order_id names the order the payment was for, where it used to be absent. The refund appears in the order's refund_ids and in GET /v1/refunds?order_id=, but the order never received the money, so it doesn't count toward the order's refund_status, refunded amounts, or refundable money.
  • initiated_by is flint.

If you count an order's refunds from GET /v1/refunds?order_id= or refund_ids, skip refunds with reason payment_returned, or read the order's refund_status and refunded amounts instead. Buyers reading their refunds see reason: payment_returned on these refunds; every other reason stays null for buyers. Refunds Flint creates has the details.

  • Breaking change
  • API
  • Webhooks
  • Inventory

Inventory events arrive once per change, with previous values#

Previously, inventory events were recorded as each row was written. A change that raised a level's shortage sent both inventory_level.updated and inventory_level.shortage_detected, and a change that wrote one level more than once, such as releasing held and committed quantity together, sent an inventory_level.updated for each write.

Now Flint compares each level, reservation, count, transfer, and receipt as its GET returns it before and after an inventory command, such as an adjustment, a reservation commit, or a transfer step:

  • Each resource sends at most one event of each type per command, carrying the resource as the command left it. A return request that restocks several lines into one level sends one level update.
  • A command that raises a level's shortage_quantity sends only inventory_level.shortage_detected, with the level's new quantities. Other level changes still send inventory_level.updated.
  • inventory_level.updated and the reservation, count, and transfer change events carry data.previous_attributes with the changed fields' earlier values. A level's first stock at a Location has none, and neither does an inventory_reservation.at_risk sent without another change to the reservation.
  • The event types are otherwise the same: each reservation commit, consumption, release, expiry, and action requirement, and each transfer departure, receipt, return, and loss, still sends its event.
  • A replayed request sends nothing.

What to do: treat inventory_level.shortage_detected as a level update too, and keep the copy with the higher version. Deduplicate by event ID. See inventory events.

  • Breaking change
  • API
  • Webhooks
  • Inventory

Inventory reservations, counts, and transfers send updated events#

Some inventory changes advanced a resource's version without sending an event. They now send a new updated event for every supported API version, with data.previous_attributes holding the changed fields as they were:

  • inventory_reservation.updated fires when a reservation you created gets a new expires_at, or when Flint clears its inventory_action_required because the requirement was resolved. Reservations Flint holds for orders and checkout still send no reservation events; their order's events cover them.
  • inventory_count.updated fires when you save a draft count's observations.
  • inventory_transfer.updated fires when a PATCH changes a transfer's note, external_reference_id, or lines, and when cancel reduces a transfer's quantities but leaves it open. A cancel that closes the transfer still sends inventory_transfer.closed.

A deadline, count observation, or transfer PATCH that changes nothing now keeps the resource's version and updated_at and sends no event. Before, these requests advanced version anyway.

Creating a count or transfer, and canceling a count, still send no event. Partner apps with commerce.inventory.read receive the new events for their installed merchants.

See inventory events in the webhook events catalog.

  • Breaking change
  • API
  • Invoices
  • Checkout
  • Customer-accounts

Invoice checkout moves to POST /v1/checkout-sessions#

Breaking: an invoice's checkout session is now created with the other checkout sessions, and the response is the checkout session itself. Two routes are removed:

RemovedUse instead
POST /v1/invoices/{invoice_id}/checkout-sessions (createInvoiceCheckoutSession)POST /v1/checkout-sessions (createCheckoutSession) with type: invoice and invoice_id
POST /v1/me/invoices/{invoice_id}/checkout-sessions (createMeInvoiceCheckoutSession)POST /v1/me/checkout-sessions (createMeCheckoutSession) with type: invoice and invoice_id
cURL
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "invoice", "invoice_id": "inv_1kmn0aExample"}'

The body is now required, because it names the invoice. Besides type and invoice_id, it takes the same fields as before: invoice_schedule_entry_id, surface, redirects, payment_return_url, page_origin, and return_url. Any other create field, such as order_id or metadata, returns 400 INVALID_REQUEST with an UNKNOWN_FIELD detail naming the field.

The response changed. data is the checkout session, as for every other checkout session create: url for a hosted session, checkout_auth_token for a headless one. The invoice, invoice_payment_attempt, and nested checkout_session members are gone. Read the invoice with GET /v1/invoices/{invoice_id} (or GET /v1/me/invoices/{invoice_id}) and its attempts with GET /v1/invoices/{invoice_id}/payment-attempts. The InvoiceCheckoutSessionRequest, InvoiceCheckoutSessionResponse, InvoiceCheckoutSessionResult, and buyer copies of those schemas are removed.

The rest of the behavior is unchanged:

  • 201 when Flint creates the session and 200 when it reuses the open one.
  • The same refusals, such as 409 OPERATION_IN_PROGRESS while earlier payment work resolves.
  • An Idempotency-Key used on the old route still finds its record on the new one for the same invoice and fields. A retry of a request first sent before this change can replay the original response body, with its old members.
  • Each type keeps its own idempotency records, as the separate routes did. If you reuse one Idempotency-Key for an invoice create and a create of another type, Flint runs both requests and doesn't return IDEMPOTENCY_KEY_REUSED. Use a new key for each checkout you create.

Scopes: type: invoice needs commerce.invoices.write, as the old route did. A key or partner token without it gets 403 INSUFFICIENT_SCOPE with param: type.

POST /v1/me/checkout-sessions takes a customer session, or an invoice's access token for that invoice only. An invalid, expired, or revoked token returns 401 INVALID_CREDENTIAL, as on GET /v1/me/invoices/{invoice_id}. A valid token with an invoice_id it doesn't open returns 404 RESOURCE_NOT_FOUND on invoice_id, the same as an invoice that doesn't exist. See Invoicing.

  • Payments
  • Orders

Charge a saved card while the customer is away#

You can now charge a saved card for a no-show fee, damages, or a top-up without the customer present, and without issuing an invoice for each charge:

  • POST /v1/orders/{order_id}/pay with action: "pay" accepts payment_source.customer_presence, and POST /v1/payment-intents/{payment_intent_id}/confirm accepts customer_presence, both with credential_type: "payment_method" only. Values are present, the default, and absent.
  • With absent, Flint confirms the charge as merchant-initiated on the card's stored credential, so the bank can approve it without asking the customer to authenticate. If the bank still requires authentication, the payment ends requires_payment_method with last_payment_error.code authentication_required, never requires_action.
  • absent needs an API key or partner token and an active card with usage: "off_session". A card the buyer saved in checkout returns 409 ACTION_NOT_ALLOWED with the new reason payment_method_not_reusable. Sending customer_presence on another credential_type, or absent from the checkout credential, returns 400 INVALID_REQUEST with detail code NOT_ALLOWED.
  • PaymentIntent.customer_presence is new, read-only, and always present. It reports the latest confirmation: absent for these charges, subscription renewals, and automatic invoice charges, and present when the customer pays, including with a card they enter on one of those payments. Webhook payloads carry it as GET returns it.

See When the customer is not there.

  • API
  • Payments
  • Subscriptions

Payment failures name never-retry and outdated-card declines#

last_payment_error.code and the other payment failure codes have two new values:

CodeMeaningNext step
card_declined_do_not_retryThe issuer said not to charge this card again. Stripe reports these as stop_payment_order, revocation_of_authorization, revocation_of_all_authorizations, pickup_card, and do_not_try_again, which the networks forbid retrying.Don't charge this card again. For recurring charges, get new authorization from the buyer and use a different payment method.
card_details_outdatedThe card's details have changed, for example a new number or expiry date. Stripe reports this as new_account_information_available.Ask the buyer to update their card details, then try again.

These declines used to be card_declined and payment_failed, so a client that retried them risked the networks' excessive-retry fees. Flint maps only these Stripe decline codes. A Visa category 1 or Mastercard advice code 03 or 21 decline that Stripe reports under another code, such as generic_decline, still arrives as card_declined.

Buyer credentials, such as a checkout session or a customer session on /v1/me, read card_declined_do_not_retry as card_declined, like lost_card, because it includes pickup_card. card_details_outdated reaches buyers as is, with a message asking them to update their card.

Subscription dunning treats both codes like expired_card, as a permanent decline: no more automatic retries against that card. Flint sends subscription.dunning_exhausted right away with the subscription still past_due, and the buyer gets the payment-failed email with its update link. A payment retry with a new card recovers the subscription. If none succeeds by the time the retry window closes, the dunning end action runs. No new subscription events: payment_intent.payment_failed and last_payment_error.code carry the codes.

The payment failure code vocabulary is extensible, so treat an unknown code like payment_failed.

  • Breaking change
  • API
  • Onboarding
  • Sandboxes
  • Api-keys

Sandbox and onboarding keys come from POST /v1/api-keys#

These changes apply immediately to every supported API version.

Removed routes#

  • POST /v1/onboarding/api-key (createOnboardingAPIKey) and POST /v1/sandboxes/{sandbox_id}/api-keys (createSandboxAPIKey) are removed and return 404 ROUTE_NOT_FOUND.
  • POST /v1/api-keys creates every key. It takes an optional sandbox_id, the sandbox's public ID:
    • A live key, a live CLI login, or a Dashboard session sends sandbox_id to create a test key bound to that sandbox, and omits it for a live key.
    • A sandbox-bound credential, such as a test key, creates keys only in its own sandbox. It may omit sandbox_id or send its own; any other sandbox returns 404 RESOURCE_NOT_FOUND with param sandbox_id.
    • An onboarding session token is now accepted, and must send sandbox_id. Its first key goes to default_sandbox_id; like a Dashboard session, it can name any of the merchant's active sandboxes.
    • name and access stay required, and expires_at stays optional.
  • The starter scope set is gone. Send access explicitly; for the first sandbox key, agents should send full. Granting full, read_only, or a step-up scope from an onboarding session needs a fresh verification, as before.
  • POST /v1/sandboxes with issue_test_key: true gains test_key_expires_at, an optional future RFC 3339 time, allowed only with issue_test_key.

Removed fields and values#

  • can_issue_api_key is removed from the POST /v1/onboarding/verify-email result and from GET /v1/onboarding/state.
  • The readiness action create_api_key is removed. Onboarding state never asks for a key, and status: complete no longer depends on whether the merchant has one.
  • The response warning api_key_scopes_reduced and its removed_scopes field are removed.
  • The OpenAPI extension x-flint-cli-bootstrap-scopes is removed. x-flint-cli-allowed-scopes lists the scopes a CLI login may request.

Added#

  • fresh_verification_expires_at on the verify-email result: the last instant the session can grant full or read_only access or a step-up scope, 5 minutes after verification.

Verify-email refusals#

  • An existing account with two-step verification is refused after the code matches: 409 ALREADY_EXISTS with reason dashboard_sign_in_required, no session, and the verification token used up. The existing refusals for an unverified matching address and for an email linked to another sign-in use the same reason. Sign in to the Dashboard, or run flint login.

Migrate#

  1. Replace POST /v1/onboarding/api-key with POST /v1/api-keys, sending the onboarding session token and {"name": "...", "access": "full", "sandbox_id": "<default_sandbox_id from verify-email>"}, before fresh_verification_expires_at.
  2. Replace POST /v1/sandboxes/{sandbox_id}/api-keys with POST /v1/api-keys, moving the path's sandbox ID into the body's sandbox_id.
  3. Stop reading can_issue_api_key and the create_api_key next step. Read default_sandbox_id and fresh_verification_expires_at from verify-email instead.
  4. Handle 409 ALREADY_EXISTS with reason dashboard_sign_in_required on verify-email by sending the user to the Dashboard or flint login.

See Issue the first sandbox key and Issue a key for an existing sandbox.

  • Breaking change
  • API
  • Orders

Order activity deltas follow the balance#

balance_delta_money on an order activity is now exactly how far the row moved running_balance_money, the order's signed balance (outstanding_money minus overpaid_money): the row's running balance minus the balance before it.

  • Refund rows usually carry 0, because returning collected money doesn't change what is owed. Previously they carried the refunded amount as a positive delta that the running balance never showed. A refund of an overpayment carries the change it made to the balance. Read the refund in refund_id for the amount; the row's description also names it, as in "Refund of USD 20.00 created". If a refund of an overpayment then fails, an adjustment row carries the balance it restores, as in "Balance restored after refund of USD 20.00 failed", and the refund_failed row carries 0.
  • Payment rows carry the change to the balance. That is still the amount collected plus any debt a final capture discharged, except where the balance moves by a different amount, for example less when part of the order was written off. Read the PaymentIntent in payment_intent_id for the amount collected.
  • payment_failed rows are now written. A failed payment attempt, or the failed part of a split payment, adds one row with a delta of 0, whatever retries or replays follow. payment_intent_id names the declined payment when exactly one card payment declined. Canceled and expired attempts add no row.

Descriptions now format money with its currency, as in "Requested tip set: USD 5.00", instead of raw minor units.

If you showed a refund's amount from balance_delta_money, read it from the refund instead. See Order activities.

  • API
  • Orders
  • Refunds

Order edit previews can add and replace items#

Order edit previews now take add_line_items, in the same shape as POST /v1/orders/{order_id}/line-items. To swap a size before shipping, remove the old units and add the new variant in one preview. Send remove_line_items, add_line_items, or both.

Added lines are priced from the catalog, price list, or customer price, without evaluating promotions again, and taxed through the order's tax settings. Tax already committed on the order doesn't change. Only lines Flint can fulfill can be added: variant, bundle, and custom lines with a delivery requirement. Gift cards, subscribe-and-save lines, and lines with fulfillment requirement none return 400 INVALID_REQUEST with detail NOT_ALLOWED. Stock that can't cover an added line returns 409 INVENTORY_INSUFFICIENT at that add_line_items[i]; variants that allow backorders can still be added.

The removed value and released charges pay for the added lines first, and the rest is refunded. Each preview reports add_line_items with their prices and tax, added_total_money, and amount_due_money, what the added lines cost beyond the credit. Added variant lines include product_id beside variant_id; bundle and custom lines omit it. Committing an edit that adds lines isn't available yet.

  • API
  • Orders
  • Refunds

Orders report the value edits removed#

An order's settlement_amounts now include removed_money: the value order edits took off the order, which it no longer owes. It adds each removed unit's value and each edit's charge_refunds[].amount_money. It isn't collected money, so paid_money and refunded_money don't change, and outstanding_money is now the total minus paid, written-off, released, and removed money, never below zero. It also appears on buyer reads and orders in webhook payloads, and is 0 on orders with no edits.

Order edits and order edit previews report the value of what they remove separately from the refund:

  • Each remove_line_items[] entry gains total_money, the value of the removed units. refund_money is the part refunded to the buyer.
  • Each charge_refunds[] entry gains refund_money, the part of the released amount_money refunded to the buyer.
  • The edit and the preview gain removed_total_money, the sum of the removals' total_money.

Today an edit refunds everything it removes, so each pair is equal. Edits recorded before this change report the same values.

  • Breaking change
  • API
  • Partners
  • Webhooks

Partner apps can declare payment splits#

A marketplace that collects payments as the seller of record will be able to send splits of each payment to its sellers: merchants that installed its partner app and approved receiving split funds from it. No request accepts splits yet; this release covers the app's declaration, the sellers' approval, and the platform capability.

  • PartnerApp.payment_splits. Set it on POST /v1/partner-apps or PATCH /v1/partner-apps/{partner_app_id} with seller_terms_url, the marketplace's terms for sellers, an HTTPS URL of at most 2,048 characters. A write replaces the whole declaration, and null removes it. Declaring it doesn't need platform approval.
  • Breaking: expected_version with payment_splits. A PATCH that sends payment_splits must also send expected_version, or it returns 400 INVALID_REQUEST with detail REQUIRED at expected_version. Requests without payment_splits are unchanged.
  • Consent and grants. GET /v1/oauth/authorize/preview returns the app's payment_splits, and every authorization of an app that declares it asks the merchant to approve receiving split funds: the consent screen shows the seller terms beside the permissions. PartnerEnvironmentGrant.payment_splits records the approval for that mode: the seller_terms_url approved and approved_at. Changing seller_terms_url leaves approved grants on the terms they approved. Removing payment_splits, or revoking the grant or install, ends the approval.
  • Platform capability. platform.capabilities gains payment_splits, which live splits will need. Declaring payment_splits requests it, so an approved platform reads limited, with payment_splits not_approved, until Flint approves it. A platform that doesn't declare it keeps its status.
  • Events. A declaration change sends partner_app.updated, or partner_app.platform_limited or partner_app.platform_approved when declaring or removing it changes the platform's status. A grant whose approval changes at a code exchange, or ends when you remove payment_splits, sends partner_app_install.updated and partner_app_install.permissions_updated.
  • Error reasons. payment_split_consent_required joins the 409 ACTION_NOT_ALLOWED reasons for a split to a seller that hasn't approved receiving split funds in that mode. No request returns it until splits are accepted. The next_steps for platform_onboarding_required, platform_pending_review, platform_rejected, platform_capability_inactive, and capability_unavailable now point at the refused capability named in capability.

See Declare payment splits.

  • API
  • Partners

Partner apps show the current platform terms version#

Your app no longer needs to hard-code the platform terms version it accepts.

  • PartnerApp.platform.current_terms. platform_terms_version is the version POST /v1/partner-apps/{partner_app_id}/accept-platform-terms accepts now. Send it as platform_terms_version. Compare it with terms_acceptance.platform_terms_version to see whether your app has accepted it.
  • url. Where Flint publishes that version's text. It's null while the version is a placeholder, as 2026-11-01 is today.
  • acceptance_due_at. When Flint announces a new version, the date accepting it becomes required. Until then your earlier acceptance keeps the platform_terms requirement met. It's absent when the current version is already required.

partner_app webhook objects carry the same field. See Accept the platform terms.

  • Breaking change
  • API
  • Partners
  • Webhooks

Partner apps can set a platform fee cap#

A partner app can now declare the most a platform fee can take from one payment it creates with a partner app token. No request accepts a platform fee yet; this release covers the cap and the merchant's approval of it.

  • PartnerApp.platform_fee_cap. Set it on POST /v1/partner-apps or PATCH /v1/partner-apps/{partner_app_id}: percent, above 0 and at most 25, and maximum_fee_currency_options, the maximum fee per payment in USD. A write replaces the whole cap, and null removes it. Setting it doesn't need platform approval.
  • Breaking: expected_version with platform_fee_cap. A PATCH that sends platform_fee_cap must also send expected_version, or it returns 400 INVALID_REQUEST with detail REQUIRED at expected_version. Requests without platform_fee_cap are unchanged.
  • Consent and grants. GET /v1/oauth/authorize/preview returns the app's platform_fee_cap, the consent screen shows it, and installing approves it for that mode. PartnerEnvironmentGrant.platform_fee_cap is the cap the merchant approved. Lowering the app's cap lowers every grant at once; raising it changes no grant until the merchant authorizes again.
  • Events. A cap change sends partner_app.updated. A grant whose approved cap changes sends partner_app_install.updated and partner_app_install.permissions_updated.
  • Error reason. platform_fee_consent_required joins the 409 ACTION_NOT_ALLOWED reasons for a platform fee in a currency the merchant hasn't approved a cap for. No request returns it until platform fees can be charged.

See Set a platform fee cap.

  • API
  • Partners
  • Webhooks

Partner apps can complete platform onboarding#

A partner app can now go through Flint's platform review from the API. Approval turns on platform capabilities, such as live onboarding through an install.

  • PartnerApp.platform. Every app shows platform.status (not_started, pending_review, approved, limited, or rejected), the requirements still outstanding, each platform capability with its status and inactive_reason, and terms_acceptance. Once Flint approves or limits the app, limits and reserve show the terms Flint set, and limits.usage shows current usage. Usage changes don't change version or send events.
  • platform_profile. Describe the platform on POST /v1/partner-apps or PATCH /v1/partner-apps/{partner_app_id}. A write replaces the whole profile. Estimates use estimated_* names and USD.
  • POST /v1/partner-apps/{partner_app_id}/accept-platform-terms. Records the credential's acceptance of the current platform terms version. PartnerApp.supported_actions lists accept_platform_terms while that version isn't accepted. Version 2026-11-01 is a placeholder while Flint finishes writing the terms.
  • partner_app webhook events. partner_app.updated, partner_app.platform_approved, partner_app.platform_limited, and partner_app.platform_rejected go to the owning merchant's own live endpoints. Every change that advances the app's version sends one, including edits and deleting the app. A secret rotation never includes the secret.
  • Refusal reasons. In live mode, a partner app token that uses an inactive platform capability gets 409 ACTION_NOT_ALLOWED with a reason that follows the app's platform status: platform_onboarding_required, platform_pending_review, platform_rejected, or platform_capability_inactive. The next_steps for platform_onboarding_required and platform_capability_inactive now point to the app's platform object.

Test mode never checks platform capabilities, and ordinary installs and payments don't depend on them. See Become an approved platform.

  • API
  • Partners
  • Security

Partner app tokens read your app's installs and revoke them#

Your backend can now track and end installs with the same partner app token it uses for the rest of your API traffic, instead of keeping your account's live API key for it.

Your app's routes accept partner app tokens#

A live partner app token can call five routes for its own app:

  • GET /v1/partner-apps/{partner_app_id}
  • GET /v1/partner-apps/{partner_app_id}/installs
  • GET /v1/partner-apps/{partner_app_id}/installs/{partner_app_install_id}
  • POST /v1/partner-apps/{partner_app_id}/installs/{partner_app_install_id}/revoke
  • POST /v1/partner-apps/{partner_app_id}/installs/{partner_app_install_id}/environment-grants/{environment_grant_id}/revoke

On these routes the token acts for your app, not for a merchant:

  • A test token returns 403 FORBIDDEN with reason live_mode_required, because installs are shared by live mode and every sandbox. A live token can revoke a test grant.
  • Flint-Merchant-Id and Flint-Sandbox-Id return 400 INVALID_REQUEST with detail NOT_ALLOWED. Filter installs with merchant_id instead.
  • Another app's IDs return the same 404 as unknown IDs. A merchant-bound token sees and revokes only its merchant's install.
  • A revoke records revoked_by partner_app with revoked_by_user_id null, and sends the same environment_grant.revoked and partner_app_install.revoked events as a revoke with your key.
  • Idempotency-Key values on the revoke routes are scoped to your app and, for a merchant-bound token, its merchant, so a retry with a newly minted token replays, and your own key never shares them.
  • Requests run as your account in live mode. Request logs list them under your account with the new caller type partner_app, which caller_type also filters on.
  • x-flint-partner-access is platform_scoped on these operations.

Every other partner app route still returns 401 INVALID_CREDENTIAL with reason wrong_credential_type for a partner app token, including changing or deleting the app, its credentials, and its secret.

Limit a credential to test mode#

Partner app credentials have modes, the modes they can mint partner app tokens for. Send "modes": ["test"] when you create a credential for a staging or CI deployment. A live mint or live code exchange with it returns 400 with error unauthorized_client, and the code stays usable with another credential. Credentials created without modes, including every existing one, have ["live", "test"].

See Track installs and Register a credential.

  • Breaking change
  • API
  • Partners
  • Webhooks
  • Security

Partner event reads follow the resource routes#

GET /v1/webhook-events/{webhook_event_id} returns data to a partner install token only when a route that reads the event's resource accepts the same token. Before this change, the event log checked only the resource's read scope, so a token with webhooks.read and customers.read could read customer deletion request snapshots, although the deletion request routes refuse install tokens.

Customer deletion request events now come back to install tokens without data. The event keeps its metadata, including event_type, resource_type, and resource_id. Delivery attempt reads also omit response_headers, response_body_excerpt, and response_content_type for these events, because a receiver can echo the payload in them.

This matches the rule for events forwarded to installed-merchant endpoints. Merchant API keys are unchanged: customers.read still reads deletion request snapshots.

  • Breaking change
  • Webhooks
  • Partners

Partner install events are sent with the change#

Flint now records your app's lifecycle events in the same transaction as the install or grant change. An exchange, revoke, or narrowing that succeeds always sends its events, and a retry of a failed delivery sends the same event ID. The event types and envelopes are unchanged.

  • Breaking: one install event per change. A change to an install sends partner_app_install.permissions_updated when a grant's permissions or approved platform fee cap changed, partner_app_install.revoked when the install was revoked, and partner_app_install.updated otherwise. permissions_updated no longer arrives with updated, and the first exchange sends only partner_app_install.created and environment_grant.created.
  • Breaking: revoking one grant. Revoking a grant while the install keeps another active grant sends environment_grant.revoked and partner_app_install.updated, since the install's environment_grants changed. Revoking a grant still in pending_exchange on an active install sends partner_app_install.updated for the same reason, and no grant event.
  • Installs awaiting their exchange. As before, authorizing sends no event, including authorizing again or adding a mode, the exchange sends partner_app_install.created, and revoking an install before its exchange sends none. A change while it waits, such as narrowing, sends partner_app_install.permissions_updated like any other change.
  • Pending grants show their request. A grant in pending_exchange now lists the permissions the merchant is approving in granted_permissions, beside the granted_scopes they require, and the platform_fee_cap the consent shows. A grant's updated_at no longer moves when the merchant consents again to the same permissions.
  • Changes a grant doesn't show. A change that leaves everything a grant's GET shows unchanged sends no install event and keeps the grant's updated_at. That includes a change to only the fixed part of a platform fee cap, which grants don't show yet; it will send partner_app_install.permissions_updated once they do. Before this release, narrowing the fixed part sent partner_app_install.updated and partner_app_install.permissions_updated.
  • Previous values. partner_app_install.updated and partner_app_install.permissions_updated carry data.previous_attributes, like other change events.

See Receive webhooks.

  • API
  • Partners

Partner app install lists show each merchant's readiness#

A platform no longer needs a request per merchant to see who can take payments.

  • merchant_readiness on environment grants. When the app's owner calls GET /v1/partner-apps/{partner_app_id}/installs or GET /v1/partner-apps/{partner_app_id}/installs/{partner_app_install_id}, each active grant that holds merchants.profile.read or merchants.profile.write, within the app's allowed_scopes, has merchant_readiness. It has payments and payouts, each with the status and status_reason from the merchant's readiness, plus blocking_requirement_count and observed_at.
  • Same view as a partner app token. The summary describes the merchant in the grant's mode and sandbox, and appears only where a partner app token in that mode could read GET /v1/merchant for the merchant: the app, install, grant, merchant, and environment are active. The installing merchant's own install reads, revoke results, and webhook events don't include it.
  • Requirement names stay on the merchant. Read GET /v1/merchant with a partner app token in the grant's mode, naming the merchant, for the due requirements and the merchant account session to create.

See See which merchants can take payments.

  • API
  • Partners
  • Settings
  • Custom-domains

Partner app installs can brand checkout and set custom domains#

A platform can now white-label each merchant's checkout from inside its product with the install token, without asking for a separate merchant key.

  • New installable scopes. A permission manifest can request settings.read, settings.write, and merchants.profile.write.
  • Settings. An install token reads GET /v1/settings and GET /v1/settings/effective, and changes branding, legal links, and the checkout, customer account, and invoice presentation defaults with PATCH /v1/settings.
  • Merchant profile. With a live grant, PATCH /v1/merchant changes business_name, logo, and icon. The same token can upload merchant_logo and merchant_icon files.
  • Custom domains. An install token creates, validates, lists, reads, and archives checkout and customer account hostnames in its grant's environment, under the rules an API key follows.
  • What stays with the merchant. In settings: payments.statement_descriptor, tax_identity, tax, payment_limits, checkout.enabled_payment_options, inventory.origin_policies, the subscription billing and dunning fields, customer_account.buyer_capabilities, invoices.payment_policy, invoices.remit_to_address, invoices.default_collection_mode, invoices.default_invoice_payment_term_id, and invoices.autopay_retry_policy, and null for a section that holds one. On the merchant: email, phone, address, the support contact, website_url, timezone, api_version, and metadata. An install token that sends one gets 400 INVALID_REQUEST with a NOT_ALLOWED detail per field and param naming it, and nothing is saved. Tax configuration, payment method domains, and the custom domain add-on keep refusing install tokens with 401 INVALID_CREDENTIAL and reason wrong_credential_type.

Each token acts only in its grant's merchant and environment. Revoking the install or grant, or removing the permission, ends access on the next request. Custom domain events still go only to the merchant's own webhook endpoints. See Brand checkout and set custom domains.

  • API
  • Partners
  • Payouts
  • Disputes

Partner app installs can read balances and payouts and answer disputes#

A platform can now show each merchant its money and handle its chargebacks with the install token, without asking for a separate merchant key.

  • New installable scopes. A permission manifest can request money_movement.balances.read, money_movement.balance_transactions.read, money_movement.payouts.read, money_movement.payout_settings.read, payments.disputes.read, and payments.disputes.write.
  • Money reads. With those scopes, an install token reads GET /v1/balances, GET /v1/balance-transactions and each balance transaction, GET /v1/payouts and each payout, GET /v1/payout-settings, and GET /v1/payout-destinations and each destination. Responses match what an API key with the same scope gets: a payout destination shows bank_name, country, and the masked last4.
  • Disputes. An install token lists and reads disputes, accepts them with POST /v1/disputes/{dispute_id}/accept, and opens POST /v1/disputes/{dispute_id}/response-sessions for Stripe's dispute component. In test mode it can also call POST /v1/disputes/{dispute_id}/simulate; a live token gets 403 FORBIDDEN with reason test_mode_required.
  • Moving money stays with the merchant. POST /v1/payouts, POST /v1/payouts/{payout_id}/cancel, PATCH /v1/payout-settings, and changes to payout destinations still return 401 INVALID_CREDENTIAL with reason wrong_credential_type for an install token. An app can't request money_movement.payouts.write or money_movement.payout_settings.write. The balances and payouts account session components stay closed to install tokens, because they also change bank details and the payout schedule.

Each token acts only in its grant's merchant and environment. Revoking the install or grant, or removing the permission, ends access on the next request. Before you return a response session's client secret to a browser, your backend must authenticate the person and confirm they may handle the merchant's disputes.

Dispute, payout, and balance events reach your installed-merchant endpoint under the same read scopes. See Read money and answer disputes.

  • API
  • Webhooks
  • Partners
  • Disputes
  • Payouts

Partner apps can receive dispute, payout, and balance events#

Endpoints with the installed_merchants event source can now subscribe to dispute and money movement events. A platform learns that an installed merchant has a chargeback to answer, or that a payout failed, without polling each install.

Flint forwards each event only while the install's grant for that mode holds the scope that reads the event's resource:

EventsScope
dispute.created, .updated, .needs_response, .inquiry_closed, .won, .lost, and .preventedpayments.disputes.read or payments.disputes.write
payout.created, .updated, .succeeded, .failed, .canceled, and .reversedmoney_movement.payouts.read
payout_destination.created, .updated, .disabled, and .archived, and payout_settings.updatedmoney_movement.payout_settings.read
balance.updatedmoney_movement.balances.read
balance_transaction.created and .updatedmoney_movement.balance_transactions.read

data.object is what the matching read route returns to the install token, so a payout destination shows only bank_name, country, and the masked last4. When the merchant removes the permission or revokes the install or grant, Flint stops forwarding, and deliveries already queued are suppressed with suppression_reason scope_missing or authorization_revoked.

GET /v1/webhook-event-types lists installed_merchants in event_sources for these types, and their OpenAPI webhooks entries add the installed-merchants variant. Name each event in enabled_events, because ["*"] isn't available with installed_merchants.

merchant_billing_balance.* and merchant_billing_invoice.* events still go only to the merchant's own endpoints. A merchant billing collection is a balance transaction, so it arrives as balance_transaction.created under money_movement.balance_transactions.read. See Read money and answer disputes and Installed-merchant events.

  • Breaking change
  • API
  • Payments
  • Payouts
  • Errors

Temporary Flint faults during payment checks are retryable#

Before a payment or payout proceeds, Flint checks that it has enabled the action for the merchant's environment and verified the processor account. When a temporary fault on Flint's side stops that check from completing, the request now returns a retryable error with retry same_request and error_source: flint:

  • Payment requests return 503 PAYMENT_PROCESSING_UNAVAILABLE.
  • Creating a payout returns 503 SERVICE_UNAVAILABLE.

Retry the same request with backoff. No merchant changes are needed.

409 MERCHANT_NOT_READY with reason processing_not_enabled now means Flint has definitively not enabled the action for this environment.

Breaking: these temporary faults used to return 409 MERCHANT_NOT_READY with reason processing_not_enabled and retry none, so clients stopped retrying requests that would have succeeded moments later.

  • Breaking change
  • API
  • Payments
  • Errors

Payment failures and refusals use one name per condition#

Concurrent confirm. When another confirmation of the same payment intent is still running, POST /v1/payment-intents/{payment_intent_id}/confirm now always returns 409 OPERATION_IN_PROGRESS with retry same_request. Wait, then resend the same request with the same Idempotency-Key.

Unusable confirmation token. An expired confirmation token, or one another payment intent already used, now returns 409 ACTION_NOT_ALLOWED with reason confirmation_token_unusable on payment intent confirm and order pay. param names the confirmation token field you sent, such as stripe.confirmation_token. The message says whether the token expired or was already used. Create a new confirmation token with Stripe.js and send it. A retry with the same Idempotency-Key still returns the original result.

Recurring ACH. ACH can't collect recurring payments. Every refusal for that rule now has reason recurring_not_supported, the reason other payment options use for it.

Payment failure remediation. last_payment_error.remediation.retry stays none for every payment failure code. next_steps now depends on the code. For example, incorrect_cvc says to re-enter the card details, processing_error says to try again later with the same card, and stolen_card says not to try the card again. On a standalone payment intent, next_actions still names the confirm request to send. The message for payment_method_unavailable, which covers mistyped card numbers and postal codes, now asks the customer to check the details. Buyer credentials keep the neutral next step.

Order payment attempts. A failed attempt whose confirmation Flint refused before reaching the processor, such as a reused or expired confirmation token, now reports status_reason: payment_confirmation_rejected instead of other, and never reports an earlier attempt's decline as its last_payment_error. The descriptions of authorization_canceled and payment_authorization_canceled now say what triggers each.

Breaking: a concurrent confirm used to return 409 ACTION_NOT_ALLOWED with reason in_progress and retry none from one of its two detection points. On the confirm route, reason in_progress now means only that the customer is being deleted. An expired or used confirmation token used to return reason terminal_status, the same reason as a finished payment intent. Reason recurring_ach_not_supported is no longer returned or published.

  • Breaking change
  • API
  • Payments
  • Webhooks

Saved card updates and unconfirmed card failures send events#

Saved payment method webhooks change for every supported API version:

  • payment_method.updated is a new event. It fires when a saved card's details change without a stored status change, such as the new last4, brand, exp_month, and exp_year the card network sends after a bank reissues the card, including for a card that is still pending. data.previous_attributes holds the fields as they were. A card that read as expired and gets a new expiry this way reads as active again, with payment_method.updated rather than payment_method.activated. Before, these updates sent no event.
  • A card a buyer saved with a mobile number in checkout and didn't confirm within 24 hours becomes failed and now sends payment_method.failed. Before, it sent no event.
  • A pending card whose setup Flint stops itself now sends payment_method.failed when it becomes failed: for example, when the processor returned a different card for a Flint Wallet save, or the setup completed after Flint could no longer prove it owned the card. Before, it sent no event.
  • Each event is sent in the same commit as the change it reports, with the card as GET /v1/payment-methods/{payment_method_id} returns it. A repeated provider notification still sends nothing.

A payment method's is_default follows its customer's default_payment_method_id. Choosing or clearing a customer's default still sends customer.updated and no payment method event. A card whose expiry date passes reads as expired with no event.

Partner apps with payments.payment_methods.read receive payment_method.updated for their installed merchants.

See Customers and saved payment methods in the webhook events catalog.

  • Breaking change
  • API
  • Payments
  • Refunds

Refunds for payments Flint can't accept#

Sometimes Flint can't accept a payment after it was sent to the processor, for example because the buyer completed it with a payment method other than the one Flint approved. Flint returns that money. Until now, the payment intent looked like a risk block with nothing collected, and nothing public tracked the money on its way back.

Breaking: when Flint returns money for such a payment, through a refund or by releasing the authorization, the payment intent ends canceled with cancellation_reason: "payment_returned", and Flint writes no last_payment_error for it. Before, it was canceled with no cancellation_reason and last_payment_error.code: "payment_blocked". While Flint knows of no money to return, for example while the charge is still processing, the payment intent keeps that shape, then moves to payment_returned and sends payment_intent.updated once Flint finds money to return.

Breaking: the order's payment attempt then fails with status_reason: "payment_returned" and no last_payment_error, where it used to fail with last_payment_error.code: "payment_blocked". An attempt that already failed with payment_blocked changes with its payment intent.

When the payment collected money:

  • captured_money shows the amount collected, and refunded_money counts Flint's refund once the processor accepted it.
  • processing_fee_money and merchant_net_money show the fee charged at capture, once Flint has read it from the charge. Flint returns that fee to your balance separately.
  • Flint creates a refund with initiated_by: "flint", reason: "payment_returned", and the order's order_id, and sends the usual refund.* events. It never counts toward the order's refunds. While Flint's team reviews it, it's pending with pending_reason: "manual_review". If a bank reverses it after it succeeded, it goes back to pending for review instead of failing.
  • The refund balance transaction, any reversal of it, and the adjustment that returns your fee link that refund in related_resource instead of the payment intent.
  • If the buyer wins a dispute on the charge before Flint sends the refund, the refund fails with payment_disputed. Flint still returns its fee to your balance, and the dispute fee is yours.
  • When the refund succeeds, the buyer gets a receipt that says their payment couldn't be applied to the order and was refunded.

An authorization that captured nothing is released: released_money shows it and there's no refund. Attempt legs (PaymentAttemptPaymentIntent, BuyerPaymentAttemptPaymentIntent) gain captured_money, present once nothing more can be collected, so checkout can say whether the buyer was charged.

Branch on cancellation_reason and status_reason, treat a canceled payment intent with payment_blocked as one that can still move to payment_returned, and treat refunds with initiated_by: "flint" as Flint's. Refunds Flint creates has the details.

  • Breaking change
  • API
  • Payouts

Set default payout destinations through the API#

You can now choose each currency's default payout destination through the API.

  • default_payout_destinations on PATCH /v1/payout-settings. Send a map from currency code to payout_destination_id, with expected_version. Each listed destination becomes its currency's default, and currencies you leave out keep theirs. The destination must be active and in that currency. Errors name the entry in param, such as default_payout_destinations.USD: a missing destination returns 404 RESOURCE_NOT_FOUND, an inactive one 409 ACTION_NOT_ALLOWED with reason configuration_required, and one in another currency 400 INVALID_REQUEST with detail NOT_ALLOWED. A default can only be replaced, so null is rejected. Changing a default needs the manage_payout_destinations capability, like the destination routes; without it the request returns 409 MERCHANT_NOT_READY with reason capability_unavailable.
  • Adding a bank account stays in the component. The owner enters bank details in the payouts component, opened with POST /v1/merchant-account-sessions and components: ["payouts"]. Flint never takes account or routing numbers through the API, and the component asks the owner to confirm their identity first.
  • Destination management follows the processor's rules. manage_payout_destinations is ready only when Flint collects the account's requirements, because only then does your payment processor accept bank account changes from Flint. For other accounts, readiness reports it blocked, and PATCH and DELETE on a payout destination, like default changes, return 409 MERCHANT_NOT_READY with reason capability_unavailable; the owner manages bank accounts in the payouts component.
  • Verification is in status. Payout bank accounts have no micro-deposit or other owner verification step. A destination is active once added and verification_required when your processor's checks fail.
  • Merchant credentials only. Partner app tokens still can't change payout settings, choose a default, or open the payouts component.

Spec change: UpdatePayoutSettingsRequest now declares that default_payout_destinations requires expected_version. Earlier releases rejected default_payout_destinations as an unknown field, so no request that worked before behaves differently; only clients that compare the spec's request rules will see the new one. See Choose the default.

  • API
  • Partners
  • Payments

Partner apps can charge platform fees#

Superseded by Create order payments through the payment intents collection.

A partner app can now take a cut of the payments it creates for an installed merchant. The merchant pays the fee beside Flint's fees, Flint takes no share of it, and it never exceeds the platform fee cap the merchant approved.

  • platform_fee on four creates. POST /v1/payment-intents, POST /v1/orders/{order_id}/payment-intents, POST /v1/orders/{order_id}/pay with action: pay, and POST /v1/checkout-sessions of type order or quick_pay take platform_fee.amount_money. Only a partner app token can send it; other credentials get 400 INVALID_REQUEST with NOT_ALLOWED on platform_fee, including on a pay that creates no processor payment.
  • Checks. A fee above the cap for the amount, or not below the amount, returns 400 INVALID_REQUEST with INVALID_VALUE and maximum_money. Without an approved cap in the currency, the request returns 409 ACTION_NOT_ALLOWED with reason platform_fee_consent_required. In live mode, the app's platform_fees capability must be active.
  • PaymentIntent.platform_fee. Shows platform_fee_id, partner_app_id, and amount_money: the fee Flint will charge, lowered at confirm and capture when the cap or Flint's own fees leave less, then the fee it charged. CheckoutSession.platform_fee shows the fee requested. Both are merchant-only.
  • What the merchant nets. merchant_net_money subtracts the platform fee, a payment's balance transaction fee_money includes it, and order settlement fees count it. processing_fee_money stays Flint's fee only. The payments_itemized_v1 report gains a platform_fee_money column at the end, and its merchant_net_money subtracts it.

Live fees need Flint's approval of the app as a platform. Test mode works now. See Platform fees.

  • API
  • Payments
  • Readers

Readers for in-person payments#

Register payment hardware at your locations with the new Readers resource and /v1/readers. A smart_reader is a Stripe Reader S700 that your server drives through Flint, registered with the pairing code it shows. A tap_to_pay reader is a phone that takes Tap to Pay in your app with the Stripe Terminal SDK. A reader can name the device it takes payments for.

  • POST /v1/readers/{reader_id}/connection-sessions gives your app a fresh single-use Stripe Terminal connection token, scoped to the reader's location.
  • In a sandbox, registration_code: simulated-s700 registers a simulated reader. POST /v1/readers/{reader_id}/simulate presents a test card for a payment on that reader, so it becomes useful once card-present payments arrive.
  • The new scopes payments.readers.read and payments.readers.write are part of full access, and partner apps can request them.
  • The new events are reader.created, reader.updated and reader.archived.

A location with active readers can't be archived or given an address that isn't a complete US address, and a device that an active reader names can't be archived. Card-present payments on readers come in a later release.

  • Api-keys
  • Api-request-logs

Request logs name every credential's caller, and API keys filter by creator#

Superseded by Request logs include buyer account and invoice access requests.

GET /v1/api-keys accepts created_by_type and created_by_id. created_by_type takes one or more of api_key, user, and workload_identity. created_by_id takes a key_, usr_, or wid_ ID, and its prefix sets the type, so you can send it alone. A malformed ID returns 400 INVALID_REQUEST on created_by_id. A created_by_type that disagrees with the ID returns 400 INVALID_REQUEST on created_by_id. A user filter matches keys the user created directly, not keys their keys created. Keep both filters unchanged when following next_page_token.

Keys a workload token creates now name its workload identity as created_by, with resource_type workload_identity. Keys a workload token created earlier keep naming the user who set up the workload identity.

Every merchant credential now records a request log caller. Onboarding session requests, reads and writes, are logged with a user caller, like Dashboard writes and CLI logins. Workload identity token exchanges are logged with a workload_identity caller. Request log details now include ip_address and user_agent for workload_identity callers too. Requests made with a customer session or invoice access aren't logged.

See Remove what it created and Debugging.

  • Breaking change
  • API
  • Returns
  • Checkout
  • Customer-accounts

Return balance checkout moves to POST /v1/checkout-sessions#

Breaking: a return resolution's checkout session is now created with the other checkout sessions. Two routes are removed:

RemovedUse instead
POST /v1/return-resolutions/{return_resolution_id}/checkout-sessions (createReturnResolutionCheckoutSession)POST /v1/checkout-sessions (createCheckoutSession) with type: return_resolution and return_resolution_id
POST /v1/me/return-resolutions/{return_resolution_id}/checkout-sessions (createMeReturnResolutionCheckoutSession)POST /v1/me/checkout-sessions (createMeCheckoutSession) with type: return_resolution and return_resolution_id
cURL
curl -X POST https://api.withflintpay.com/v1/checkout-sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-retres_1kmn0a" \
  -d '{
    "type": "return_resolution",
    "return_resolution_id": "retres_1kmn0aExample",
    "return_url": "https://account.example.com/returns/ret_1kmn0aExample"
  }'

The body is now required, because it names the resolution. Besides type and return_resolution_id, it takes the same fields as before: surface, redirects, payment_return_url, page_origin, and return_url. Any other create field, such as order_id or metadata, returns 400 INVALID_REQUEST with an UNKNOWN_FIELD detail naming the field. return_url is accepted only with type: return_resolution.

These match the old routes:

  • 201 when Flint creates the session and 200 when it reuses the open one with the same surface. The response is the checkout session in data, as before.
  • The same refusals, such as 409 ACTION_NOT_ALLOWED when the resolution has no balance to collect, and 404 RESOURCE_NOT_FOUND for an unknown resolution or, on /v1/me, another buyer's.
  • An Idempotency-Key used on the old route replays on the new one when the request names the same resolution with the same fields.

These changed:

  • In live mode, POST /v1/checkout-sessions now adds the merchant's account readiness warnings to meta.warnings, as it does for the other types. They don't change the status or data.
  • Both routes now count as payment routes for rate limits. Live limits are unchanged. In demo mode, each credential gets 1 request per second and 10 per minute, down from 2 and 30.
  • Each type keeps its own idempotency records, as the separate routes did. If you reuse one Idempotency-Key for a return_resolution create and a create of another type, Flint runs both requests and doesn't return IDEMPOTENCY_KEY_REUSED. Use a new key for each checkout you create.

Scopes depend on type. return_resolution needs commerce.returns.resolutions.write, as the old route did. order, quick_pay, and subscription_plan still need checkouts.checkout_sessions.write. A key or partner token holding only one of them can call POST /v1/checkout-sessions, and gets 403 INSUFFICIENT_SCOPE with param: type for a type its scope doesn't cover.

POST /v1/me/checkout-sessions takes a customer session and only type: return_resolution.

The OpenAPI schemas GetOrCreateReturnResolutionCheckoutSessionRequest, GetOrCreateReturnResolutionCheckoutSessionResponse, and BuyerReturnResolutionCheckoutSessionResponse are removed. The requests use CreateCheckoutSessionRequest and the new CreateMeCheckoutSessionRequest, and the responses use CheckoutSessionLaunchResponse and BuyerCheckoutSessionLaunchResponse. See Return resolutions.

  • Breaking change
  • API
  • Sandboxes
  • Webhooks

Resetting a sandbox keeps its ID, keys, and webhook endpoints#

POST /v1/sandboxes/{sandbox_id}/reset now deletes the sandbox's data and keeps the sandbox. It used to archive the sandbox and return a replacement with a new ID.

BeforeNow
Reset responseA replacement sandbox with a new sandbox_id and replaces_sandbox_idThe same sandbox, active, with a new updated_at
Keys bound to the sandbox401 INVALID_CREDENTIAL with reason revokedKeep working, as do workload identities, CLI logins, and connected app installs
Webhook endpointsDeleted with the dataKept, with the same IDs, URLs, events, API versions, and signing secrets
Test payment account, domains, and fee assignmentsPayment account kept; domains left behindAll kept
Retry with a new Idempotency-Key409 ACTION_NOT_ALLOWED with reason archivedResets the sandbox again
Requests during a resetRan against data being deleted409 OPERATION_IN_PROGRESS with reason sandbox_resetting and Retry-After; send the same request again

Sandbox no longer has replaces_sandbox_id or replaced_by_sandbox_id. Sandboxes that earlier resets archived stay readable as ordinary archived sandboxes.

Webhook deliveries and scheduled retries of events from before a reset stop with the new suppression_reason sandbox_reset, and open event streams end with a disconnect frame with reason sandbox_reset.

To update a CI script, delete the steps that follow a reset: looking the sandbox up again, issuing a new test key, and registering the webhook endpoint again. Store the sandbox ID and its test key once. Reset a sandbox lists what a reset keeps and deletes.

  • API
  • Subscriptions
  • Checkout

Name a gift recipient on a subscription#

Subscriptions have a new gift_recipient field: null, or {"email", "name", "message"}, where email is required and message is up to 200 characters. The subscription's customer stays the purchaser, who pays, gets receipts and reminders, and manages the subscription. delivery.recipient stays the ship-to.

  • POST /v1/subscriptions accepts gift_recipient, including for imports.
  • PATCH /v1/subscriptions/{subscription_id} replaces the whole object, and null clears it. expected_version stays optional. Buyers can read the field but not change it.
  • Subscription plans have gifts_enabled, which defaults to false. When it's true, checkout sessions report subscription_terms.gifts_enabled: true and accept subscription_terms.gift_recipient on PATCH /v1/checkout-sessions/{checkout_session_id}. Sessions freeze the setting when they're created. On a plan without gifts, the request fails with 400 INVALID_REQUEST and detail code NOT_ALLOWED.
  • Flint emails the recipient a gift notice when the subscription starts and a final notice when it ends, and sends the gift's shipment notices to delivery.recipient.email, or to gift_recipient.email when the ship-to has none. None of these show prices or payment details, and they follow your customer_email_delivery settings.
  • Flint clears gift_recipient when the subscription is canceled, and when the purchaser's data is erased. The final notice keeps its own copy, and subscription.canceled reports the field as null.

See Gift subscriptions and the Subscriptions reference.

  • Breaking change
  • API
  • Subscriptions

Permanent declines apply the dunning end action when the retry window closes#

A subscription charge declined as expired_card, lost_card, stolen_card, or fraudulent, or failing with authentication_required, still stops automatic retries, and Flint still sends subscription.dunning_exhausted right away with the subscription past_due. Flint now waits for a working card only until the retry window closes: dunning_retry_days after the renewal first failed, the day the last automatic retry would have run. Then it applies your dunning_end_action, or external_dunning_end_action on an external schedule. cancel sends subscription.canceled and pause sends subscription.paused, as when the last retry fails, without a second subscription.dunning_exhausted. notify_only keeps the subscription past_due. Previously, a permanent decline left the subscription past_due with no deadline, whatever the end action. The new decline codes card_declined_do_not_retry and card_details_outdated take the same path.

A permanent decline on a later retry, or a failed payment retry, doesn't extend the window. A payment retry that succeeds before the window closes recovers the subscription, and no end action runs. If billing recovers from an interruption while a retry is scheduled, the window counts from the billing date that failed, missed_billing_at. A subscription already waiting for a new card when billing recovers keeps waiting without a deadline. On a test clock, the window closes in clock time.

Subscriptions that were already waiting after a permanent decline before this change keep waiting for a payment retry with no deadline.

See When a renewal payment fails.

  • Breaking change
  • API
  • Subscriptions
  • Promotions

Preview subscription promotions#

POST /v1/subscription-previews now accepts mode: "promotion_apply" with a required subscription_id and promotion, plus optional first_cycle and replace_promotion_id. It uses the same eligibility and timing rules as apply without saving an attachment or counting a promotion use.

The response includes the proposed promotion and a renewal estimate for its first_cycle. renewal.billing_at is projected for Flint schedules. It is null for external schedules, when a cancellation is scheduled before that cycle, when end_after ends the subscription before that cycle is charged, or while paused with no resume date. Refusals return HTTP errors rather than entries in errors.

This mode requires commerce.subscriptions.read and no Idempotency-Key. It is available through the merchant API. See Preview a promotion.

Integrations that parse POST /v1/subscription-previews responses with a closed list of schemas or mode values must accept SubscriptionPromotionApplyPreview and promotion_apply. They appear only when you request this mode.

  • Webhooks
  • Subscriptions

Subscription events record the change and its previous values#

Events for a change to a subscription now record the subscription at the version the change wrote: its creation, status changes, billing periods and payments, schedule and plan changes, and delivery edits. subscription.dunning_exhausted records the cancellation or pause that ends the retries. Before, Flint read the subscription when it prepared the event, so the payload could include a later change. Notices sent ahead of a date, and a subscription.dunning_exhausted that leaves the subscription past_due, still read it then.

These events also carry data.previous_attributes with the fields the change replaced. subscription.canceled shows the earlier status, and subscription.plan_changed shows the earlier subscription_plan_id or line_items.

During this rollout, a second subscription.created or subscription.activated can arrive for a subscription created while the change deploys. The two copies have different event IDs, so key any provisioning on these events by subscription_id.

See Webhook events.

  • API
  • Tax
  • Checkout
  • Payment-links
  • Subscriptions
  • Settings

Tax hosted checkout, payment links, and subscriptions with your tax calculation callback#

tax on POST /v1/checkout-sessions, POST /v1/payment-links, and PATCH /v1/payment-links/{payment_link_id} takes calculation: {"mode": "automatic"}, or {"mode": "external", "components_source": "callback"} to ask your tax calculation callback for the tax of the order a quick-pay or subscription plan session, or a payment link checkout, creates. Flint creates those orders, so external tax needs components_source callback: leaving it out returns 400 INVALID_REQUEST with detail code REQUIRED, and provided returns INVALID_VALUE. On a payment link update, "calculation": null follows your settings again. Session and payment link reads return the calculation you set. With callback tax and no selected callback, creating the session or opening the link returns 409 ACTION_NOT_ALLOWED with reason configuration_required and resource_type tax_calculation_callback.

Subscriptions add tax, {"enabled": true, "calculation": {"mode": "external", "components_source": "callback"}}, on POST /v1/subscriptions and PATCH /v1/subscriptions/{subscription_id}. It's replaced as a whole, null in a PATCH clears it, and null on reads means the subscription follows your settings. Renewal, setup fee, and plan change orders use it. A subscription that a subscription plan checkout session or payment link creates copies the tax they set. Merchant credentials see it; buyer credentials don't. When the callback can't price a renewal, billing holds it without charging or starting dunning, and tries again after an hour, backing off to once a day. Estimates on a subscription with callback tax return tax_money null and don't call the callback. A paid subscription order's delivery destination change asks the callback about the new destination and is refused only if the tax would change.

tax.default_calculation now applies wherever an order, checkout session, payment link, or subscription sets no calculation of its own. A provided default applies only to orders you create, so checkout session, payment link, and subscription orders use automatic tax under it. Turning on tax.default_enabled, or changing the default while it's on, now needs a selected callback and no tax connection when the default is callback; any other default still needs an active tax connection.

  • Breaking change
  • API
  • Openapi

Tax calculation callback operations list X-Request-Id once#

These changes apply immediately to every supported API version.

  • The /v1/tax-calculation-callbacks operations listed the X-Request-Id request header twice. Each now lists it once, as every other operation does.
  • The header keeps its rules: 1 to 128 visible ASCII characters, sent once. Requests that were valid stay valid, and no response changes.

If you generate clients from the OpenAPI document, regenerate them. A generator that rejected duplicate parameters can now read these operations.

  • API
  • Errors
  • Tax

Unknown fields in tax objects are reported in byte order#

This change applies immediately to every supported API version. Error codes, statuses, and messages don't change.

When a request has more than one unknown field inside a tax object, param now names the first one in UTF-8 byte order, the same order details already uses elsewhere. It was the first one in the order you wrote the keys. JSON object keys have no defined order, so the same body now reports the same param whichever client serialized it.

This applies to five objects:

  • the tax object on an order line item
  • the tax object on a calculated order line item
  • the tax object on a calculated order charge
  • a tax component you send in a tax input
  • a tax jurisdiction

For example, a line item update with "tax": {"zeta": 1, "alpha": 1} returns param: "tax.alpha".

If you branch on param, no change is needed for requests with one unknown field. See Validation errors.

  • Breaking change
  • API
  • Errors

More request checks are published and reported together#

These changes apply immediately to every supported API version. Each refused input returns 400 INVALID_REQUEST with detail INVALID_VALUE (or REQUIRED where noted), listed with every other input that breaks the request schema.

New published rules. Flint already refused these values after the schema check. Now the OpenAPI document publishes each rule, and the schema check reports it.

  • ID filters publish their prefix as a pattern. A value without it is refused, and so is an empty, whitespace-padded, or lowercase value, which some of these filters used to ignore:
    • GET /v1/balance-transactions: payout_id, order_id
    • GET /v1/bundles/{bundle_id}/components: delivery_profile_id
    • GET /v1/delivery-quotes: checkout_session_id, order_id
    • GET /v1/fraud-warnings: payment_intent_id
    • GET /v1/inventory-reservations: inventory_item_id, location_id, order_id
    • GET /v1/me/tickets and GET /v1/tickets: order_id, plus payment_link_id on /v1/tickets
    • GET /v1/merchant-billing-entries: payment_intent_id, dispute_id, merchant_billing_invoice_id, balance_transaction_id
    • GET /v1/orders: customer_id
    • GET /v1/payment-reviews: payment_intent_id, order_id, customer_id
    • GET /v1/webhook-deliveries: webhook_event_id, webhook_endpoint_id
    • DELETE /v1/checkout-sessions/{checkout_session_id}/delivery-selections/current: expected_delivery_selection_id
  • GET /v1/webhook-endpoints created_by must be an API key, user, partner app, or workload identity ID.
  • Every idempotency_key list filter needs a character other than whitespace, and can't contain a null character or a line break.
  • domain_name on GET /v1/payment-method-domains and POST /v1/payment-method-domains must be a hostname with at least two labels of letters, digits, and inner hyphens, and not an IPv4 address. Surrounding ASCII whitespace and uppercase letters are still accepted. Padding with other whitespace, such as U+00A0 or U+0085, is now refused.
  • expected_version query parameters publish a maximum of 9007199254740991, the largest value Flint already accepted.
  • minimum_balance_currency_options on PATCH /v1/payout-settings takes uppercase currency codes as keys, such as USD. Flint no longer upper-cases a key such as usd; it refuses it at minimum_balance_currency_options.usd.
  • PATCH /v1/api-keys/{api_key_id} with scopes but no access returns REQUIRED at access. Before, the error named the whole body as matching none of the accepted shapes.

Repeated query values. A query parameter that takes one value and is sent more than once, such as ?order_id=ord_1&order_id=ord_2, returns INVALID_VALUE at that parameter with the message "order_id takes one value." Before, the message said the parameter "accepts a single value", and some parameters returned a different detail. Multi-value filters, such as status and expand, still accept repeated keys.

Bracketed query names. An unknown query parameter whose name isn't a plain name, such as status[] or expand[0], is named in the quoted form a map key uses: param is ["status[]"]. The message suggests the parameter you probably meant, such as status.

Scope names. The schema check now covers scopes on POST /v1/api-keys, PATCH /v1/api-keys/{api_key_id}, POST /v1/sandboxes, POST /v1/workload-identities, and PATCH /v1/workload-identities/{workload_identity_id}.

  • A retired scope name, such as capabilities.read, is refused. Before, Flint dropped it silently.
  • An unknown or retired name returns INVALID_VALUE at its entry, such as scopes[1], and the message names the nearest valid scope. It no longer returns the UNKNOWN_SCOPE detail or suggestions, which only unknown fields carry.
  • A repeated scope name on the API key and sandbox operations returns INVALID_VALUE at the later entry instead of DUPLICATE_SCOPE.
  • POST /v1/workload-identities without scopes returns REQUIRED at scopes.
  • A live-only scope on a test key, such as developer.sandboxes.read on POST /v1/api-keys with a sandbox_id or POST /v1/sandboxes with issue_test_key, still returns detail NOT_ALLOWED with scope and allowed_key_modes, because it is a valid scope name the test key can't hold. POST /v1/sandboxes now lists those live-only names in its scopes enum too, as POST /v1/api-keys already did.

Unknown fields inside tax objects. A field name that isn't a plain name inside a line item's or a charge's tax object is named in the same quoted form the rest of the API uses, such as tax["a.b"].

Read Validation errors for how the details are ordered and counted.

  • Breaking change
  • API
  • Errors

Validation counts the inputs a message doesn't name#

These changes apply immediately to every supported API version.

  • When one rule's message names several inputs, such as "tip.enabled and promotion_config.codes_enabled conflict", the top-level message now ends with a count of the details whose param the message doesn't name, such as "1 more input is invalid; see details." Before, Flint counted only the details whose own message differed, so a message that left out an input could end without a count.
  • A Content-Type or Idempotency-Key error now wins over an unknown query parameter, as the request checks order promises. Fix the header and the unknown parameter is reported next, with every other input that breaks the schema. The same holds for a body Flint couldn't read, such as one over the size limit: its error now comes before an unknown query parameter.
  • Inside a line item's or a charge's tax object, a field that differs only in case, such as Taxable, is still refused as UNKNOWN_FIELD, but the message no longer gives the correct spelling. This covers order line items, order charges, payment link line items, subscription plan line items, and checkout quick pay items. Everywhere else, the schema check already reports such a field and suggests the correct name.

Field names are case-sensitive everywhere. Read Validation errors for the message format.

  • Breaking change
  • Webhooks
  • Custom-domains
  • Tax

Custom domain events cover every public change#

Breaking: custom_domain.updated now fires whenever a custom domain's public state changes, other than by being archived. Before, it fired only when status changed. A domain that still needs attention, but for a different reason (for example dns_record_missing becoming dns_record_mismatch), now sends custom_domain.updated with the new status_reason, and so do changes to dns_records and payment_method_domain_id. A check that changes only last_checked_at still sends nothing, and neither does a new active_payment_attempt_count. If you treat every custom_domain.updated as a status change, compare status with the domain you stored first. Account owners are still emailed only when a hostname stops or starts working.

tax_connection.updated now fires only when the connection's public state or one of its registrations changes. Creating, editing, activating, or deleting a registration still sends it and advances version. Writes that only record Flint's internal provisioning progress, such as an account creation attempt, no longer advance version or send an event, so every new version arrives as an event.

A tax calculation callback update that changes nothing keeps its version and sends no event. custom_domain.archived is sent exactly once per archived domain. custom_domain.updated, custom_domain.archived, tax_connection.updated, and tax calculation callback change events now carry data.previous_attributes with the fields the change replaced. A connection's first stored write has no stored prior value, so that event carries none.

See Webhook events.

  • Breaking change
  • Webhooks
  • Merchants

Merchant events carry previous values and record time#

Breaking: merchant.readiness_updated now sets the envelope created_at to when Flint recorded the event. Before, it was the time the payment provider observed the account. That observation time is still in readiness.observed_at, so order two readiness reads by readiness.observed_at, not by the event's created_at. The event's object now also includes the merchant's logo and icon, exactly as GET /v1/merchant returns them.

merchant.readiness_updated still fires once for each account observation, payout capability change, and processing pause or resumption. It can arrive when readiness didn't change, so compare readiness with the copy you stored. After this release, a readiness change already delivered can arrive once more under a new event ID.

merchant.updated now carries data.previous_attributes with the profile fields the change replaced, and fires only when the merchant's public profile, status, API version, logo, or icon changes. Readiness never appears in previous_attributes. When one change updates the profile and publishes readiness, you get both events. Its envelope created_at is now when Flint recorded the event. Before, it was the merchant's updated_at, which a payment provider profile sync set to the provider's observation time.

A merchant profile write that changes nothing public no longer advances version. For example, a PATCH /v1/merchant that resends the stored values, or clears a field that is already empty, keeps version and updated_at, and the response returns them unchanged. A clear is still sent to the payment provider, which may hold a value collected during onboarding. A few provider-driven writes can still move updated_at without a new version, such as account updates from the payment provider.

See Webhook events.

  • Breaking change
  • Webhooks
  • Returns

Returns events follow each resource's version#

Return, receipt, inspection, disposition, and resolution webhooks change for every supported API version:

  • Verifying receipt lines while creating an inspection sends return_receipt.verified. Before, the receipt's version advanced with no receipt event.
  • Canceling a Return's last remaining line sends only return.canceled. Before, the same request also sent return.updated.
  • POST /v1/returns/{return_id}/process sends at most one event per resource. Before, it could send several return.updated events with the same snapshot.
  • A PATCH /v1/returns/{return_id} that repeats the current metadata and external_reference_id sends no event and keeps the Return's version and updated_at. Before, it advanced version and sent return.updated.

Each event is recorded with the request that changed the resource, and its snapshot is the resource as GET returns it, without supported_actions. Change events carry data.previous_attributes. A receipt's or inspection's available_disposition_quantity is read from its dispositions, so a disposition changes it without a receipt or inspection event; follow return_disposition.*.

See the Returns event catalog.

  • Breaking change
  • Webhooks
  • Risk
  • Disputes

Risk events follow the stored review and warning#

Breaking: when Flint links a dispute to the payment's fraud warning by setting the dispute's fraud_warning_id, it now sends dispute.updated and advances the dispute's updated_at. Flint sets the link when it processes an event for a payment that has both a dispute and a fraud warning. When that event also makes the warning unactionable, fraud_warning.updated arrives too. Before, fraud_warning_id appeared on the dispute without an event and without changing updated_at.

updated_at on payment reviews and fraud warnings is now when Flint recorded the change, and it never moves earlier. A provider event that arrives after a newer one no longer sets it to the older event's time. created_at, reported_at, opened_at, and closed_at keep the time of the event that caused them.

payment_review.* and fraud_warning.* events are recorded with the change that caused them. payment_review.closed, payment_review.reopened, and fraud_warning.updated carry data.previous_attributes, and payment_review.opened carries the review as GET /v1/payment-reviews/{payment_review_id} returns it. Moving a review to resolving, and linking the refund a decline starts while the review resolves, still send no event.

See Respond to fraud warnings.

  • Breaking change
  • Webhooks
  • Payment-links
  • Tickets

A ticket issued voided sends ticket.voided#

Breaking: when Flint issues a ticket for an order that a full refund already reached, the ticket is issued voided, and Flint now sends ticket.voided in addition to ticket.created. Before, only ticket.created arrived, carrying a ticket whose status was already voided. If you count valid tickets from events, the ticket.voided you already handle now covers this case too.

ticket.checked_in, ticket.voided, and ticket.updated now carry data.previous_attributes with the fields the change replaced. A code rotation always changes admission_code_last4, so it always advances version and sends ticket.updated. An attendee name edit that leaves the name as it was keeps version and sends nothing, as before.

See Webhook events.

  • API

New in the API: week of November 2, 2026#

631 additions across Fulfillment records, Inventory, and 45 more areas. These are additions, so nothing you already use needs to change.

Related: Payment intents publish the Affirm refund deadline, The checkout session surface embedded is now headless, Inputs that can't be sent together name the input to remove, Bulk delivery assignment runs after the response, Delivery configuration events follow version, and six unused types are removed, Delivery configuration PATCH publishes a revision only for revision fields, Delivery quotes move to top-level routes, Delivery rate callback requests use public field names, Delivery rate callback secrets follow signing_methods, Buyers lose the download link after a full refund, Stripe Elements guidance lists Flint payment options, Embed a merchant's payments and disputes with the payments component, Used-up subscription promotions stay listed until the renewal is recorded, Refunds say who initiated them, Inventory events arrive once per change, with previous values, Inventory reservations, counts, and transfers send updated events, Invoice checkout moves to POST /v1/checkout-sessions, Charge a saved card while the customer is away, Payment failures name never-retry and outdated-card declines, Sandbox and onboarding keys come from POST /v1/api-keys, Order activity deltas follow the balance, Order edit previews can add and replace items, Orders report the value edits removed, Partner apps can declare payment splits, Partner apps show the current platform terms version, Partner apps can set a platform fee cap, Partner apps can complete platform onboarding, Partner app tokens read your app's installs and revoke them, Partner event reads follow the resource routes, Partner install events are sent with the change, Partner app install lists show each merchant's readiness, Partner app installs can brand checkout and set custom domains, Partner app installs can read balances and payouts and answer disputes, Partner apps can receive dispute, payout, and balance events, Temporary Flint faults during payment checks are retryable, Payment failures and refusals use one name per condition, Payment intents name their subscription, return resolution and latest attempt, Saved card updates and unconfirmed card failures send events, Refunds for payments Flint can't accept, Set default payout destinations through the API, Partner apps can charge platform fees, Readers for in-person payments, Request logs name every credential's caller, and API keys filter by creator, Return balance checkout moves to POST /v1/checkout-sessions, Resetting a sandbox keeps its ID, keys, and webhook endpoints, Name a gift recipient on a subscription, Permanent declines apply the dunning end action when the retry window closes, Preview subscription promotions, Subscription events record the change and its previous values, Tax hosted checkout, payment links, and subscriptions with your tax calculation callback, Tax calculation callback operations list X-Request-Id once, Unknown fields in tax objects are reported in byte order, More request checks are published and reported together, Validation counts the inputs a message doesn't name, Custom domain events cover every public change, Merchant events carry previous values and record time, Returns events follow each resource's version, Risk events follow the stored review and warning, A ticket issued voided sends ticket.voided, A misconfigured delivery method no longer fails the whole quote, Delivery errors name the input, or report a Flint failure, Delivery quotes, selections, and previews drop fields Flint never used, Delivery rate callback bodies are in the OpenAPI document, Platforms can create merchants with merchant signups, Request logs record the partner app behind partner app token requests, Email buyers when a ship date changes, Partner apps can stream an installed merchant's events, Automatic tax for tax-inclusive prices and post-tax discounts, Automatic tax calculates orders that ship from or to more than one place, Errors keep the keys you send in request maps, Canadian automatic tax covers digital goods, software, and SaaS, Automatic tax for Canadian digital products and services, Catalog changes reach every resource they change, Catalog parents send their own event when a child changes them, One rule decides what a credential can grant, Allocations made on issue report your Idempotency-Key, Credit note refunds no longer send credit_note.updated, Choose a default tax price mode, Gift card events arrive once per change, with previous values, Automatic VAT and GST for the EU, the UK, Australia, and New Zealand, with reverse charge, Preparing international automatic tax records, Inventory lifecycle actions use their own routes, Customer price-list resolution, Order lifecycle status words and inventory resolution route, Order payment completion timestamp and report column rename, Partner apps mint one token per mode and name the merchant on each request, Partner apps get only events and scopes they can use, Partner app installs can onboard their merchant in test mode, Payment errors name the merchant setup step, Payout transitions send one status event, Price lists and customer assignments, Price list schema corrections, Refund success times, and tax reports name the refund, Location settings no longer block archiving, Returns validation errors name the input to change, Validation errors name the input to change, Create and import subscriptions with promotions, Subscription create previews price first-period proration, Apply and remove subscription promotions, Tax address and registration fields depend on the country, Calculate order tax with your tax calculation callback, Collect an attendee name for each event ticket, Check in, void, and edit event tickets, Validation errors list every invalid input, EU and UK VAT in local currency on invoices and credit notes, Checkout sessions send checkout_session.updated, Customer deletion events follow each resource's state, Customer events follow the customer's version, Fulfillment events follow the stored fulfillment, Credit note allocations update the credit note, Order amount changes send order.updated, Prorate an anchored first subscription period, Send the buyer's IP address when your server pays, Preview buyer subscription quantity changes, Choose a delivery charge tax basis, Delivery methods and rate callbacks show when their current revision is revoked, Backdated manual payments preserve order update times, Payment link answers move to custom_field_answers, Revoked delivery methods can't be added to new checkouts, links, or plans, End a subscription after a number of cycles or on a date, Read frozen buyer quantity policies on subscription lines, Schedule subscription line quantity changes, Authorization warnings before capture deadlines, Automatic tax country coverage matches accepted locations, Automatic tax works with manual capture, Automatic tax works with deposits, installments, and split payments, Checkout sessions no longer expose delivery dependency pins, Context headers must match fixed credentials, Delivery inputs use request paths and pickup uses inventory_unavailable, Take unshipped items off a paid order, Event tickets are individual records you can read, Inventory items record a backorder policy and backordered quantity, Inventory observations share sequence rules and show live versions, Record late payments after an invoice write-off, Merchant billing invoice numbers and issue times, Recording an offline payment warns when an order is past the allowance, Orders paid outside Flint past the allowance appear as a monthly event fee, Preview removing items from a paid order, Order lines report removed quantity, param names the input to change, payment_intent.updated covers refund and dispute changes, Record credit-note refunds you paid outside Flint, Refunds accept the out_of_stock reason, Invoice time zone setting removed, Retry a failed order edit refund, Returns responses and buyer cancellation match their contract, Risk rule matching and payment review attribution, Subscription create previews include collection estimates, Charge prorated subscription changes without moving the billing date, Moving a trial's billing date moves its trial end, Free trials can start without a card, Register a tax calculation callback, tax_transactions_itemized_v2 report, Variant quantity price breaks, Invoice lifecycle events omit companion updates, Refund and dispute events follow committed changes, Sell variants on backorder and pre-order, Request log search uses query, Automatic return dispositions follow inspection conditions, Automatic tax supports service, handling, and surcharge fees, Embedded modifier groups and category references, Checkout saved-card lists require verified authority, Credit-note refunds return gift cards first, Record customer tax exemptions, Invoice and order refund events follow status changes, Export issued invoices with payments and outstanding balances, One business time zone on the merchant, Orders paid outside Flint past the monthly allowance cost $1 each, Download an order's receipt as a PDF, Tax exemptions apply to orders, invoices, and renewals, Public organizations API removed, Package and order lifecycle actions, Payment links use checkout_start_due_at for the checkout start cutoff, Limit promotions per customer and bind codes to a customer, Receivables aging report, Receipt settings removed from the settings API, Return receipt overflow reports quantity limits, Create a sandbox that starts with onboarding not started, Set statement text for new payments and read it on payment intents, Subscriptions can exist without a payment method, Cancel unpaid replacement resolutions, Preparing local-currency VAT invoice amounts, Previous values on webhook change events, Delivery country requirements follow method coverage, Hosted checkout launches omit checkout_auth_token, Download a numbered receipt for each subscription charge, Automatic tax supports tax-exempt customers, Credential types and authentication failures, Tax delivery charges on external-tax orders with one template, External tax accepts foreign jurisdictions and VAT and GST types, Lines with nothing to fulfill return a validation error, Digital and service variants can use a manual delivery profile, Offline payments can be recorded beyond the monthly allowance, Order routing inputs and response vocabularies, Find orders by product, variant, or email, Partner apps can receive merchant readiness and profile events, Buyer exchange previews and net original prices, Plan changes default to an interval the target offers, Record who requested a subscription cancellation, Tax connection legal identity and sandbox profiles, Credit-note refunds move to the refunds API, A customer with no email can be given one in either account mode, Disputes include network reason codes and evidence recommendations, Inventory errors identify the cause and short demand, JSON bodies reject null and rate limits name credentials, Error recovery instructions fit the request, Return fees use refundable value and credit-note refunds use gift cards first, Consistent postal address and email validation, Subscriptions require a customer email, Imported subscriptions count the current paid period, Schedule a subscription plan change for the next charged renewal

Fulfillment records
32 additions
Price lists
10 additions
Tickets
14 additions
Tax calculation callbacks
13 additions
Orders
65 additions
Readers
10 additions
Customer tax exemptions
5 additions
Customer account
75 additions
Subscriptions
61 additions
Partner apps
22 additions
  • Endpoint
  • Request field
    payment_splitson PATCH /v1/partner-apps/{partner_app_id}

    Replaces the whole payment_splits declaration.

  • Request field
    platform_fee_capon PATCH /v1/partner-apps/{partner_app_id}

    Replaces the whole platform fee cap.

  • Request field
    platform_profileon PATCH /v1/partner-apps/{partner_app_id}

    Replaces the whole platform profile, which Flint reviews before it approves the app as a platform. support_email, website_url and support_phone are shown to merchants on the consent screen and install resource.

  • Request field
    payment_splitson POST /v1/partner-apps

    Declares that the app's owner sends splits of the payments it collects to sellers that install the app, with the seller terms sellers approve on the consent screen.

  • Request field
    platform_fee_capon POST /v1/partner-apps

    The most a platform fee can take from one payment the app creates with a partner app token.

  • Request field
    platform_profileon POST /v1/partner-apps

    The platform profile Flint reviews before it approves the app as a platform.

  • Request field
    modeson POST /v1/partner-apps/{partner_app_id}/credentials

    Modes this credential can mint partner app tokens for, with grant_type=client_credentials or an authorization code exchange.

Delivery quotes
2 additions
Subscription plans
32 additions
  • Request field
    allow_quantity_adjustmenton PATCH /v1/subscription-plans/{subscription_plan_id}

    Whether buyers may adjust this line quantity.

  • Request field
    allow_quantity_adjustmenton PATCH /v1/subscription-plans/{subscription_plan_id}

    Whether buyers may adjust this line quantity.

  • Request field
    allow_quantity_adjustmenton PATCH /v1/subscription-plans/{subscription_plan_id}

    Whether buyers may adjust this line quantity.

  • Request field
    allow_quantity_adjustmenton PATCH /v1/subscription-plans/{subscription_plan_id}

    Whether buyers may adjust this line quantity.

  • Request field
    end_afteron PATCH /v1/subscription-plans/{subscription_plan_id}

    Default automatic end for new subscriptions.

  • Request field
    max_quantityon PATCH /v1/subscription-plans/{subscription_plan_id}

    Maximum buyer quantity.

  • Request field
    max_quantityon PATCH /v1/subscription-plans/{subscription_plan_id}

    Maximum buyer quantity.

  • Request field
    max_quantityon PATCH /v1/subscription-plans/{subscription_plan_id}

    Maximum buyer quantity.

Refunds
30 additions
  • Query parameter
    credit_note_idon GET /v1/refunds

    Exact match on the credit note whose credit was refunded.

  • Request field
    credit_note_idon POST /v1/refunds

    Issued credit note on a paid invoice whose credit is returned to the buyer.

  • Request field
    expected_credit_note_versionon POST /v1/refunds

    Credit note version last read.

  • Request field
    processed_byon POST /v1/refunds

    Who moves the money for this refund.

  • Request field
    processed_byon POST /v1/refunds

    Who moves the money for this refund.

  • Request field
    refund_referenceon POST /v1/refunds

    Optional check, wire, or other reference for the money you returned outside Flint.

  • Request field
    refund_referenceon POST /v1/refunds

    Optional check, wire, or other reference for the money you returned outside Flint.

  • Request field
    refunded_aton POST /v1/refunds

    When you report returning the money outside Flint.

Invoices
23 additions
Checkout sessions
17 additions
Payment links
13 additions
  • Request field
    collect_attendee_nameson PATCH /v1/payment-links/{payment_link_id}

    Whether resolving the link requires `attendee_names`, one name per ticket.

  • Request field
    collect_attendee_nameson POST /v1/payment-links

    Whether resolving the link requires `attendee_names`, one name per ticket.

  • Request field
    attendee_nameson POST /v1/payment-links/{payment_link_id}/resolve

    One attendee name per ticket on an event payment link, in line_items order: each tier's tickets in turn, skipping tiers with quantity 0.

  • Request field
    client_referenceon POST /v1/payment-links/{payment_link_id}/resolve

    Your reference for the buyer or cart this checkout is for, such as your user ID.

  • Request field
    prefillon POST /v1/payment-links/{payment_link_id}/resolve

    Email to fill in on the next checkout step.

  • Field
  • Field

    Whether resolving the link requires `attendee_names`, one name per ticket.

  • Field

    Tickets for this payment link that are checked in now, counted when the summary is read.

Payments
13 additions
  • Request field
    customer_presenceon POST /v1/orders/{order_id}/pay

    Whether the customer is present for this payment.

  • Request field
    request_overcaptureon POST /v1/payment-intents

    Let one capture collect more than the authorization where the card network allows it, for example a final bill plus a tip.

  • Request field
    final_amount_moneyon POST /v1/payment-intents/{payment_intent_id}/capture

    The bill without the tip.

  • Request field
    tip_moneyon POST /v1/payment-intents/{payment_intent_id}/capture

    The tip, replacing the tip the authorization carries.

  • Field

    Lifecycle actions Flint accepts for this resource now, based on stored state.

  • Field

    The part of captured_money that is a tip: the capture's tip_money when it sent one, otherwise the tip the authorization carried, at most captured_money. tip_money keeps the tip the authorization carried.

  • Field

    Whether the customer was present for the most recent confirmation. absent means Flint charged a saved card without them, as a merchant-initiated payment on its stored credential.

  • Field

    Whether one capture can collect more than the authorization, and the most it can collect.

Products
12 additions
Reports
12 additions
Settings
12 additions
  • Request field
    calculation_callback_idon PATCH /v1/settings

    The active tax calculation callback selected for this merchant and environment.

  • Request field
    default_calculationon PATCH /v1/settings

    Replaced as a whole: send every field you want to keep.

  • Request field
    default_price_modeon PATCH /v1/settings

    Price mode an order takes when it starts calculating tax without its own tax.calculation: when it is created, from a checkout session or payment link, or when tax is turned on later. additive (the default) adds tax to prices, and inclusive treats every line item and charge price as including its tax.

  • Request field
    default_routing_sourceon PATCH /v1/settings

    Where tracked demand is routed when a request omits `inventory_routing_source`: a fixed Location, an allocation policy, or one policy revision.

  • Request field
    delivery_charge_tax_basison PATCH /v1/settings

    Automatic tax basis for delivery-method charges.

  • Request field
    paymentson PATCH /v1/settings

    Patch object: fields you send are applied, fields you omit are unchanged.

  • Field

    Where tracked demand is routed when a request omits `inventory_routing_source`: a fixed Location, an allocation policy, or one policy revision.

  • Field

    Statement text for new payments and Stripe's current decision about the card statement name.

OAuth
11 additions
  • Request field
    merchant_idon POST /v1/oauth/token

    Binds the minted partner app token to this merchant, for client_credentials.

  • Request field
    merchant_idon POST /v1/oauth/token

    Binds the minted partner app token to this merchant, for client_credentials.

  • Request field
    merchant_idon POST /v1/oauth/token

    Binds the minted partner app token to this merchant, for client_credentials.

  • Request field
    merchant_idon POST /v1/oauth/token

    Binds the minted partner app token to this merchant, for client_credentials.

  • Request field
    merchant_idon POST /v1/oauth/token

    Binds the minted partner app token to this merchant, for client_credentials.

  • Request field
    modeon POST /v1/oauth/token

    Mode of the partner app token to mint, test or live.

  • Request field
    modeon POST /v1/oauth/token

    Mode of the partner app token to mint, test or live.

  • Request field
    modeon POST /v1/oauth/token

    Mode of the partner app token to mint, test or live.

Webhooks
11 additions
  • Query parameter
    created_byon GET /v1/webhook-endpoints

    Filter by the exact ID of the API key, user, partner app, or workload identity that created the endpoint.

  • Field

    The API key, user, partner app, or workload identity that created this endpoint.

  • Values

    checkout_session.updatedinventory_count.updatedinventory_reservation.updatedinventory_transfer.updatedorder_edit.createdpartner_app.platform_approved

  • Values

    checkout_session.updatedinventory_count.updatedinventory_reservation.updatedinventory_transfer.updatedorder_edit.createdpartner_app.platform_approved

  • Values

    order_editpartner_appprice_listreadertax_calculation_callbackticket

  • Values

    checkout_session.updatedinventory_count.updatedinventory_reservation.updatedinventory_transfer.updatedorder_edit.createdpartner_app.platform_approved

  • Values

    checkout_session.updatedinventory_count.updatedinventory_reservation.updatedinventory_transfer.updatedorder_edit.createdpartner_app.platform_approved

  • Values

    checkout_session.updatedinventory_count.updatedinventory_reservation.updatedinventory_transfer.updatedorder_edit.createdpartner_app.platform_approved

API keys
9 additions
API request logs
9 additions
Delivery configuration
9 additions
Promotions
8 additions
  • Query parameter
    customer_idon GET /v1/promotion-codes

    Exact match on the customer bound to the code.

  • Request field
    customer_idon PATCH /v1/promotion-codes/{promotion_code_id}

    Only this identified customer can redeem the code.

  • Request field
    max_uses_per_customeron PATCH /v1/promotions/{promotion_id}

    Maximum reserved and redeemed uses per identified customer across every code and automatic or ID-based application.

  • Request field
    customer_idon POST /v1/promotion-codes

    Only this identified customer can redeem the code.

  • Request field
    customer_idon POST /v1/promotions

    Only this identified customer can redeem the code.

  • Request field
    max_uses_per_customeron POST /v1/promotions

    Maximum reserved and redeemed uses per identified customer across every code and automatic or ID-based application.

  • Field

    Maximum reserved and redeemed uses per identified customer across every code and automatic or ID-based application.

  • Field

    Only this identified customer can redeem the code.

Return policies
6 additions
Credit notes
5 additions
Customers
5 additions
  • Query parameter
    price_list_idon GET /v1/customers

    Only return customers assigned directly to this price list.

  • Request field
    price_list_idon PATCH /v1/customers/{customer_id}

    ID of a wholesale price list in this merchant environment.

  • Request field
    decision_reasonon POST /v1/customer-deletion-requests/{customer_deletion_request_id}/resolve

    Optional plain-text explanation visible to the buyer.

  • Request field
    price_list_idon POST /v1/customers

    ID of a wholesale price list in this merchant environment.

  • Field

    ID of the customer's direct wholesale price list.

Delivery previews
4 additions
Delivery selections
4 additions
Money movement
4 additions
Tax connection
4 additions
Sandboxes
3 additions
  • Request field
    initial_onboardingon POST /v1/sandboxes

    The onboarding state the sandbox starts in, and returns to when you reset it.

  • Field

    The onboarding state the sandbox starts in, and returns to when you reset it.

  • Values

    commerce.tickets.readcommerce.tickets.writepayments.readers.readpayments.readers.write

Disputes
2 additions
Merchants
2 additions
  • Request field
    timezoneon PATCH /v1/merchant

    Business IANA time zone, such as America/New_York.

  • Field

    Business IANA time zone, such as America/New_York.

Partner OAuth
2 additions
Risk controls
2 additions
  • Request field
    actionon POST /v1/risk-previews

    Action to preview.

  • Request field
    predicateon POST /v1/risk-previews

    Predicate to preview.

Workload identities
2 additions
Bundles
1 addition
  • Field

    Whether the bundle can be sold now: it is `active`, has at least one component, every component's variant and product are `active`, and `delivery_configuration_status` isn't `action_required`.

Demo sessions
1 addition
Merchant billing
1 addition
Payment methods
1 addition
  • Event

    A saved payment method's details changed without a stored status change, such as new card details from the card network after the bank reissued the card.

Webhook events
28 additions
  • Field
    CreditNoteAllocation.supported_actions

    Lifecycle actions Flint accepts for this resource now, based on stored state.

  • Field
    CustomerDeletionRequest.decided_at

    Time of the most recent approve or reject decision.

  • Field
    CustomerDeletionRequest.decision_reason

    Merchant's plain-text explanation for rejecting the request, visible to the buyer.

  • Field
    CustomerDeletionRequest.requested_by

    Who opened the request: buyer from the buyer account, or merchant on the buyer's behalf.

  • Field
    CustomerDeletionRequest.response_due_at

    Requested time plus one calendar month in UTC, clamped to the last day of that month.

  • Field
    DeliveryMethod.delivery_revocation_id

    The revocation fencing this resource's own current revision.

  • Field
    DeliveryRateCallback.delivery_revocation_id

    The revocation fencing this resource's own current revision.

  • Field
    ExpandedPayoutDestinationSummary.is_default_for_currency

    Whether this is the default destination for its currency.

  • Breaking change
  • API
  • Delivery
  • Checkout

A misconfigured delivery method no longer fails the whole quote#

A delivery method with an allocated_origin_group origin of two or more Locations can't serve items whose delivery profile has origin_policy method_origin, such as the General profile. Previously, every quote that included such a method returned 503 SERVICE_UNAVAILABLE with remediation.retry: same_request, and retrying always failed the same way.

Quotes and delivery previews now succeed. The affected method's candidate outcome is cannot_calculate with failure_category: invalid_configuration and retryable: false, and its merchant_diagnostics entry has code: method_unavailable, recommended_action: review_configuration, and a summary naming origin_policy. Every other method is still evaluated and offered. If every method in the quote is affected, the quote is created with no available options instead of failing.

To offer the method, put the items on a profile with origin_policy inventory_routing and give orders an inventory_routing_source, or give the method a fixed_location origin. See Ship from two warehouses.

503 SERVICE_UNAVAILABLE remains for temporary failures where Flint couldn't evaluate any method.

  • Breaking change
  • API
  • Delivery
  • Checkout
  • Errors

Delivery errors name the input, or report a Flint failure#

Some delivery requests returned 400 INVALID_REQUEST with param: body and the message "the delivery request is invalid", even when nothing in the request was wrong. For example, a subscription checkout whose order Flint had stored without its inventory revision returned this 400 on every quote, so retrying with a different body could never work.

Those failures are now reported for what they are. When the failure is in data Flint stored or computed, the response is 500 INTERNAL_ERROR with error_source: flint. Flint logs the cause under the response's request_id, so contact support with it.

Rates you supply in method_results are reported at the field that's wrong:

  • A count that doesn't match pending_caller_rate_requests returns the error at method_results.
  • An extra or duplicate pair returns it at that entry, such as method_results[1].
  • An outcome missing a field its type needs returns INVALID_REQUEST with detail REQUIRED at that field, such as method_results[0].outcome.failure_category or method_results[0].outcome.retryable.
  • An available outcome that breaks a rule names the field and the rule, such as method_results[0].outcome.amount_money.currency for a currency other than the checkout's, method_results[0].outcome.expires_at for an expiry before the method's minimum_option_lifetime_seconds or after the pending quote's, and method_results[0].outcome.offered_windows[1].start_at for overlapping windows. A window's position is its position in your request.

Other caller input now names its field too:

  • A malformed page_token, or one issued for different list parameters, returns 400 INVALID_REQUEST with detail INVALID_VALUE at page_token on every delivery list: profiles, zones, location sets, methods, rate callbacks, quotes, revocations, and a checkout session's delivery selections. Restart from the first page.
  • GET /v1/delivery-revocations/{delivery_revocation_id} with a malformed ID returns 400 INVALID_REQUEST at delivery_revocation_id, and GET /v1/checkout-sessions/{checkout_session_id}/delivery-selections with a malformed ID returns it at checkout_session_id.
  • A delivery preview whose delivery_method_ids and line items would offer more than 100 options returns 400 INVALID_REQUEST at delivery_method_ids, also when you left it out and the checkout default applied. Send fewer methods.
  • A delivery selection that lists one choice group twice returns 400 INVALID_REQUEST at the repeated entry, such as choices[1].delivery_choice_group_id. A choice without its group or option ID returns it at that field.

Previously these returned the same body-level 400 without naming the field.

Two quote failures caused by the checkout session's delivery methods are now 409 ACTION_NOT_ALLOWED with reason configuration_required, error_source: merchant, and retry none. The detail names the checkout session (resource_type: checkout_session), and next_actions is update_checkout_session with required_fields: ["delivery_method_ids"]:

  • None of the session's delivery methods has a type an item's delivery profile allows. This was 400 INVALID_REQUEST at body.
  • The session's methods and choice groups would offer more than 100 options in one quote. This was a 400 at body; reduce the session's delivery_method_ids or the items with different delivery profiles.
  • Breaking change
  • API
  • Delivery
  • Checkout

Delivery quotes, selections, and previews drop fields Flint never used#

These fields and values described Flint's internal bookkeeping or were never returned. Removing them leaves only what you can act on.

Delivery quotes and selections. DeliveryQuote, DeliverySelection, and the delivery_selection.committed event no longer include delivery_quote_version or eligibility_context_version. They counted internal changes and never fenced a write. Read a quote's status and stale_reason to know whether you can still select from it.

Selection deadlines. DeliverySelection.limiting_deadline_reason lists only the three values Flint returns: selection_guarantee_expiry, calculation_expiry, and selection_maximum_lifetime. inventory_reservation_expiry, tax_validity_expiry, and checkout_session_expiry were never returned and are removed. A stock hold ends with the guarantee, so it reports selection_guarantee_expiry, and the checkout session's expiry bounds the calculation, so it reports calculation_expiry.

Quote choice groups. A delivery quote's choice group availability_status no longer lists needs_checkout_context, which only delivery previews return.

Delivery previews. CreateDeliveryOptionsPreviewRequest no longer accepts pricing_context. No accepted key ever changed a preview's prices, and sending it now returns 400 INVALID_REQUEST with an UNKNOWN_FIELD detail and param pricing_context. inventory_routing_source now uses the shared InventoryRoutingSourceInput union that orders and payment links use, so each type requires its own ID and refuses the others. DeliveryPreviewRoutingSource is removed.

Rates your server supplies. Each method_results[].outcome type now publishes and accepts only its own fields, plus merchant_reference. Sending another type's field, such as amount_money on an unavailable outcome, returns 400 INVALID_REQUEST with an UNKNOWN_FIELD detail whose param names it, such as method_results[0].outcome.amount_money. Previously the request failed without naming the field.

  • API
  • Delivery

Delivery rate callback bodies are in the OpenAPI document#

The OpenAPI document now describes the requests Flint sends to a delivery rate callback. createDeliveryRateCallback has two callbacks under components.callbacks, both posting to the callback's configuration.url:

Both list the signing headers as parameters. The request and response bodies haven't changed, so you can generate types for your callback server from the OpenAPI document instead of copying them from Live delivery rates with a callback.

Test deliveries now send leg_distance_meters as an empty array, as live requests do, instead of null.

  • Breaking change
  • API
  • Partners

Platforms can create merchants with merchant signups#

A merchant signup creates a Flint merchant for a business owner from inside your product. Create one with POST /v1/merchant-signups, and Flint emails the owner a code that names your app, the business, the permissions and platform fee cap you request, and Flint's merchant terms. Send the code and the owner's terms acceptance to POST /v1/merchant-signups/{merchant_signup_id}/verify: Flint creates the merchant, installs your app in the modes you chose, and returns test_authorization_code and live_authorization_code. Exchange them at POST /v1/oauth/token without redirect_uri.

  • The routes are createMerchantSignup, getMerchantSignup, listMerchantSignups, verifyMerchantSignup, resendMerchantSignupCode, cancelMerchantSignup and rotateMerchantSignupAuthorizationCodes. They take your app owner's live credentials, with the new scopes developer.merchant_signups.read and developer.merchant_signups.write. Test credentials get 403 FORBIDDEN with reason live_mode_required, and keys linked to an install get reason linked_key_not_allowed.
  • PartnerApp.merchant_action_url is where Flint sends an owner of a merchant your app created when an email asks them to act. Its registrable domain must match platform_profile.website_url, and PATCH with it requires expected_version. Setting it requests the new create_merchants platform capability, which live signups and signups for owners outside your team need.
  • PartnerAppInstall.merchant_signup_id names the signup that created an install.
  • Breaking: expected_version with merchant_action_url. A PATCH /v1/partner-apps/{partner_app_id} that sends merchant_action_url must also send expected_version, or it returns 400 INVALID_REQUEST with detail REQUIRED at expected_version. Requests without merchant_action_url are unchanged.
  • Breaking: partner app names are at most 100 characters. POST /v1/partner-apps and PATCH /v1/partner-apps/{partner_app_id} return 400 INVALID_REQUEST with INVALID_VALUE at name for a longer name, because Flint's emails show it.
  • New error reasons: merchant_signups and owned_merchants under LIMIT_REACHED, and owner_identity_conflict under ACTION_NOT_ALLOWED.
  • A partner app's name and permission title values can no longer contain a link, a host name, or an email address, because Flint's emails show them. Writes that include one return 400 INVALID_REQUEST with INVALID_VALUE at the field. Existing apps keep their values, but signups for an app whose name or permission titles contain one are refused with configuration_required until you change them.
  • API
  • Developers
  • Partners

Request logs record the partner app behind partner app token requests#

GET /v1/api-request-logs and GET /v1/api-request-logs/{api_request_log_id} now return partner_app_id on requests made with a partner app token. The install remains the request's caller.

The list accepts a new partner_app_id filter, which requires developer.request_logs.read. When it names an app your merchant owns, the list covers that app's partner app token requests in every merchant that installed it, in the credential's mode. For any other app, it narrows your own environment's requests. The detail route still reads only your environment.

The dashboard's Versions screen now lists only the changes on routes a partner app called when you change the app's version. See Review a partner app's requests.

  • API
  • Orders
  • Delivery
  • Fulfillment

Email buyers when a ship date changes#

Ship date emails. When you change or clear a paid line's expected_ship_date with PATCH /v1/orders/{order_id}/line-items/{order_line_item_id}, Flint emails the buyer the new date. The email belongs to the fulfillment_updates family and the buyer's shipping_updates preference, both checked when it's sent. A request that doesn't change the date, the date Flint sets at payment, and stock filling a backorder send nothing. If you change the same line again before the email goes out, the buyer gets only the latest date. See Change an expected ship date.

Receipts. Payment receipts note each pre-order line as "Pre-order, releases {date}" and each backordered line as "Backordered, ships about {date}", or "Backordered" without a date.

Delivery estimates. Estimates that count handling_days and transit_days now start from the latest pre-order release date or backordered item's expected ship date in the delivery choice, when that date is after today. Windows you or a rate callback supply, scheduled windows, and quote expiry don't change. See Delivery options.

  • API
  • Webhooks
  • Partners

Partner apps can stream an installed merchant's events#

GET /v1/webhook-events/stream now accepts a partner app's install token with webhooks.read. The stream carries the installed merchant's events in the environment the token's grant covers, in recorded order, with the same ready, gap, withheld, and disconnect frames. A partner app that missed deliveries can now resume from a known event instead of paging GET /v1/webhook-events by created_at.

A webhook.event frame carries data only for an event Flint forwards to installed-merchant endpoints while the grant holds the scope that event requires. Other events arrive as withheld frames. The new withheld reason partner_read_unsupported marks events Flint doesn't forward to installed-merchant endpoints, such as reports and customer deletion requests.

Each install can have five streams open per environment, apart from the merchant's own five. The stream ends with authorization_changed when the token expires or the install or grant stops authorizing it. See Catch up on missed installed-merchant events.

  • API
  • Tax
  • Reports

Automatic tax for tax-inclusive prices and post-tax discounts#

Orders with automatic tax accept tax.calculation.price_mode: inclusive. Every line item and charge price then includes its tax: Flint gets the rates for the price after pre-tax discounts and extracts the tax as price × rate ÷ (100 + rate), rounded half up. The buyer pays the prices you entered. See Tax-inclusive prices with automatic tax.

Discounts with discount_calculation_basis: subtotal_post_tax work with automatic tax. Tax is calculated on the price before the discount, so the discount lowers what the buyer owes but not the tax. See Post-tax discounts.

tax_transactions_itemized_v2 now fills post_tax_discount_money with each collection's share of post-tax discounts, and its discount_money holds pre-tax discounts. tax_transactions_itemized_v1 has no column for them, so its total_money is the calculated total before the post-tax discount.

These requests used to fail with 400 INVALID_REQUEST.

  • API
  • Orders
  • Tax

Automatic tax calculates orders that ship from or to more than one place#

Automatic tax now calculates each part of an order from where it leaves to where it goes. One order can ship from more than one warehouse, pick up at more than one store, ship some items and have others picked up, and ship to different addresses.

Fulfilled goods are taxed from the location that fulfills them to their shipping address or pickup store. A line item fulfilled from two locations is calculated in two parts, each with its share of the quantity and amount. Services and items without a fulfillment are taxed from your legal address to the order's tax location, so a taxable service can be sold with shipped or picked-up goods. A charge takes the origin and destination of the fulfillment it belongs to.

tax.location is omitted when every taxable item and charge is taxed at its own fulfillment destination and those destinations differ. Each calculation commits, collects, and refunds as before, and the tax reports show its own seller_origin.* and buyer_destination.*. Orders with one origin and one destination are calculated as before.

These orders no longer fail with 400 INVALID_REQUEST. See Several stores or destinations.

  • Breaking change
  • API
  • Errors
  • Payment-links
  • Delivery
  • Returns

Errors keep the keys you send in request maps#

These changes apply immediately to every supported API version. Error codes and statuses don't change.

  • Resolving a payment link names the entry you sent in variant_selections, custom_field_values, quantity_overrides, unit_price_overrides, and modifiers, such as variant_selections.events_from or custom_field_values.fulfillment_profile_id. Before, a key such as events_from came back as event_sources, and fulfillment_profile_id came back as delivery_profile_id.
  • Keys that aren't plain identifiers are quoted, such as custom_field_values["a.b"].
  • Errors for a line item that doesn't allow quantity or amount adjustment now name quantity_overrides.<key> or unit_price_overrides.<key> instead of quantity_overrides["<key>"] or unit_price_overrides["<key>"]. Oversized custom_field_values answers name custom_field_values.<key>.
  • Messages that quote one of your keys keep it as you sent it.
  • Delivery previews name an unsupported pricing_context entry exactly, such as pricing_context.events_from.
  • Processing an open return whose lines have different committed receiving locations names the line, such as line_items[1], instead of line_items[1].decision.receiving_location_id, because the committed decision can't be changed. The message says to process lines with different receiving locations in separate requests.

If you match on param, update those comparisons to use these values.

  • Breaking change
  • Tax
  • Orders

Automatic tax for Canadian digital products and services#

Automatic tax now calculates Canadian digital products and services. Add a federal GST/HST registration and, where needed, a provincial PST, RST, or QST registration. Each tax follows its own registration dates. Canadian physical goods and taxable charges remain unsupported; set a charge's taxable: false or use external tax for the order.

GET /v1/tax-connection now returns coverage with each country's category scope. Canadian calculations record separate rows for each tax, carried through invoices, refunds, and row-based reports. US tax behavior stays the same.

Tax registration country now accepts CA. A Canadian federal registration omits state on create and returns state: null; clients must accept that nullable response field. Registration lists now sort by country, state, then ID. Unsupported automatic-tax countries or categories return 400 INVALID_REQUEST for request input and 409 ACTION_NOT_ALLOWED with reason configuration_required for stored input.

See Canada coverage and Tax registrations.

  • Breaking change
  • Tax
  • Orders

Canadian automatic tax covers digital goods, software, and SaaS#

Canadian automatic tax now covers digital_goods, software, and saas. GET /v1/tax-connection lists Canada with category_scope: digital instead of services. digital is a new value; the category_scope enum is extensible, so handle values you don't recognize.

Taxable Canadian line items with services or professional_services are refused before calculation. Lines with taxable: false are still accepted. A category in the request returns 400 INVALID_REQUEST with detail INVALID_VALUE and param naming the line item's line_item_tax_category. A stored category returns 409 ACTION_NOT_ALLOWED with reason configuration_required. Use external tax for those orders. Previously these orders failed during calculation.

US coverage stays all, and US services tax is unchanged. See Canada coverage.

  • Breaking change
  • API
  • Webhooks
  • Products
  • Promotions

Catalog changes reach every resource they change#

Previously, archiving a product sent only product.archived, and archiving a promotion sent only promotion.archived, so a mirror had to mark the children archived itself. A product or variant change that reached a variant's or bundle's copy of it changed that resource without advancing its version or sending its event.

Now each resource a change reaches advances its version and updated_at and sends its own event:

  • DELETE /v1/products/{product_id} sends product_variant.archived for each variant it archives, in the same request as product.archived. A variant that was already archived sends nothing again.
  • DELETE /v1/promotions/{promotion_id} sends promotion_code.archived for each code it archives, shortly after promotion.archived.
  • A product option or value rename sends product_variant.updated for every variant whose selected_options it changes, archived variants included.
  • A product status change between active and inactive sends product_variant.updated for each active variant, whose is_available_for_sale changes.
  • A product image change, including an image moderation result, sends product_variant.updated for each variant without images of its own, whose effective_images change.
  • A product or variant change that reaches a bundle's components[].variant or is_available_for_sale sends bundle.updated for each bundle containing the variant, archived bundles included. That covers a product's name, status, and option names, and a variant's name, sku, status, and selected_options.

Each resource still sends at most one event per request, and never updated beside archived.

What to do: handle product_variant.archived and promotion_code.archived from parent archives the same way as a direct archive, and keep the copy of a variant, bundle, or modifier set with the higher version. Parents now send their own event when a child changes their rollups; see Catalog parents send their own event. Promotion and code availability is still evaluated when you read it. The catalog events list every remaining exception.

  • Breaking change
  • API
  • Webhooks
  • Products
  • Categories
  • Promotions

Catalog parents send their own event when a child changes them#

Previously, a child's change moved its parent's summaries and version without a parent event. A variant write changed its product's price_range or variant_count, a product assignment changed a category's counts, and a code write changed its promotion's codes_summary, and you had to refetch the parent to see it. Redemptions advanced the promotion's and code's version and updated_at without an event.

Now a parent's version advances exactly when a child changes its summaries, and each advance arrives as the parent's own event:

  • A variant create, update, archive, image change, or modifier set assignment that changes its product's default_variant, price_range, active_variant_count, variant_count, is_available_for_sale, or delivery_configuration_status sends product.updated in the same request, beside the variant's own event. Delivery profile bulk assignment does the same for each product it changes.
  • Assigning a product or bundle to a category, removing it, or archiving it sends category.updated with the new counts. So does a promotion starting or stopping to reference a category.
  • Creating, changing, or archiving a promotion code sends promotion.updated when it changes the promotion's codes_summary.
  • A child change that leaves the parent's summaries as they were, such as a variant's sku or a product rename that keeps its categories, no longer advances the parent's version.
  • A redemption or released use changes uses_count without advancing the promotion's or code's version or updated_at, and still sends no event. A busy promotion no longer fails expected_version because a buyer used it.

What to do: apply product.updated, category.updated, and promotion.updated like any other snapshot, and stop refetching parents after child events. Keep the copy with the higher version. Read the promotion when you need a current uses_count. Return policies and reasons still change a category's targeting_reference_count without an event; the catalog events list every remaining exception.

  • Breaking change
  • API
  • Api-keys
  • Errors

One rule decides what a credential can grant#

Every route that grants scopes to another credential now applies the same rule: creating and updating API keys, the sandbox key routes, workload identities, CLI login approval, and partner app install approval. Credentials that can mint keys has the full table.

Breaking: only a full-access key in the target mode (or a live full-access key granting a test credential) or a user session verified within the last 300 seconds can grant accounts.api_keys.write, accounts.workload_identities.write, or commerce.gift_cards.secrets.write. A restricted or read-only key, a CLI login, or a workload token gets 403 FORBIDDEN with details[0].reason full_access_required, even when it holds the scope. param names the first such scope, such as scopes[1]. So a restricted key that manages keys can't mint its own replacement with key management. Keys that already hold these scopes keep them.

Breaking: workload identities apply the same rule in test mode. A test identity that grants one of the three scopes now needs a full-access key or a freshly verified Dashboard session, as a live one did.

Breaking: FORBIDDEN with reason full_access_required now also covers the step-up scopes, and its message says which grant needs full authority.

Breaking: INSUFFICIENT_SCOPE always sets details[0].reason, and the error has no top-level param unless a grant input caused it:

  • scope_not_granted: the credential lacks a scope the endpoint needs. Retry with a credential that holds missing_scopes. A read-only key's message says its access grants read scopes only.
  • scope_not_held: the credential tried to grant, or manage a key holding, scopes it doesn't hold. param is scopes for a grant. Leave those scopes out, or use a larger credential.
  • install_scope_not_granted: a partner app install wasn't granted the scope. Only the merchant can approve it, so error_source is merchant.

Breaking: details[0].scope_requirement matches the operation's published x-flint-required-scopes. An endpoint that needs a read scope reports {"mode": "any", "scopes": ["commerce.products.read", "commerce.products.write"]} instead of {"mode": "all", "scopes": ["commerce.products.read"]}. missing_scopes leaves out a read scope when the write that implies it is also missing, and a message naming more than three scopes gives a count instead.

Breaking: IDENTITY_VERIFICATION_REQUIRED now has details[0].verified_at, when the session last verified its identity (to the minute for Dashboard sessions), and details[0].verification_max_age_seconds, 300. Its param names the input that needed verification, such as access.

Breaking: PATCH /v1/api-keys/{api_key_id} on a revoked key returns 409 ACTION_NOT_ALLOWED with details[0].reason terminal_status and current_status revoked. It returned already_applied, which clients may read as success. Revoking a revoked key still returns already_applied.

Grant checks on PATCH /v1/api-keys/{api_key_id} and PATCH /v1/workload-identities/{workload_identity_id} count only the scopes the update adds. Managing a key still needs every scope the key holds. A workload identity update that keeps a scope the caller doesn't hold no longer fails, but changing its subject or claim conditions, or reactivating it, grants its whole scope set again. POST /v1/api-keys/{api_key_id}/revoke and the workload identity create, update, and delete routes now count against the sensitive_write rate limit, like other credential changes.

  • Breaking change
  • API
  • Invoices

Allocations made on issue report your Idempotency-Key#

This change applies immediately to every supported API version.

When POST /v1/credit-notes/{credit_note_id}/issue applies credit with allocation, the resulting CreditNoteAllocation reports the issue request's Idempotency-Key as idempotency_key. It previously reported issue: followed by that key. This covers new issue results, allocation reads and lists, and webhook payloads, including existing allocations. Replaying an issue request that completed earlier returns its recorded result, which still shows the prefixed key.

To recover a lost issue response, list the note's allocations with idempotency_key=<your issue key>. A filter value that starts with issue: no longer finds an allocation made on issue. If you also used the issue key to allocate from the note directly, the filter returns both allocations. Keys up to 255 characters now fit the filter's published limit, so spec-validating clients can recover allocations made with any valid issue key.

If you stored or compared the issue:-prefixed value, compare the issue request's key instead.

  • Breaking change
  • Webhooks
  • Credit-notes
  • Refunds

Credit note refunds no longer send credit_note.updated#

Breaking: requesting a credit note refund, and each outcome of that refund, no longer sends credit_note.updated or moves the credit note's version and updated_at. The note reads pending_refund_money, refunded_money, latest_refund_status, and the refunded part of available_money from its refunds when you retrieve it. Follow the refund's own refund.* events, which carry credit_note_id, and retrieve the note when you need its current amounts.

credit_note.updated now means the note itself changed: a draft was edited, or an allocation was applied or reversed. Its previous_attributes leaves out available_money; allocated_money shows the allocation's change, and data.object still carries the current available_money.

An explicit expected_version on issue, or expected_credit_note_version on POST /v1/refunds, now conflicts only when the note itself changed: an edit, issue, void, allocation, or reversal. A refund request or outcome since you read the note no longer returns 409 VERSION_CONFLICT. Refunds still can't exceed the credit available when they're accepted: an explicit amount_money above it returns 409 LIMIT_EXCEEDED, and an omitted amount_money is resolved again when the available credit changed, for example after an earlier refund failed.

  • API
  • Tax
  • Settings

Choose a default tax price mode#

PATCH /v1/settings accepts tax.default_price_mode: additive (the default) or inclusive. An order that turns tax on without its own tax.calculation, including checkout and payment link orders, takes it as its tax.price_mode. Subscription orders and renewals stay additive, and orders that already have a price mode keep it.

See Tax settings and Tax-inclusive prices with automatic tax.

  • Breaking change
  • API
  • Webhooks
  • Gift-cards

Gift card events arrive once per change, with previous values#

Previously, gift card events were recorded for each row write, without previous values. A provider callback that reported acceptance and a bounce together sent two gift_card_notification.updated events.

Now Flint compares each gift card, load, redemption, notification, and transaction as its GET returns it before and after a command:

  • Each resource sends at most one event per command. Acceptance and a bounce reported together send one gift_card_notification.updated with status: failed.
  • gift_card.updated, gift_card_load.updated, gift_card_redemption.updated, and gift_card_notification.updated carry data.previous_attributes with the changed fields' earlier values.
  • A command that changes nothing a resource shows sends no event for it. A replayed command sends nothing.
  • Commands send the same event types as before: a capture, refund to the card, load, adjustment, or cash-out sends gift_card.updated beside its child events and a gift_card_transaction.created for each posting.

What to do: deduplicate by event ID and keep the copy with the higher version. Use data.previous_attributes instead of keeping your own copy to find what changed. See gift card events.

  • Tax
  • Orders
  • Invoices

Automatic VAT and GST for the EU, the UK, Australia, and New Zealand, with reverse charge#

Automatic tax now calculates VAT for the 27 EU member states and the UK, and GST for Australia and New Zealand, on digital_goods, software, and saas. Each sale records one vat or gst row with the country as its jurisdiction, carried through invoices, refunds, and row-based reports. Amounts stay in USD.

Tax registration country now accepts EU, GB, AU, and NZ, with state omitted and returned as null. An EU registration carries the non-Union OSS number, EU followed by nine digits, and covers all 27 member states.

In GET /v1/tax-connection coverage, the EU member states, GB, AU, and NZ use category_scope: digital, which covers digital_goods, software, and saas. There, lines in other categories, including physical goods, services, and professional_services, return 400 INVALID_REQUEST with detail INVALID_VALUE on the category, and taxable charges return NOT_ALLOWED on the charge; use external tax for them.

For these destinations, automatic tax sends the customer's matching tax ID to the tax provider only when it's a VAT or GST type in that country's format. An order uses one buyer tax ID, and items going to a country where that ID doesn't apply are charged tax. A tax ID that isn't a VAT or GST type, or doesn't match the format, means tax is charged. You're responsible for checking that a buyer's number is real: neither Flint nor the provider checks that it's registered. When the buyer accounts for the tax, the order records zero-tax rows with taxability_reason: reverse_charge, keeps tax.status: calculated, and sets the new tax.reverse_charge.customer_tax_id. External reverse-charge components set it too, with a null ID when the customer has none for that country. tax.reverse_charge is null otherwise. Issued invoices freeze it as snapshot.tax_reverse_charge, and invoice and credit note PDFs print "Reverse charge" with the buyer's tax ID.

For EU and UK sales, Flint records the buyer's billing country as private location evidence. It isn't returned by the API and never blocks a sale. Irish tax addresses may omit postal_code, and full tax addresses outside the US and Canada may omit state.

See EU, UK, Australia, and New Zealand coverage and Reverse charge for business buyers.

  • Tax

Preparing international automatic tax records#

Flint is preparing automatic tax records for buyer tax IDs, reverse charge, and private country evidence for digital sales. These records will preserve the identity and location evidence used for a calculation.

Automatic tax coverage is unchanged: US orders and Canadian digital products and services. International automatic tax and reverse-charge calculation are not enabled by this preparation. See Sales tax for current coverage.

  • Breaking change
  • API
  • Inventory

Inventory lifecycle actions use their own routes#

The three inventory /transitions routes are removed. Send POST to the route that matches the former action, and remove action from the body:

Previous route and actionNew routeOperation ID
/v1/inventory-reservations/{id}/transitions, commitPOST /v1/inventory-reservations/{inventory_reservation_id}/commitcommitInventoryReservation
/v1/inventory-reservations/{id}/transitions, consumePOST /v1/inventory-reservations/{inventory_reservation_id}/consumeconsumeInventoryReservation
/v1/inventory-reservations/{id}/transitions, releasePOST /v1/inventory-reservations/{inventory_reservation_id}/releasereleaseInventoryReservation
/v1/inventory-counts/{id}/transitions, applyPOST /v1/inventory-counts/{inventory_count_id}/applyapplyInventoryCount
/v1/inventory-counts/{id}/transitions, cancelPOST /v1/inventory-counts/{inventory_count_id}/cancelcancelInventoryCount
/v1/inventory-transfers/{id}/transitions, departPOST /v1/inventory-transfers/{inventory_transfer_id}/departdepartInventoryTransfer
/v1/inventory-transfers/{id}/transitions, receivePOST /v1/inventory-transfers/{inventory_transfer_id}/receivereceiveInventoryTransfer
/v1/inventory-transfers/{id}/transitions, return_to_originPOST /v1/inventory-transfers/{inventory_transfer_id}/return-to-originreturnInventoryTransferToOrigin
/v1/inventory-transfers/{id}/transitions, report_lossPOST /v1/inventory-transfers/{inventory_transfer_id}/report-lossreportInventoryTransferLoss
/v1/inventory-transfers/{id}/transitions, cancelPOST /v1/inventory-transfers/{inventory_transfer_id}/cancelcancelInventoryTransfer

Each body keeps the fields of its former branch: cumulative line targets, optional expected_version, and provenance where it was accepted before. Sending action now returns 400 INVALID_REQUEST with detail UNKNOWN_FIELD. Each route returns the same result as before, keeps its scope, and takes an optional Idempotency-Key. For example:

cURL
curl -X POST https://api.withflintpay.com/v1/inventory-transfers/invtr_1kmn0aExample/depart \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lines": [{ "inventory_transfer_line_id": "invtrln_1kmn0aExample", "target_departed_quantity": 12 }] }'

supported_actions values don't change. Each value is the route segment with hyphens written as underscores, so return_to_origin is /return-to-origin. The OpenAPI request schemas are now one per route, such as DepartInventoryTransferRequest, replacing the InventoryReservationTransitionRequest, InventoryCountTransitionRequest, and InventoryTransferTransitionRequest unions.

An Idempotency-Key now names one request on one route, as on every other operation. Before, a reservation or transfer key used for one action was refused with 409 IDEMPOTENCY_KEY_REUSED on another; now the same key on /commit and /consume, or on /depart and /receive, makes two independent requests.

A refused transfer action no longer names param action, because the body has no such field. Read details[0].reason, current_status, and supported_actions as before.

Regenerate API clients and update calls that send action to the old routes. See Inventory and the Inventory reference.

  • Catalog
  • Price-lists
  • Orders

Customer price-list resolution#

Catalog variant lines now select the customer's active direct price list, then their segment's active list, then the variant schedule. Each line selects its own quantity break and freezes the chosen schedule and source. Wholesale pricing explains setup, supported creation paths, and promotion stacking.

Use catalog_price_behavior: "reprice" with an explicit non-null customer_id to refresh catalog variant lines on an open, unpaid order, including reassignment to another customer. The default keep preserves existing prices. Checkout customer verification and subscription renewals keep frozen prices.

  • Breaking change
  • Orders
  • Fulfillments

Order lifecycle status words and inventory resolution route#

Tip.status and BuyerTip.status now return paid instead of settled when the full tip has been collected. A later refund can still change the status to partially_refunded or refunded. The money fields keep their names, including settled_amount_money and settlement_amounts.settled_tip_money.

TicketedEvent.ticket_status now returns voided instead of void after a full refund releases the order's tickets. Ticket numbers stay on the order if they were issued before the refund. This applies to merchant and buyer order reads.

Resolve an order's inventory exception with POST /v1/orders/{order_id}/resolve-inventory-exception. The former /inventory-exception/resolve route is removed. Keep the same optional reason_message body and commerce.orders.write scope. The response is still the updated order. Merchant orders list resolve_inventory_exception in supported_actions while inventory_exception_status is paid_inventory_failed, including after the order closes; resolving the exception removes that action.

Update route callers and comparisons against the renamed status values. See inventory exceptions, tips, and event tickets.

  • Breaking change
  • API
  • Orders
  • Reports

Order payment completion timestamp and report column rename#

Order.paid_at is when payment_status became paid, including a final capture that releases the remaining balance. It's set once and never changes, even after refunds. It's null while payment_status isn't paid, including on an order whose balance was written off without being paid. Order reads, buyer order reads, order expansions, and webhook data.object snapshots include it.

The orders_itemized_v1, orders_itemized_v2, tax_itemized_v1, and tax_transactions_itemized_v1 CSV reports rename their collection_completed_at column to paid_at. Update CSV parsers to read the new name. Column positions, timestamp values, and report intervals don't change.

tax_transactions_itemized_v2 keeps collection_completed_at, because its rows carry each collection's own completion time rather than the order's.

  • Breaking change
  • API
  • Partners
  • Security

Partner apps mint one token per mode and name the merchant on each request#

Superseded by Auth context describes each credential type.

A partner app now authenticates as itself and names the merchant on each request, instead of keeping a refresh token for every merchant and mode. Existing installs and grants keep working, and no merchant needs to authorize your app again.

These breaking changes apply to every supported API version.

Mint partner app tokens#

  • POST /v1/oauth/token accepts grant_type=client_credentials with your app's client authentication, a client assertion or, when the secret is enabled, the client secret. mode (test or live) is required. merchant_id is optional and binds the token to that merchant; Flint checks only its format.
  • The response has access_token, token_type, expires_in, partner_app_id, mode, and merchant_id for a bound token. Those are the only fields. A test-mode token uses each merchant's test grant instead of a sandbox_id. Sending scope returns 400 invalid_scope.
  • Partner app tokens start with fpat_, are opaque, and last 900 seconds. Mint again when one expires. Each app can mint 600 tokens a minute.
  • The authorization code exchange returns a partner app token bound to the installing merchant and the grant's mode, with the install IDs, and no refresh token. Its expires_in is 900.
  • grant_type=refresh_token from a partner app returns 400 unauthorized_client. Partner refresh tokens and fpat_v1. access tokens stop working; an fpat_v1. token returns 401 INVALID_CREDENTIAL with reason unknown.
  • Discovery metadata lists client_credentials in grant_types_supported.

Name the merchant#

  • Send Flint-Merchant-Id with an app-level token. Without it, a request returns 400 INVALID_REQUEST with detail REQUIRED at Flint-Merchant-Id. A merchant-bound token may omit it, and must match it when sent.
  • Flint-Mode and Flint-Sandbox-Id stay optional and must match the token's mode and the merchant's test grant. A mismatch returns 403 FORBIDDEN with reason context_mismatch, or sandbox_not_accessible for another sandbox. Operations that accept partner app tokens publish the three headers as optional request parameters.
  • When the merchant hasn't installed your app in the token's mode, or revoked the install or the grant, or closed its account, the request returns 403 FORBIDDEN with reason environment_grant_required at Flint-Merchant-Id. This replaces 401 INVALID_CREDENTIAL for those cases, because the token still works for your other merchants. Every cause returns the same body.
  • Flint reads the merchant's grant on every request. A route scope the grant doesn't hold returns 403 INSUFFICIENT_SCOPE with reason install_scope_not_granted, which replaces 401 INVALID_CREDENTIAL after a permission was narrowed. Narrowing, re-authorization, and revocation apply on your next request with the same token.
  • 401 INVALID_CREDENTIAL now means only that the token itself is unknown, expired, or revoked: mint a new one. Deleting the credential that minted a token, disabling the client secret or rotating it with an immediate expiry, and deleting the app revoke the affected tokens.
  • Idempotency keys sent with a partner app token are scoped to the selected merchant's install.
  • GET /v1/auth-context accepts partner app tokens, with the same headers, and needs no scope. It returns auth_type partner_app with the selected merchant_id, environment, the test grant's sandbox_id, the grant's current scopes, and the token's expires_at, so you can confirm a token's mode before a live write. It used to return 401 INVALID_CREDENTIAL with reason wrong_credential_type for partner tokens.
  • Flint-Merchant-Id, Flint-Sandbox-Id, and the minted merchant_id must be Flint IDs in their canonical form, such as mer_01KEZF7C00MPP0T9S0KH5BB4CC: an uppercase 26-character ULID after the prefix. Other values return 400.

Revoke and preview#

  • POST /v1/oauth/revoke revokes the one partner app token you send. Revoking never changes an install or grant.
  • GET /v1/oauth/authorize/preview ignores a single Authorization header, as GET /v1/oauth/authorize does. It no longer refuses partner tokens with 401.
  • Environment grants on partner app installs and environment_grant.* events include partner_app_install_id.

The partner app installs guide covers minting, the selector headers, and every error.

  • Breaking change
  • API
  • Partners
  • Webhooks

Partner apps get only events and scopes they can use#

Flint now forwards an event to an installed-merchant endpoint only when a route that reads the event's resource accepts the install token with the event's scope. A partner app that received report.succeeded couldn't call the report routes to read the report or download its file, because those routes refuse install tokens.

Events that stay with the merchant#

These events now go only to the merchant's own webhook endpoints:

  • report.succeeded and report.failed
  • customer_deletion_request.created, .processing, .failed, .completed, and .rejected

GET /v1/webhook-event-types lists only the merchant source for them, and the OpenAPI webhooks entries for them drop the installed-merchants variant. Partner endpoints that subscribed to them no longer list them in enabled_events, and queued deliveries are suppressed with suppression_reason event_not_allowed. Creating or updating a partner endpoint with one of them returns 400 INVALID_REQUEST. When a customer deletion completes, partner apps still receive customer.deleted.

Scopes partner installs can't request#

A scope is available to partner installs only when a route that accepts install tokens requires it. reports.read, reports.write, webhooks.write, and commerce.tickets.write no longer are. Merchant API keys keep all four.

A permission manifest that requests one returns 400 INVALID_REQUEST with detail NOT_ALLOWED and param naming the scope, such as permission_manifest[0].required_scopes[1]. Apps, installs, grants, and tokens that already hold one keep working with the access it gave on install token routes:

  • webhooks.write reads as webhooks.read.
  • commerce.tickets.write reads as commerce.tickets.read.
  • reports.read and reports.write are dropped. A manifest permission left with no scopes grants nothing.

Remove these scopes the next time you send your manifest, and remove any permission they leave empty. See Edit the permission manifest.

  • API
  • Partners
  • Onboarding

Partner app installs can onboard their merchant in test mode#

A platform can now build and test its whole onboarding flow under a partner app install, and follow live onboarding from the install.

  • Live installs before onboarding. The consent screen no longer stops a live install for a merchant that hasn't finished onboarding.
  • Onboarding scopes for partner apps. A permission manifest can request merchants.onboarding.read, merchants.onboarding.write, and merchants.account_sessions.write.
  • Install tokens on the onboarding routes. With those scopes, an install token reads GET /v1/onboarding/state in both modes. In test mode it also works on POST /v1/onboarding/advance, POST /v1/merchant-account-sessions, and POST /v1/merchant-account-session-refreshes. A token without the route's scope gets 403 INSUFFICIENT_SCOPE.
  • Live onboarding needs an approved platform. In live mode, those three routes return 409 ACTION_NOT_ALLOWED with details[0].reason platform_onboarding_required, resource_type partner_app, and capability merchant_onboarding until Flint approves the app as a platform. Until then, the merchant finishes live onboarding with its own live API key or CLI login.
  • Limits on what an install changes. An install token opens only the account_onboarding and notification_banner components; another component returns 400 INVALID_REQUEST with detail NOT_ALLOWED. It can't change the merchant's account email: profile.email on advance returns 400 INVALID_REQUEST with detail NOT_ALLOWED.

A launch token an install creates is bound to that grant and consent. It survives access token refreshes and stops working once the merchant revokes the install or grant, or authorizes again. Your backend must still authenticate the person and confirm they may manage the merchant before it returns a client secret to the browser.

POST /v1/onboarding/api-key still refuses install tokens with 401 INVALID_CREDENTIAL and reason wrong_credential_type, so an install token's onboarding state reports can_issue_api_key false. See Onboard an installed merchant.

  • Breaking change
  • API
  • Payments
  • Errors

Payment errors name the merchant setup step#

Creating, updating, confirming, capturing, or canceling a payment intent, paying an order, collecting an invoice, and renewing or changing the plan of a subscription now return 409 MERCHANT_NOT_READY with retry none when the merchant or Flint must act before payments can proceed. details[0].reason names the step:

ConditionReasonerror_source
The environment has no active processor accountprocessor_not_configuredmerchant
The processor is still reviewing a payment capabilitycapability_pendingflint
The processor hasn't activated a payment capabilitycapability_blockedmerchant
The processor needs more account informationrequirements_duemerchant
The processor restricted the merchant's paymentsprocessing_restrictedmerchant
Flint hasn't enabled the action for this environmentprocessing_not_enabledflint
Flint lost access to the merchant's processor accountaccount_setup_repair_requiredflint

Read readiness on GET /v1/merchant to find the step, then send a new request once it's done.

When live payments are paused because the merchant hasn't chosen a supported automatic tax category, payment requests now return reason tax_category_required, the same name readiness uses, instead of processing_restricted.

503 PAYMENT_PROCESSING_UNAVAILABLE remains for causes expected to clear on their own, such as a processor account that is still being set up, with retry same_request. Its only reason is now platform_funding_unavailable.

Breaking: these conditions used to return 503 PAYMENT_PROCESSING_UNAVAILABLE with retry same_request and error_source: flint, so a client that retried them kept failing. The tax category pause used to return reason processing_restricted. PAYMENT_PROCESSING_UNAVAILABLE no longer lists capability_pending, capability_blocked, requirements_due, or the other merchant readiness and payment option reasons; they appear under MERCHANT_NOT_READY.

  • Breaking change
  • Webhooks
  • Payouts

Payout transitions send one status event#

Breaking: a payout moving to succeeded, failed, or canceled now sends its specific event without payout.updated alongside it. Other public changes, such as moving to in_transit, send payout.updated. A completed reversal sends payout.reversed. Subscribe to the specific events to follow those transitions. Re-observing the same stored state sends no new event.

When Flint prepares a payout's contents, assigning payout_id now sends balance_transaction.updated for each assigned row. Previously, assigning this field sent no event. Use the event's payout_id to read the complete contents.

Payout and balance events are recorded with their resource changes. A payout created already in a terminal status sends payout.created and that status event. The first time Flint stores a balance, it still sends balance.updated, without previous_attributes. Initial payout-settings observations send no event; later public changes send their updated event. Changes only to a balance's observed_at stay silent. Payout hold changes continue to send balance.updated.

Changing the default payout destination sends payout_destination.updated for each destination whose default flag changes. Archiving a destination sends payout_destination.archived. Reconciliation that corrects a destination to active sends payout_destination.updated; historical status backfills stay silent.

  • Catalog
  • Price-lists
  • Customers

Price lists and customer assignments#

Manage merchant-only price lists with /v1/price-lists. Each list holds up to 10,000 variant prices, with bulk additions of up to 500 prices and optional quantity schedules. Lists can claim up to 20 customer segment labels, with one unarchived list per label in each merchant environment.

Customers now accept a nullable price_list_id for direct list assignment, and the customer list can filter by it. Customer sessions cannot read or change this field.

Set a list's availability with status: active|inactive. DELETE soft-deletes it, returns status: archived, and releases its segment labels. A list directly assigned to customers returns 409 RESOURCE_IN_USE until those assignments are removed. Archived lists remain readable by ID and appear in lists only when the status filter names archived.

The new events are price_list.created, price_list.updated, and price_list.archived. A changed bulk price write advances the list version and emits one update event.

  • Breaking change
  • Catalog
  • Price-lists

Price list schema corrections#

These changes apply immediately to every supported API version.

  • currency on POST /v1/price-lists publishes the same format as every other currency field: three uppercase letters (^[A-Z]{3}$). Flint still accepts only USD and returns INVALID_REQUEST for any other currency.
  • The schema for a single price list response is now named PriceListResourceResponse, replacing PriceListResponse. The fields are unchanged. PriceListListResponse still names the paginated list. If your generated client refers to the old type name, regenerate it.
  • API
  • Refunds
  • Reports

Refund success times, and tax reports name the refund#

Refund, BuyerRefund, and each payment_refunds and tender_allocations entry gain an optional succeeded_at: when that status first became succeeded. It's present only while the status is succeeded, and absent for every other status, including partially_succeeded and a refund a bank rejected after it succeeded. A refund or part that succeeds again shows its first success time. On a refund, it's when its last part first succeeded. A recorded refund's succeeded_at equals its refunded_at. Refund reads and lists, create responses, buyer refund reads, and refund.* webhook snapshots include it.

The tax_transactions_itemized_v1 and tax_transactions_itemized_v2 CSV reports now fill refund_id with the ID of the refund each refund_reversal row reverses, as GET /v1/refunds/{refund_id} returns it. Rows previously carried an ID that no refund endpoint returns. refund_succeeded_at keeps its value, which is the succeeded_at of the refund's tender_allocations entry for the row's payment or gift card. Column names, column positions, and report intervals don't change.

See Tax reports for how each column maps to the refund.

  • Breaking change
  • API
  • Locations
  • Settings

Location settings no longer block archiving#

DELETE /v1/locations/{location_id} now succeeds when the only remaining dependencies are legacy Location settings or policies. Those records no longer produce 409 RESOURCE_IN_USE or a merchant blocker. Other Location dependencies still block archiving.

Effective settings now use merchant settings and defaults. Legacy organization, Location, and device settings no longer contribute, including when an order supplies a device context.

Review merchant settings before relying on values previously inherited from a legacy layer. Read and update the supported configuration through /v1/settings.

  • Breaking change
  • API
  • Errors
  • Returns
  • Fulfillment

Returns validation errors name the input to change#

These changes apply immediately to every supported API version. Error codes, statuses, and messages don't change.

  • Line errors name the line and field, such as line_items[0].buyer_note, line_items[0].requested_quantity, or line_item.requested_resolution_type. When the return reason requires a buyer note and none is sent, the detail code is REQUIRED at line_items[0].buyer_note.
  • Processing a return names the line input, such as line_items[0].received_quantity, line_items[0].inspection, line_items[0].disposition.inventory_location_id, or line_items[0].resolution.quantity, and receipt fields such as receipt.received_at.
  • Return policy revision rules name the revision field, such as revision.release_timing, revision.allowed_resolution_types[1] for a duplicate, revision.return_window.duration_seconds, or revision.scope.channel_types[1].
  • Resolution errors name the line, replacement, or adjustment, such as line_items[1].return_line_item_id, replacement_line_items[0].unit_price_money, or adjustments[0].applied_amount_money.amount. Return previews add the eligibility. or resolution. prefix.
  • Receipt, inspection, and disposition errors name their field, such as line_items[0].unverified_item.name, line_items[0].finding_codes[1], supersedes_return_receipt_id, or inventory_location_id.
  • Metadata errors name the entry, such as metadata.order_ref or metadata["a.b"]. List filter errors name the query parameter, such as status or created_before, and malformed IDs name the path parameter, such as return_line_item_id.
  • Missing inputs report REQUIRED instead of INVALID_VALUE, such as reason when reason_message is sent alone, or inventory_location_id for a stock-producing disposition.
  • Return shipment allocation errors on shipment creation name the failing entry, such as return_line_items[0].return_line_item_id, or return_id.

If you match on param or details[].code, update those comparisons to use these values.

  • Breaking change
  • API
  • Errors
  • Customers
  • Payment-intents
  • Refunds
  • Settings
  • Subscriptions
  • Invoices

Validation errors name the input to change#

These changes apply immediately to every supported API version.

  • Invalid customer email and empty customer name errors name email and name. An invalid buyer_contact.email on order payment names buyer_contact.email, and an invalid fulfillment recipient.email names recipient.email.
  • Metadata key errors and oversized value errors name the entry, such as metadata.order_ref or metadata["a.b"]. Collection size errors name the map itself. Nested maps keep their request path, such as options[0].values[0].metadata.key, line_items[0].modifiers[0].metadata.key, or fulfillment event custom_details.key. Caller-defined map keys keep their exact spelling.
  • Payment intent and refund amount errors name amount_money.amount. An unavailable card saving option on payment intent confirmation names save_payment_method.
  • Customer account settings that send route_templates in Flint hosted mode name customer_account.route_templates.
  • Subscription offer target limits name product_ids or variant_ids, whichever exceeds the limit. Empty target sets return a REQUIRED detail at body that names both alternatives.
  • Subscription billing_start errors name the missing branch field with REQUIRED, or the field from another branch with UNKNOWN_FIELD.
  • An invoice issue value of the wrong type returns INVALID_VALUE at issue, with a message that it must be a JSON object.

If you match on param or details[].code, update those comparisons to use these values.

  • API
  • Subscriptions
  • Promotions

Create and import subscriptions with promotions#

POST /v1/subscriptions accepts an optional promotions array with up to five entries. Identify each promotion by promotion_id or promotion_code. Its current terms are frozen when attached. Set first_cycle to choose its first eligible charged cycle.

Imports also accept consumed_cycles to keep the buyer's remaining discounted cycles. For example, a three-cycle promotion with two cycles already used discounts one more paid cycle. The default first cycle for an import is billing_start.completed_cycles + 1.

Each attachment counts one promotion use and, when sent by code, one code use. This includes an offer's own promotion: POST /v1/subscriptions with offer line items now counts one use toward the offer promotion's max_uses. Create previews report promotion refusals in errors without attaching promotions or counting uses.

See subscription promotions for fields and validation.

  • API
  • Subscriptions

Subscription create previews price first-period proration#

POST /v1/subscription-previews with mode: "create" now accepts prorate_first_period: true instead of returning 400 INVALID_REQUEST. Ineligible combinations come back in errors with detail code NOT_ALLOWED and param: subscription.prorate_first_period, the same refusal creation returns.

Each estimate matches a collection billing makes:

  • first_charge is still the first Flint collection. Without a setup fee, it's the prorated first period, cycle 1, billed now, at trial end, or at starts_at, unless the first paid start is on the anchor day, which makes cycle 1 a full period.
  • recurring is still the first normal full-period collection. With proration, that's cycle 2, billed at the anchor that ends the prorated period.
  • SubscriptionCreatePreview adds first_period_charge, a nullable SubscriptionChargeEstimate. It's the prorated first period when a setup fee in first_charge comes first, because billing collects them as separate orders. It's null when no proration was requested, when the prorated period is already included in first_charge, or when the first paid start is on the anchor day.

The prorated amount uses the same calendar, rounding, and cycle promotions as collection. See Import subscribers from another tool.

  • API
  • Subscriptions
  • Promotions

Apply and remove subscription promotions#

Use POST /v1/subscriptions/{subscription_id}/promotions to apply a promotion by ID or code. Set first_cycle to schedule it or include replace_promotion_id to replace an attached promotion. Remove up to 5 promotions together with POST /v1/subscriptions/{subscription_id}/promotions/remove.

Both routes require commerce.subscriptions.write, accept an optional Idempotency-Key and expected_version, and return the updated subscription. scheduled_promotions lists discounts starting after the next charged cycle, and each attached promotion includes first_cycle. Existing paid orders and the unpaid past_due order keep their prices.

See Discount a subscription.

  • Breaking change
  • Tax
  • Orders
  • Invoices

Tax address and registration fields depend on the country#

state and postal_code on full tax addresses are now required by country. A tax_address, billing_address, or shipping_address tax location needs line1, city, and country, plus state for US and Canadian addresses and postal_code for every country except Ireland. The OpenAPI schema states these rules as conditions on the country. Every address accepted before is still accepted.

Tax registrations for EU, GB, AU, and NZ omit state. The create-registration schema now lists those countries, with CA, as the ones that don't require it. US registrations still require state.

See Tax location and Tax registrations.

  • API
  • Tax
  • Orders
  • Settings

Calculate order tax with your tax calculation callback#

tax.calculation on POST /v1/orders and PATCH /v1/orders/{order_id} takes components_source with mode external: provided (the default) when you send components, or callback when Flint asks the environment's selected tax calculation callback for them. Flint calls on every change that would recalculate tax, including line items, charges, discounts, the customer, the destination, the tax location, and a delivery or pickup selection, and before a payment when the last evaluation is more than 24 hours old. Identical inputs keep one tax_calculation_evaluation_id, and a validated answer is reused for 15 minutes.

The request carries the order's currency, tax location, customer exemption and tax IDs, each unpaid line item and charge with an amount, and, for generated delivery charges, the delivery method, choice group, and pickup store or destination. The response returns line_item_calculations and charge_calculations in the shapes PATCH /v1/orders/{order_id} accepts, plus optional flat order taxes.

Order responses add tax.components_source while tax is external, and tax.callback_evaluation with the tax_calculation_evaluation_id and evaluated_at of the answer in use. A callback order refuses components, tax.line_item_calculations, tax.charge_calculations, and tax.delivery_charge_calculation with 400 INVALID_REQUEST and detail code NOT_ALLOWED, and needs no delivery charge template to offer paid delivery. When the order needs an evaluation and no active callback is selected, the request returns 409 ACTION_NOT_ALLOWED with reason configuration_required and resource_type tax_calculation_callback. When the callback fails, times out, or answers badly, the change returns 502 EXTERNAL_SERVICE_ERROR with reason tax_callback_failed, error_source merchant_endpoint, and retry same_request, and the order is unchanged.

tax.default_calculation in PATCH /v1/settings sets the calculation orders created with POST /v1/orders use when they leave tax.calculation out. Orders that checkout sessions, payment links, invoices, and subscriptions create keep their current tax defaults for now, so tax.default_enabled still needs a tax connection with any default, and a callback default also needs a selected callback.

  • API
  • Payment-links

Collect an attendee name for each event ticket#

Event payment links have a new setting, event_config.collect_attendee_names, which is false by default. When it's true, POST /v1/payment-links/{payment_link_id}/resolve requires attendee_names: one name per ticket, in line_items order, skipping tiers the buyer didn't choose.

  • Flint trims each name, which must then be 1 to 200 characters.
  • A missing list returns 400 with param attendee_names.
  • A list with the wrong number of names returns INVALID_VALUE at attendee_names. An empty or too-long name returns INVALID_VALUE at its position, such as attendee_names[1].
  • When the setting is off, you can still send attendee_names. Flint validates them the same way.

Hosted Checkout asks for the names itself: with the setting on, buyers enter one name per ticket before they continue, and the field count follows the quantities they choose. In the Dashboard, turn on Collect attendee names in a payment link's event settings. Headless callers send attendee_names themselves.

When the payment succeeds, Flint sets each ticket's attendee_name, and the ticket.created webhook includes it. Names never appear in order or checkout metadata, and Flint redacts attendee_names from request logs. If the order's ticket count changed after checkout started, Flint still issues the tickets, with no names.

See Sell event tickets.

  • API
  • Payment-links
  • Webhooks

Check in, void, and edit event tickets#

Event tickets now accept changes. Each one needs the commerce.tickets.write scope, which doesn't include access to orders or refunds.

  • POST /v1/tickets/{ticket_id}/check-in admits an issued ticket. Send the scanned admission_code to confirm it belongs to the ticket, or send no code to check the ticket in by hand. check_in_method records which. Each ticket is admitted once: a repeated or concurrent check-in returns 409 ACTION_NOT_ALLOWED with reason already_applied, and a wrong code returns 400 INVALID_REQUEST with detail INVALID_VALUE at admission_code without changing the ticket.
  • POST /v1/tickets/{ticket_id}/undo-check-in returns a checked-in ticket to issued and clears its check-in fields.
  • POST /v1/tickets/{ticket_id}/void permanently voids a ticket and frees its seat. The event link's total_quantity_sold drops by one, as it does for a refund, without changing the link's version. Nothing is refunded, and a later full refund of the order frees only the seats of its remaining valid tickets.
  • POST /v1/tickets/{ticket_id}/rotate-code replaces a ticket's admission code and returns the new code in admission_code. A retry with the same Idempotency-Key within 24 hours returns it again while the ticket is unchanged.
  • PATCH /v1/tickets/{ticket_id} sets attendee_name, or clears it with null.

Tickets now publish supported_actions: check_in and void while issued, undo_check_in and void while checked_in, and none once voided. Every change accepts an optional expected_version; a stale one returns 409 VERSION_CONFLICT before any other refusal, so door scanners usually omit it. A voided ticket refuses every other change with reason unsupported_state; voiding it again returns already_applied.

Flint sends two new webhook events with the ticket as data.object: ticket.checked_in when a ticket is checked in, and ticket.updated for an attendee name edit, an undone check-in, or a replaced code. ticket.voided now also reports a ticket you void. None of them carries the admission code.

expand=sales_summary on a payment link adds checked_in_ticket_count, the number of its tickets checked in when you read it.

See Tickets.

  • Breaking change
  • API
  • Errors

Validation errors list every invalid input#

These changes apply immediately to every supported API version.

  • Flint checks the path, query parameters, and body together against the endpoint's published request schema right after authentication and the header checks. One 400 INVALID_REQUEST lists every input that breaks the schema, up to 50, so a request with several mistakes is reported once instead of one mistake at a time. Rules that compare inputs with each other or with stored data run after the request passes the schema and still report the first rule that fails.
  • details is sorted by location (path, then query, then body) and then by param, so details[0], and with it the top-level param and message, can name a different input than before.
  • When more than one input failed, the top-level message is details[0].message followed by a count, such as "2 more inputs are invalid; see details."
  • A request that breaks a constraint the request schema publishes, such as an enum, a length, an ID format, or a required field, now gets 400 INVALID_REQUEST even where an endpoint used to accept it or to answer with a later error such as 404, 409, or the demo session 429. In particular:
    • Currency codes match exactly, with no case folding: ?currency=usd and a lowercase currency in a body are refused. Send USD.
    • null is refused on a create field that can't be cleared, such as {"name": null} on POST /v1/customers. Leave the field out instead.
    • Retired request names are refused: gift_card_code on POST /v1/orders/{order_id}/gift-cards (send code), and the earlier inventory adjustment reasons received_stock, damage, manual_correction, and other with their *_quantity_delta line fields (send a current reason and its line fields).
  • A POST whose body fields are all optional now publishes requestBody.required: false and accepts an absent body the same as {}. This covers 36 operations, such as issueInvoice, collectInvoice, the fulfillment and package verbs, and createCustomer.
  • Validation messages for schema failures use one wording per kind of failure, such as "name is required.", "status must be one of: open, closed.", and "variant_id must be a variant ID, which starts with var_." A map of IDs reads "variant_selections.size must be an ID that starts with var_." An empty PATCH names every field it accepts: "Send at least one of name, phone."
  • details[] items on INVALID_REQUEST no longer carry remediation. Use the error's own remediation, which applies to every input.

Read Validation errors for the order and the message format. Show each details[].message at its param, and don't match on message text.

  • Tax
  • Invoices

EU and UK VAT in local currency on invoices and credit notes#

When an issued invoice has VAT above zero for an EU member state or the UK, issue now converts that VAT into the country's currency and freezes it in snapshot.tax_currency_conversions. Each entry has currency, exchange_rate, rate_date, rate_source, tax_money, and taxable_money. EU VAT uses the ECB euro reference rate, the latest on or before the issue date, with other currencies converted through the euro. UK VAT uses HMRC's exchange rate for the month of issue. Each amount is added up in USD, multiplied by exchange_rate, and rounded half up to the currency's minor units.

Credit notes reuse the invoice's rate in their own tax_currency_conversions. The invoice and credit note PDFs print the converted VAT, the converted taxable amount, and the rate with its source. Orders, receipts, and reports stay in USD.

Issue and create-and-issue can now return 503 SERVICE_UNAVAILABLE when the rate for the issue date isn't available. Nothing is issued; retry later with the same Idempotency-Key.

See VAT in local currency.

  • Breaking change
  • API
  • Checkout
  • Webhooks

Checkout sessions send checkout_session.updated#

New event type: checkout_session.updated. It fires when a checkout session changes without entering a new status, for example when the buyer saves their contact, you change metadata or external_reference_id, subscription terms change, or a relaunch gives the session a new return URL or page origin. Each new session version now arrives as an event. A change that only moves the session to a new status sends that status event, never checkout_session.updated beside it.

Partner apps receive checkout_session.updated with the checkouts.checkout_sessions.read permission, like the other checkout session events.

Other changes for every supported API version:

  • Checkout session, payment link, and delivery_selection.committed events are recorded in the same transaction as the change, and each event's data.object is the resource as of that change. Change events carry data.previous_attributes.
  • checkout_session.paid is sent with the session's own transition to paid. Replaying a settled payment sends no second event.
  • Updating a checkout session's metadata or external_reference_id to the values it already has keeps its version and updated_at and sends nothing.
  • A session's customer_id, subscription_plan_id, custom_field_answers, and payment_intent_ids come from its order, so changes to them alone send order.* or payment_intent.created. A payment link's completed_count and total_quantity_sold change with sales and send no payment link event.

See the checkout session events.

  • Breaking change
  • Webhooks
  • Customers
  • Invoices

Customer deletion events follow each resource's state#

Breaking: when a customer deletion cancels a pending invoice email, the delivery attempt now sends invoice_delivery_attempt.failed with failure_reason: "canceled". Previously the cancellation sent no event. The recipient is erased in the same step, so the event carries no to_email or cc_emails, and data.previous_attributes holds only the earlier status and failure_reason.

Breaking: erasing a deleted customer's data no longer advances the version or updated_at of a record whose GET doesn't change. This covers a checkout session where only the verified email or phone was erased, and orders, invoices, payment intents, fulfillments, payment methods, subscriptions, payment reviews, and fraud warnings that held none of the erased values. Erasure still sends no event for these records; the deletion request's events cover it.

customer_deletion_request.*, customer.updated (on approval), and customer.deleted are now recorded with the write that caused them, and each event's created_at is when Flint recorded it. customer_deletion_request.processing, .failed, .completed, .rejected, and customer.updated carry data.previous_attributes. customer.deleted carries none, so no erased value reaches it. Repeating a deletion request, repeating a decision, or retrying a completed deletion sends no new event.

  • Breaking change
  • Webhooks
  • Customers

Customer events follow the customer's version#

Breaking: a customer write that changes no field no longer sends customer.updated and no longer advances the customer's version. This covers a PATCH /v1/customers/{customer_id} that repeats the current values, and a saved address default that leaves the customer's billing_address or shipping_address unchanged, such as moving the default between two addresses with the same postal address. Previously each of these advanced version and sent customer.updated with the same fields.

customer.created, customer.updated, and customer_email_preferences.updated are now recorded with the customer write that caused them. Each event's created_at is when Flint recorded it. customer.updated and customer_email_preferences.updated carry data.previous_attributes, except a preference event sent when a customer without an email address gets one. Retrying the same write sends no new event.

  • Breaking change
  • API
  • Fulfillment
  • Webhooks

Fulfillment events follow the stored fulfillment#

Fulfillment, shipment, package, and fulfillment event webhooks change for every supported API version:

  • A fulfillment created under a payment hold sends one fulfillment.created whose snapshot has status: on_hold and active_hold. Before, the same request also sent fulfillment.updated.
  • Updating a fulfillment with the values it already has sends no event and keeps the fulfillment's version and updated_at. Before, it advanced the version and sent fulfillment.updated.
  • Each event's snapshot is the resource as GET returned it when Flint recorded the event, in the same request that changed it.

supported_actions on a fulfillment, shipment, or package is read from other resources when the event is recorded, so a change to it alone sends no event: a fulfillment's follows order.paid, payment_intent.fulfillment_hold_updated, and its shipments' shipment.* events, and a shipment's or package's follows its fulfillment's fulfillment.* events and, for a package, shipment.updated.

Editing a package's items still sends package.updated with the package's version advanced. The package snapshot doesn't contain items, so the event has no previous_attributes.

See the fulfillment event catalog.

  • Breaking change
  • Webhooks
  • Invoices
  • Credit-notes

Credit note allocations update the credit note#

Breaking: applying a credit note allocation after issue, or reversing one, now sends credit_note.updated alongside credit_note_allocation.created or credit_note_allocation.reversed. The allocation changes the note's allocated_money and available_money and advances its version, so the note sends its own event. Previously only the allocation and the invoice sent events. Issuing with allocation still sends credit_note.issued without credit_note.updated.

A credit note patch that changes nothing no longer sends credit_note.updated and keeps the note's version.

Credit note, allocation, manual payment, invoice payment attempt, and invoice delivery attempt events are now recorded with their resource changes. Each event's created_at is when Flint recorded it, not the manual payment's received_at or the email provider's completion time. Change events carry data.previous_attributes. Retrying the same outcome sends no new event.

  • Breaking change
  • API
  • Orders
  • Webhooks

Order amount changes send order.updated#

Order webhook behavior changes for every supported API version:

  • A payment that changes the order's paid amount while payment_status stays the same now sends order.updated. For three partial payments that pay an order in full, the first sends order.partially_paid, the second sends order.updated, and the last sends order.paid and order.closed. Reversing a manual payment that lowers the paid amount without a status change also sends order.updated. Before, these changes sent no order event.
  • order.paid and order.partially_paid fire only when payment_status changes to the named value, on every path: card and wallet payments, manual payments, gift cards, zero-balance completion, and payment recovery. Replaying a settled payment sends no new order event.
  • An order created already paid or closed sends order.paid or order.closed with order.created in the same commit. An order created open and unpaid sends only order.created.
  • A write that changes no field of the order, such as saving it unchanged or repeating the current notes, sends no order event and keeps the order's version and updated_at. Before, these advanced the version, and some sent order.updated.
  • Four writes that changed the order without an event now send order.updated: the buyer contact a payment start records (buyer_contact), adopting a customer for an order that has none (customer_id), freezing the delivery destination when a manual payment is recorded on the order's invoice (delivery_destination.frozen_at), and a checkout created with its default shipping option, which now sends one order.created whose snapshot includes the shipping charge.
  • The envelope created_at of order.inventory_exception_created and order.inventory_exception_resolved is when Flint recorded the event. Before, it was the exception's own time, which stays on the order as inventory_exception_updated_at.

Some order fields are read from other resources when the event is recorded, so a change to them alone sends no order event: supported_actions and authorization_amounts (follow payment_intent.*), gift_cards, gift_card_estimate, and each line item's purchased_gift_cards (follow gift_card.* and gift_card_redemption.*), return_credit_settlements (follow return_resolution.updated), and governing_delivery_selection_id (follow delivery_selection.committed). A card dispute changes no order field, so it sends dispute.* events but no order event. Order event payloads carry each line item's image as GET returns it.

Subscribe to order.updated alongside the order status events to keep order amounts current. See the order event catalog and Refunds.

  • Breaking change
  • API
  • Subscriptions

Prorate an anchored first subscription period#

Existing requests are unaffected. Omitting prorate_first_period or sending false keeps the existing behavior. The new eligibility rules apply only when the flag is true.

POST /v1/subscriptions now accepts prorate_first_period: true for monthly or yearly subscriptions with a Flint billing schedule, billing_anchor_day, and no shipping. The flag defaults to false and is returned on Subscription responses and webhook snapshots.

The first paid period ends at the nearest future anchor day in the current or next month, even for yearly billing or an interval count greater than 1. A start on the anchor day buys a normal full period. Its item price uses the fraction of the full anchored interval covered, with actual calendar dates and half-up rounding. Trials and scheduled starts prorate from their first paid start. Setup fees remain full, and imported starts are not eligible. Ineligible combinations return 400 INVALID_REQUEST, detail code NOT_ALLOWED, with param: prorate_first_period.

Before the first prorated payment is paid, changes to the billing interval, interval count, or anchor return 409 ACTION_NOT_ALLOWED with reason first_period_unpaid. A plan change that keeps those terms is allowed.

First-period proration covers eligibility, examples, and next_renewal estimates.

  • API
  • Payments

Send the buyer's IP address when your server pays#

POST /v1/orders/{order_id}/pay with action: "pay" and POST /v1/payment-intents/{payment_intent_id}/confirm accept an optional buyer_ip_address. Send the buyer's IPv4 or IPv6 address when your server pays with an API key or partner token. Flint uses it as the payment's ip_address for risk rules and lists, and declining the payment's review with add_to_block_lists adds it to default_block_ip_addresses. Pay and confirm responses don't return it; the payment's review shows it as ip_address. For an ACH debit paid with a Stripe ConfirmationToken, the address in the token's mandate acceptance is used instead.

An IPv4-mapped IPv6 address is stored in its IPv4 form, the same as ip_address list items. Any other value returns 400 INVALID_REQUEST with detail code INVALID_VALUE and param buyer_ip_address. The checkout credential can't send it and gets 400 INVALID_REQUEST with detail code NOT_ALLOWED. Requests without it work as before, except that order payments made with a CLI or workload token now also record no buyer IP, as API keys and partner tokens already do. See Send the buyer's IP from your server.

  • Breaking change
  • API
  • Subscriptions

Preview buyer subscription quantity changes#

Clients that switch on mode in POST /v1/me/subscription-previews results must handle quantity_change, which returns SubscriptionQuantityChangePreview. It appears only when the request sends mode: "quantity_change".

POST /v1/me/subscription-previews accepts mode: "quantity_change" with subscription_id, billing_starts: "prorated_now", line_items, and optional expected_version. It returns the same quantity_change preview as POST /v1/subscription-previews, with the amount buyer change-quantity would charge now in renewal.total_money.

The preview needs a full customer session and applies the buyer route's rules: only the frozen line with allow_quantity_adjustment: true, within its min_quantity and max_quantity, and only a line that doesn't ship. Requests the buyer route would refuse fail the same way. The preview saves nothing and takes no Idempotency-Key. See Preview a buyer quantity change.

  • API
  • Tax
  • Delivery

Choose a delivery charge tax basis#

PATCH /v1/settings accepts tax.delivery_charge_tax_basis: full_charge (the default) or taxable_items_share. With the latter, automatic tax uses discounted gross taxable merchandise as a share of all merchandise in each fulfillment group, rounded half up, for shipment, local delivery, and pickup charges. A method's taxable: false still wins. Direct order charges and external tax keep their existing behavior.

You can save the setting now. It takes effect only when Flint enables the capability; until then calculations use the full charge. Open orders then use the setting at their next calculation, while committed tax keeps its original basis.

See Delivery charge tax basis.

  • API
  • Delivery

Delivery methods and rate callbacks show when their current revision is revoked#

DeliveryMethod and DeliveryRateCallback now include delivery_revocation_id. It names the delivery revocation that fences the resource's current revision, and is null when that revision isn't revoked. A revocation doesn't change status, so a revoked method still reads active; use delivery_revocation_id to tell them apart. Publishing a new revision ends a fence on the old revision, so the field reads null again, unless an older revocation without a revision fences the resource itself; that revocation still applies to every revision and stays named. The field covers only the resource's own revision: a method can also be unusable because its rate callback, signing key, or a Location's address is revoked, and then its quotes report unavailable_reason: dependency_revoked while the method reads null.

The field appears on every read and write response for these resources, and in delivery_method.* and delivery_rate_callback.* webhook payloads.

  • API
  • Orders
  • Invoices

Backdated manual payments preserve order update times#

Superseded by Order update times use wall-clock time.

Recording or reversing a backdated manual payment on an invoice now sets the order's updated_at to the time you record it. Previously it moved forward by only one second from its last value. The payment's received_at and reversed_at, and the delivery destination's frozen_at, keep their business meaning. Invoice timestamps already worked this way.

  • Breaking change
  • API
  • Delivery
  • Checkout
  • Subscriptions

Revoked delivery methods can't be added to new checkouts, links, or plans#

Writes that add a reference to a delivery method now refuse a method whose current revision, the rate callback revision or signing key it prices with, or the address of a Location it uses has been revoked. They return 409 ACTION_NOT_ALLOWED with reason dependency_revoked, retry none, and details[0].blocking_resources naming the method and the method, rate callback, or Location that holds the revoked part. Previously these writes accepted the method, and every checkout that offered it then failed to quote.

The refusal applies when you add the method to checkout.default_delivery_method_ids in settings, to a checkout session's or payment link's delivery_method_ids, or to a subscription plan's or offer's subscription_delivery_method_ids, when a subscription's delivery.delivery_method_id changes to it, and when it's a delivery method migration's to_delivery_method_id. Places that already list the method keep it. Its status doesn't change, and checkouts show it as unavailable until you publish a corrected revision.

Test deliveries and connection checks on a revoked rate callback revision or signing key now return reason dependency_revoked instead of terminal_status.

Subscription renewals on a revoked method are held with delivery_hold.reason method_unavailable and subscription.delivery_action_required, including when it's the only method offered, which previously reported destination_not_served. When no other method is offered, the hold's fixable_by is merchant, because the buyer has nothing to switch to. Publishing a corrected revision clears the hold at the next check.

  • Breaking change
  • API
  • Subscriptions
  • Webhooks

End a subscription after a number of cycles or on a date#

Subscriptions and subscription plans now accept end_after, which ends a subscription automatically. It is null, or one of two forms:

  • {"type": "cycles", "cycle_count": 12}: the subscription ends when completed_cycles reaches the count, at the end of that period. cycle_count is 1 to 1,200.
  • {"type": "date", "end_date": "2027-06-30", "timezone": "America/New_York"}: the subscription ends at the last billing boundary on or before end_date, and Flint never charges a period that would cross it. Only a period the buyer has already paid for runs past the date. A trial or unpaid period that crosses it ends at the close of end_date. The timezone comes from the request, then the merchant's reporting_timezone, then UTC, and Flint stores the one it used.

A plan can set the cycles form as the default for new subscriptions. On create, omitting end_after takes the plan's default and null means no end. Imports accept it too. PATCH /v1/subscriptions/{subscription_id} replaces the whole value, null clears it, and expected_version is required whenever the request includes end_after. Buyers can read end_after but not change it. A cycle_count below completed_cycles, or an end_date before the date of current_period_end_at, returns 400 INVALID_REQUEST with detail code INVALID_VALUE.

Subscriptions report two new read-only fields: remaining_cycles, and expires_at, which is null only when the end can't be determined or the subscription is canceled. While no charge is scheduled (paused with no resume time, or an external schedule with no date), a date end, a reached cycle limit, and a known scheduled cancellation keep their expires_at. Only a cycles end with cycles still left has none, while remaining_cycles counts them. Both are null on a canceled subscription.

  • A paid period is never cut short, and reaching the end never refunds a payment.
  • Pause and skip don't use up cycles. They move a cycles end later and leave a date end where it is.
  • At the end, the subscription becomes canceled with the new cancellation_reason value end_after_reached. cancellation_details is null, a scheduled plan change is dropped, and Flint sends subscription.canceled.
  • In the final cycle, Flint sends the new subscription.end_upcoming event and an ending email to the buyer instead of subscription.renewal_upcoming.
  • In the final cycle, POST /v1/subscriptions/{subscription_id}/renew and a now plan change return 409 ACTION_NOT_ALLOWED with reason end_after_reached, and the next_renewal preview reports billing_at: null.

A plan's contract term stays advisory and doesn't end a subscription. cancellation_reason can gain values, so handle ones you don't recognize.

See End automatically and the Subscriptions reference.

  • API
  • Subscriptions

Read frozen buyer quantity policies on subscription lines#

Subscription plan lines now accept allow_quantity_adjustment, min_quantity, and max_quantity on create and PATCH collection replacement. At most one line may allow buyer adjustment. Adjustment defaults to false; bounds default to 1 and 9,999 and must enclose the plan line's quantity.

Merchant and buyer subscription reads expose the frozen policy on each line. Checkout subscription_terms.line_items, payment-link subscription_preview.line_items, and scheduled_plan_change.line_items expose the identified lines and their policies. Existing subscriptions and checkout snapshots keep their captured terms when a plan changes.

The existing subscription quantity multiplier and quantity_options are unchanged. This addition does not add a buyer line-quantity command. See Buyer line quantity policy and Frozen line quantity policy.

  • Breaking change
  • API
  • Subscriptions

Schedule subscription line quantity changes#

Clients that switch on billing_starts in change-quantity results must now handle next_renewal and period_end, in addition to prorated_now.

POST /v1/subscriptions/{subscription_id}/change-quantity now accepts next_renewal and period_end alongside prorated_now. next_renewal changes quantities immediately without charging. period_end stores a quantity-only scheduled_plan_change that applies once at the next billing boundary. Cancel it with PATCH {"scheduled_plan_change": null}. Both timings allow physical lines; the existing prorated shipping restrictions remain.

Buyers can use POST /v1/me/subscriptions/{subscription_id}/change-quantity with line_items, billing_starts (period_end or eligible prorated_now), and optional expected_version. It requires a full customer session and an Idempotency-Key. Only the frozen adjustable line can change, within its frozen min_quantity and max_quantity. The update_quantity action points to this route and follows that policy.

A pending change locks quantity edits with plan_change_scheduled. Merchant and buyer routes retain separate durable idempotency identities. The subscription multiplier, buyer PATCH quantity, and merchant line PATCH quantity remain available. See Subscription quantity changes.

  • API
  • Payments
  • Webhooks

Authorization warnings before capture deadlines#

payment_intent.authorization_expiring warns once per authorization before its effective authorization_expires_at. It is a notification event with the PaymentIntent snapshot, and does not change the resource version.

The warning is due 24 hours before expiry, or halfway through a hold shorter than 48 hours. The warning is not sent when less than one hour remains, so windows under two hours never warn. A deadline change does not repeat a warning. Read the current PaymentIntent, then capture or release it before the deadline.

See Authorization expiry and the webhook events catalog.

  • Breaking change
  • API
  • Orders
  • Checkout
  • Payment-links
  • Subscriptions
  • Tax

Automatic tax country coverage matches accepted locations#

order.tax.supported_countries now returns ["US"] when automatic tax is enabled, replacing ["CA", "US"]. The same coverage applies to automatic-tax locations in orders, checkout sessions, payment links, and subscription billing. Canadian destination locations already failed in orders; the advertised coverage now matches the locations Flint accepts throughout a purchase.

Seller origins must also be within automatic tax coverage, even when tax account setup accepts their country. An unsupported seller origin returns a validation error before calculation.

Use this array for a tax address picker. For shipping, intersect it with the delivery input's constraint.supported_countries across choice groups. Use external tax for destinations outside automatic tax coverage. Delivery with tax off or external tax keeps its existing country coverage.

This correction applies across supported API versions. Tax off and external tax continue to omit tax.supported_countries.

  • API
  • Tax
  • Payments
  • Orders

Automatic tax works with manual capture#

An order that uses automatic tax can now be paid with a manual-capture leg. Previously, paying such an order with "capture_method": "manual" returned 400 INVALID_REQUEST with detail code NOT_ALLOWED. No request or response fields changed.

Tax is fixed when the hold is placed. Flint checks that the order's tax calculation is current when you confirm the leg. Capturing while the hold is open never recalculates tax, and the sale is taxed as of the authorization date, even when you capture on a later date.

A partial capture is the final bill for that authorization. The captured money carries its allocated share of the tax, and the uncaptured part is released as before. A hold that is canceled or expires before any capture collected nothing, so the next payment for the order calculates tax again.

The capture deadline is unchanged. authorization_expires_at still publishes the effective deadline, and a capture at or after it is refused.

Orders with automatic tax still need a single payment for the full balance. Deposits, installments, split payments, and partial payments aren't supported. See Automatic tax on a held order and Manual capture.

  • API
  • Orders
  • Invoices
  • Tax

Automatic tax works with deposits, installments, and split payments#

Orders and invoices that use automatic tax can now be paid in parts. This covers a deposit followed by the balance, several payment intents, a gift card plus a card, several partial manual payments, and invoice payment schedules with a deposit and installments.

Flint commits an order's tax at its first accepted payment, whether a payment intent, a recorded manual payment, or a gift card. An invoice commits it at issue, as before. Later payments collect their share of the committed tax however much later they arrive, and keep collecting after you change tax settings or disconnect automatic tax. Connecting or disconnecting no longer marks an order with committed tax as incomplete. Only tax that isn't committed yet is revalidated.

A line item or charge added after the commitment gets its own calculation, which commits at its first payment. Changing the amount, quantity, tax category, taxability, or tax location of a committed line item or charge returns 409 ACTION_NOT_ALLOWED with reason payment_collected, as with external tax. Refunds reverse the tax of the payment they refund. To undo a manual payment, reverse that payment in full by its ID; there is no amount to reverse part of one.

Automatic tax no longer refuses a payment for less than the balance, a second payment, more than one payment intent, an invoice schedule with more than one entry, or a partial manual payment. Manual capture keeps the order's committed tax. The other limits on automatic tax remain. See Payments in parts and Payment schedules.

  • Breaking change
  • API
  • Checkout
  • Delivery

Checkout sessions no longer expose delivery dependency pins#

Newly rendered checkout sessions no longer return delivery_pinned_dependencies. The CheckoutDeliveryPinnedDependency schema has also been removed. This applies to checkout reads, lists, creates, expanded checkout sessions, and checkout event objects for both merchant and buyer credentials.

Remove code that reads this field. Use delivery_method_ids to identify the session's delivery methods, and delivery quotes and selections to present delivery choices. Delivery pin validation and delivery admission behavior are unchanged.

Responses and events stored before this change keep delivery_pinned_dependencies when replayed or redelivered, until the idempotency key expires or the event ages out.

  • Breaking change
  • API
  • Api-keys
  • Oauth

Context headers must match fixed credentials#

Flint-Merchant-Id, Flint-Mode, and Flint-Sandbox-Id now assert the context of an API key, CLI login token, workload token, onboarding session, checkout token, customer session, or invoice access token. Absent or matching headers pass. A conflicting header returns 403 FORBIDDEN with details[0].reason: context_mismatch, retry: none, error_source: caller, and param naming the header. Flint checks this before handlers, writes, and idempotency replay. Sandbox assertions use the public sandbox ID. A live credential cannot name a sandbox.

Previously, some credentials silently ignored conflicting headers. Remove those headers or use a credential bound to the requested context. Dashboard context selection is unchanged. The legacy Flint-Merchant-Environment-Id assertion on CLI tokens still checks their bound environment.

The reason oauth_context_mismatch is removed without an alias. Update error handling to read context_mismatch.

OAuth credential exchanges now reject repeated Authorization fields, including identical values, with 400 INVALID_REQUEST, detail NOT_ALLOWED, and param: Authorization. Send one header.

Send each context header once, including the legacy Flint-Merchant-Environment-Id. Repeated fields, even with identical values or an empty first value, return 400 INVALID_REQUEST, detail NOT_ALLOWED, with param naming the header. Header names are case-insensitive.

  • Breaking change
  • API
  • Delivery
  • Orders

Delivery inputs use request paths and pickup uses inventory_unavailable#

Delivery input paths now match the request properties and error params your integration uses:

  • In DeliveryInputRequirement.field_path and every delivery method configuration's quote_input_fields, replace buyer_location.line1, buyer_location.line2, buyer_location.city, buyer_location.state, buyer_location.postal_code, and buyer_location.country with buyer_location.address.line1, buyer_location.address.line2, buyer_location.address.city, buyer_location.address.state, buyer_location.address.postal_code, and buyer_location.address.country.
  • Update delivery method create and update requests to send the new paths. Reads of existing methods and revisions return the new paths.
  • In DeliveryInputRequirement.field_path, replace caller_supplied_rates with method_results, the quote request property that accepts caller-supplied outcomes.
  • Keep buyer_location.coordinate, buyer_location, and array templates such as choices[].input.delivery_window_id as they are.

For POST /v1/delivery-previews with mode: pickup_locations, candidate_outcome.unavailable_reason now uses inventory_unavailable in place of inventory_insufficient. This matches delivery-options previews and delivery quotes. Pickup outcomes use eligibility_no_match when eligibility rules exclude a location and inventory_unavailable when it cannot supply the requested inventory. Update any comparison against the old reason. The error code INVENTORY_INSUFFICIENT keeps its name.

See Delivery quotes, Delivery previews, and Delivery rate callbacks.

  • API
  • Orders
  • Refunds

Take unshipped items off a paid order#

POST /v1/orders/{order_id}/edits takes unshipped items off a paid order. Send expected_order_version and remove_line_items, each with an order_line_item_id and a whole quantity. Add charge_refunds to refund a charge such as delivery, destinations to choose where the original payments go back to, a reason, and an internal note of up to 500 characters. The route requires an Idempotency-Key and both commerce.orders.write and commerce.refunds.write.

In one step, Flint removes the units, releases the stock committed to them, records an order_edited activity, and refunds their value, including their share of discounts and tax, to the payments that paid. The response is 201 with the immutable order_edit (oed_), the updated order, and the refunds. If Flint can't finish creating the refund during the request, refunds is [] and refund.created follows once it exists. A new order_edit.created webhook reports the edit. GET /v1/orders/{order_id}/edits and GET /v1/orders/{order_id}/edits/{order_edit_id} read edits back.

Only unassigned_quantity can come off. A unit in a fulfillment has to leave it first with fail and release_quantity: true, and units that were dispatched or delivered use a Return. Units with a value of zero, such as a fully discounted item, are still removed and recorded, and an edit that comes to zero creates no refund. Orders paid by invoice, created by a subscription or a return, or with a disputed payment can't be edited. A refund an edit creates carries the new Refund.order_edit_id.

The edit's note is internal. It never becomes the refund's reason_message and isn't on the buyer's receipt. See Edit a paid order.

  • API
  • Payment-links
  • Webhooks

Event tickets are individual records you can read#

Each ticket sold through an event payment link is now a ticket with its own ticket_id, prefixed tkt_. Flint creates one for every ticket a buyer purchases, when it issues the ticket numbers. A ticket records its order, payment link, and ticket tier, its ticket_number, and a status of issued, checked_in, or voided. It also carries an optional attendee_name, the last four characters of its admission code in admission_code_last4, and a version.

  • GET /v1/tickets lists tickets, newest first. Filter by payment_link_id, order_id, status, checked_in_after, and checked_in_before, search with query, sort by created_at or attendee_name, and add expand=order.
  • GET /v1/tickets/{ticket_id} retrieves one ticket.
  • POST /v1/tickets/lookup takes an admission_code in the request body and returns its ticket, including a voided one. A malformed code returns 400 INVALID_REQUEST with detail INVALID_VALUE, and an unknown code returns 404 RESOURCE_NOT_FOUND, both at admission_code.

These routes need the new commerce.tickets.read scope, which doesn't include access to orders or refunds. expand=order also needs commerce.orders.read.

Admission codes are secrets. No merchant read, list, or webhook includes one, and Flint redacts them from request logs.

A full refund now voids the order's remaining tickets and lowers the payment link's total_quantity_sold only by the tickets that were still valid. The order's ticketed_event is unchanged.

Flint sends two new webhook events with the ticket as data.object: ticket.created for each ticket it issues, and ticket.voided when a refund voids one.

See Read individual tickets.

  • API
  • Inventory

Inventory items record a backorder policy and backordered quantity#

Backorder policy on inventory items#

POST /v1/inventory-items and PATCH /v1/inventory-items/{inventory_item_id} accept a backorder patch object, and every inventory item response includes it:

  • enabled: false unless you set it. It can't be null.
  • limit_quantity: the most units on backorder at once across the item's levels, at least 1. null means no cap.
  • expected_ship_date: a YYYY-MM-DD date, or null when unknown.

Send at least one field. Fields you leave out stay as they are, and null clears limit_quantity or expected_ship_date.

Flint orders and reservations you create don't use the policy yet. Stock must still cover an order, and 409 INVENTORY_INSUFFICIENT is unchanged.

Backordered quantity#

Backordered units are a separate bucket. They are not held or committed, so they never change available_quantity or shortage_quantity, put a reservation line at risk, or block a commit or consume.

  • InventoryLevel.backordered_quantity reports units waiting for stock.
  • InventoryReservationLine.backordered_quantity and released_from_backordered_quantity are always present and never below 0. allocated_quantity still equals the sum of the line's buckets, which now include both.
  • InventoryMovement.backordered_quantity_delta is the change to the level's backordered_quantity.
  • InventoryReservation.expires_at is set while a line holds quantity or has backordered units that payment hasn't confirmed, and status stays active while any line holds, has committed, or has backordered quantity.

Backordered units are tentative while their reservation is on a hold and become firm when the order that owns them is paid in full. A level with firm backordered units has available_quantity 0. When stock arrives, an adjustment, transfer receive, count, return receipt, release, safety stock change, or condition change moves firm units to committed in the same transaction, oldest payment first. The movement shows the negative change in backordered_quantity_delta and the same positive change in committed_quantity_delta.

There is no public release target for backordered units. See Backorders.

  • Breaking change
  • API
  • Inventory

Inventory observations share sequence rules and show live versions#

Breaking: source_observation_sequence on adjustment lines and count observations is an integer from 1 to 9007199254740991. Send it only with source_system.type of pos, wms, erp, or other and a non-empty external_source_id. Counts now refuse zero and sequences without an external source ID with 400 INVALID_REQUEST, detail INVALID_VALUE, at the observation field.

Breaking: InventoryCountLine.captured_physical_version is required and nullable. It is null until you save an observation for the line, replacing the previous zero. A saved observation captures its submitted version, including zero.

Draft count lines now include physical_version, the level's live physical version read alongside expected quantities. It is evidence of current stock, not a fence captured at count creation. It is required and nullable: null when applied or canceled, and 0 when the level does not exist yet. Continue sending expected_physical_version when saving each observation.

Inventory receipt descriptions and missing-reservation errors now direct supplier deliveries to POST /v1/inventory-adjustments with reason: received. Receipts record returned units against consumed reservations.

  • Breaking change
  • API
  • Invoices

Record late payments after an invoice write-off#

Record a manual payment on an uncollectible invoice up to its written_off_money. A partial recovery reduces that amount and keeps the invoice uncollectible. A full recovery changes it to paid. Reversing a manual payment restores its amount to the write-off, including after a full recovery.

uncollectible is no longer published as a terminal invoice status. Recorded manual payments on written-off invoices now include reverse in supported_actions. Online collection, reminders, and late fees stay stopped. Write-offs do not count as paid money and do not create refunds.

  • Breaking change
  • API
  • Merchant-billing

Merchant billing invoice numbers and issue times#

Merchant billing invoice responses remove voided_at and always include issued_at. Update your response models. Statuses are open, paid, and written_off; legacy collecting and delinquent invoices read as open. Draft and void invoices are excluded from issued-invoice reads.

New invoice_number values use FLINT-{account code}-{0001}, sequential per billing account. The account code is the stable billing account ID. Numbers are unique; don't parse them. Existing invoices keep their numbers. Subscription line names now use the plan family, for example "Flint Growth plan".

Billing entry created_at never changes and is never backdated from an event timestamp. Overlap successive created_after passes by a few minutes and deduplicate by merchant_billing_entry_id to include late commits. No sync cursor is added.

  • API
  • Invoices
  • Billing

Recording an offline payment warns when an order is past the allowance#

POST /v1/invoices/{invoice_id}/manual-payments still records the payment whatever the account's usage is. When the payment puts an order past the month's allowance for orders paid outside Flint, the 201 response now adds a warning to meta.warnings[]:

  • code is external_paid_orders_over_allowance and severity is warning.
  • resource_type is order, and resource_id is the order the payment belongs to.
  • resets_at is the end of the New York calendar month in which Flint counted the order.

A retry with the same Idempotency-Key returns the original result, with resets_at for the original month even after the month changes, and doesn't count another order. The warning is advisory: if Flint can't work it out, the payment is still recorded without one. Sandbox payments and accounts without an allowance have no warning. Accept new warning codes as they are added.

Flint also posts a Dashboard notification and sends an email once per month and billing account when usage reaches 80% of the current allowance, rounded up, when it first goes past it, and when the month is finalized with the number of orders billed.

Read Allowance warning for the response and Orders paid outside Flint for the notices.

  • API
  • Billing

Orders paid outside Flint past the allowance appear as a monthly event fee#

Orders paid outside Flint past the monthly allowance are billed as one event_fee entry per billing account per month. GET /v1/merchant-billing-entries and the merchant_billing_itemized_v1 report return it with event_fee_type external_paid_order_overage, a new value alongside bank_verification, failed_ach_payment, ach_dispute, and card_dispute.

  • Flint posts the entry 48 hours after the New York calendar month ends. occurred_at is the end of that month and created_at is when Flint posted it.
  • The month's allowance, net live USD collected through Flint, counted orders, excess orders, unit price, and amount are fixed when the entry posts. An order committed later still counts as usage, but Flint doesn't rebill the month.
  • A month bills only if it started at or after the exact time the allowance policy was first assigned to the billing account. A policy assigned at any time after a month started, including a new account's first month, has no charge for that month and starts billing the next. A policy that takes effect exactly at the start of a New York month bills that month in full.
  • The charge stays on the merchant that made the month's first reservation for the billing account, in the live environment, even if that merchant later leaves the account or closes. Flint never reassigns it to a current member.
  • A past-due balance made up only of these fees is collected like any other but never pauses payments or payouts. A balance that includes any other amount follows the usual timeline.

Read Orders paid outside Flint for the rules and Processing fees for the price.

  • API
  • Orders

Preview removing items from a paid order#

POST /v1/order-edit-previews calculates what removing items from a paid order would refund, without changing the order. Send an order_id and remove_line_items, each with an order_line_item_id and a whole quantity. Add charge_refunds to include charges such as delivery, destinations to choose where the original payments go back to, and a reason.

The response returns each line's refund_money, including its share of discounts and tax, the removable_quantity before the removal, and the total refund_money. based_on_order_version names the order version it read. A preview doesn't hold stock or refundable money, so calculate again before you rely on it.

Only quantity that no fulfillment has claimed can be removed. Orders that were paid by invoice, or that came from a subscription or a return, can't be edited, and neither can an order that is unpaid, has a disputed payment, or has an unresolved inventory exception. Each refusal returns a 409, with details[0].reason naming the cause on ACTION_NOT_ALLOWED, and quantity above what is removable returns 409 LIMIT_EXCEEDED with details[0].available_quantity. The route needs commerce.orders.read and takes no Idempotency-Key.

This route is the first step of editing a paid order. Previews cover removals, and nothing is committed yet. See Preview removing items from a paid order.

  • API
  • Orders
  • Fulfillment

Order lines report removed quantity#

Order line items now include removed_quantity, the units taken off the paid order before any fulfillment claimed them, in units of the line. Each entry in fulfillment_quantities gains a matching removed_quantity, in units of the item or bundle component. The six buckets, unassigned_quantity, assigned_quantity, fulfilled_quantity, canceled_quantity, failed_quantity, and removed_quantity, add up to required_quantity. Clients that sum the earlier five need to include the new one.

Removing units doesn't change the line's quantity or pricing_amounts, which stay the record of the sale. A removed unit is final: it doesn't return to unassigned_quantity, and it counts like a canceled unit in the order's fulfillment_status. An order whose remaining quantity was all canceled or removed reads canceled, and one with some fulfilled and the rest canceled or removed reads closed.

Both fields also appear on buyer reads and orders in webhook payloads. Every value is 0 until units are removed. See Read what is left to fulfill.

  • Breaking change
  • API
  • Errors

param names the input to change#

These changes apply immediately to every supported API version.

  • param on INVALID_REQUEST and on other errors that set it now uses one form: a dotted path from the body root with [0] indexes (line_items[0].name), a map value as metadata.order_ref or metadata["a.b"] for a key with other characters, a path or query parameter name, a header name, or body for a failure of the whole body. Some errors name a different input than before. Read Validation errors for each case.
  • An invalid or repeated X-Request-Id request header now returns param: "X-Request-Id". It was header.X-Request-Id. No param carries a location prefix.
  • param never holds a [] placeholder, an internal field name, or a stand-in such as scope or scopes. INSUFFICIENT_SCOPE and FORBIDDEN set param only when a request input names the refused thing, such as scopes[2] when creating a key.

If you match on param, compare against the forms above. Branch on code and details[].code for the failure itself.

  • Breaking change
  • API
  • Webhooks
  • Payments

payment_intent.updated covers refund and dispute changes#

A refund or dispute that changes a payment intent's refunded_money, refund_status, or dispute_status now sends payment_intent.updated, as well as the refund.* or dispute.* event. Previously these fields changed without a payment intent event. Expect about one more event for each refund and each dispute status change on a payment. The payment intent's status still never changes for a refund or dispute.

payment_intent.updated now fires only when the payment intent's object changes. Previously, some changes that left the object as it was also sent it: a tip set on an order's payment intent before payment, while tip_money is still null, or a processor reference matching the payment intent ID that support_reference already showed.

A change that sends another payment intent event, such as a status event or payment_intent.fulfillment_hold_updated, doesn't also send payment_intent.updated.

Payment intent change events now include data.previous_attributes. See Previous values on webhook change events.

Delivery remains at least once. Deduplicate on webhook_event_id, and read the payment intent before an irreversible step. See Payment intent events.

  • API
  • Refunds
  • Invoices

Record credit-note refunds you paid outside Flint#

POST /v1/refunds with refund_type: credit_note accepts three new optional fields for money you returned to the buyer yourself, such as by check or wire for an invoice paid with a manual payment:

  • processed_by: flint (the default) or merchant. With merchant, Flint records the refund and moves no money.
  • refunded_at: an RFC 3339 time for when you returned the money. It defaults to now and can't be in the future.
  • refund_reference: a check or wire number of 1 to 255 characters, stored exactly as sent. external_reference_id stays your own ID for the refund.

refunded_at and refund_reference are accepted only with processed_by: "merchant". Otherwise the request returns 400 INVALID_REQUEST with detail NOT_ALLOWED.

A recorded refund is created succeeded. Flint contacts no processor, posts no balance transaction, and sends the buyer no refund receipt. The credit note's refunded_money rises and its available_money falls, and the invoice's and order's refunded amounts include the refund. refund.created and refund.succeeded arrive together with the same snapshot and version. The credit note sends no event of its own, and the invoice and order each send one event: invoice.partially_refunded or invoice.refunded when refund_status changes, otherwise invoice.updated, and the same for order.*.

The amount can be at most the smaller of the note's available_money and the invoice's manually recorded money not yet returned. Omit amount_money to record that amount. A larger amount, or none left, returns 409 LIMIT_EXCEEDED with details[0].maximum_money. Reversing a manual payment that recorded refunds depend on now returns 409 RESOURCE_IN_USE, with those refunds in blocking_resources. A recorded refund can't be reversed.

Refund and BuyerRefund responses gain a required processed_by (flint or merchant; treat the vocabulary as extensible) and, on recorded refunds only, refunded_at and refund_reference. Every earlier refund reports flint. processed_by says who moved or returned the money.

See Record a refund you paid outside Flint.

  • API
  • Refunds
  • Orders

Refunds accept the out_of_stock reason#

POST /v1/refunds now accepts out_of_stock as a reason, for units you couldn't supply, for example because stock ran out. Refunds carrying it return it in reason. The reason list can grow, so handle a reason you don't recognize like other, as in Choose a reason.

POST /v1/order-edit-previews takes the same reasons, and a removal worth 0, such as a free item, previews with a refund_money of 0. See Preview removing items from a paid order.

This change is additive. No existing reason changed.

  • Breaking change
  • API
  • Settings
  • Invoices

Invoice time zone setting removed#

settings.invoices.timezone is removed from settings responses and updates. PATCH /v1/settings rejects invoices.timezone, including null, as an unknown field.

Set the merchant's business time zone with PATCH /v1/merchant and timezone, such as America/New_York. New invoice drafts take that zone, or UTC when the merchant has none. Invoice payment terms work without a separate invoice time zone setting. Automatic tax also uses the merchant’s time zone, then UTC, when the seller origin has no time zone.

Existing invoices keep their saved timezone. Changing the merchant's time zone does not move their due dates, reminders, or late fees.

  • API
  • Orders
  • Refunds

Retry a failed order edit refund#

POST /v1/orders/{order_id}/edits/{order_edit_id}/retry refunds what an order edit still owes the buyer: a refund that was created and then failed, fully or in part, or a refund Flint stopped trying to create. It requires an Idempotency-Key and both commerce.orders.write and commerce.refunds.write. The body is optional: send destinations to choose where the original payments go back to, or leave it out to reuse the edit's. The response is 201 with the order_edit and the new refunds, which carry the edit's order_edit_id and reason.

Order edits gain two fields. unrefunded_money is the refund money the edit froze, less its pending and succeeded refunds. supported_actions contains retry when unrefunded_money is above zero and nothing is in progress, meaning none of the edit's refunds is pending and Flint isn't still creating the first one.

A retry returns 409 ACTION_NOT_ALLOWED with reason already_applied when nothing is left to refund, in_progress while one of the edit's refunds is pending or Flint is still creating the edit's refund, and payment_disputed when the payment is disputed. Flint holds an edit's refund money for the edit, so a refund created with POST /v1/refunds can't use it. See Retry a refund that failed.

  • Breaking change
  • API
  • Returns
  • Return_policies

Returns responses and buyer cancellation match their contract#

ReturnCompletionBlocker no longer publishes shipment_id, return_inspection_id, or return_disposition_id, which were never populated. Use the line ID, the resolution ID for resolution blockers when one exists, and the receipt ID for merchandise exceptions. Correction resolutions and unidentified merchandise can have no line ID.

ReturnResolution.action_reason now lists only buyer_payment and manual_release. action_required_by remains buyer or merchant.

POST /v1/me/returns/{return_id}/cancel accepts only reason: buyer_request. Omit reason to use that default. Merchant cancellation reasons are rejected with 400 INVALID_REQUEST, detail INVALID_VALUE, and param: reason.

Policy revisions require approval_mode: automatic or manual, including ineligible revisions. Ineligible revisions require ineligibility_reason, and returnable revisions forbid it. Policy scopes accept only the supported order channels: checkout, payment_link, virtual_terminal, api, and subscription.

Create, update, publish, and archive policy responses omit current_revision. Read the policy with expand=current_revision to retrieve the rules. A revision published while its policy is active now records the publish time in effective_at. Existing revisions are not backfilled.

Built-in Return reasons use their release time, 2026-07-27T00:00:00Z, for created_at. Their updated_at is the merchant availability change time, or the same release time if unchanged.

See Return policies, Returns, and Buyer self-serve returns.

  • Breaking change
  • API
  • Payments

Risk rule matching and payment review attribution#

Breaking: Risk rule comparisons for email and email_domain now ignore case, including rules saved before this change. Flint lowercases these literals when saving rules. Metadata comparisons remain case-sensitive. Check existing email rules, especially neq predicates, for the intended matches.

POST /v1/risk-previews with mode: stored_rule accepts optional action and predicate overrides. Omitted or null fields keep the saved value. Flint default rules cannot be overridden. Rule descriptions allow up to 512 characters counted as Unicode code points, and the API schema now publishes that limit.

Order payments authenticated with an API key or partner-install token no longer record the merchant server's address as the buyer IP. A verified Flint app can still forward the buyer's address. Without buyer IP evidence, declining a review with add_to_block_lists skips the IP entry.

Processor fraud blocks identify no Flint deciding rule and say that the payment processor's fraud screening blocked the payment. Completed review resolutions retain resolution_started_at and resolution_started_by. The credential that requested a decline is also recorded on the closed review and any block-list items it adds.

  • Breaking change
  • API
  • Subscriptions

Subscription create previews include collection estimates#

POST /v1/subscription-previews with mode: "create" now returns SubscriptionCreatePreview. It keeps mode, is_valid, and errors and adds required nullable first_charge and recurring fields. Update clients that depend on the former shared SubscriptionPreview response schema to select the new create branch. Delivery previews continue to use SubscriptionPreview.

first_charge estimates the first Flint collection. A setup fee is priced separately from recurring items, at creation or the scheduled start. Without a setup fee, it estimates trial conversion or the first paid period. An import estimates its first Flint renewal and skips setup fees. recurring estimates the first normal full-period collection without setup fees, using the imported cycle count and applicable recurring promotions.

Both estimates are null when validation prevents pricing. is_valid means the inputs are valid and priceable, not that the subscription is ready to pay. Card validation follows creation, including cardless imports. Each estimate uses SubscriptionChargeEstimate; billing_at can be null for an external schedule, and tax_money is null when tax can't be calculated yet. The total then excludes unresolved tax.

Create previews don't support prorate_first_period yet. Sending prorate_first_period: true under subscription now returns 400 INVALID_REQUEST with param: subscription.prorate_first_period, instead of an eligibility result in errors. Preview without it, or create the subscription and read its first order.

Previews create no subscription or order and consume no promotion use. See Import subscribers from another tool for the request and response fields.

  • Breaking change
  • API
  • Subscriptions

Charge prorated subscription changes without moving the billing date#

billing_starts now accepts prorated_now on plan changes, plan change previews, and plan_change_options. It charges the new terms for the rest of the current period, less credit for unused paid subscription time. The current period, next billing date, billing anchor and completed cycle count stay the same. The resulting billing interval must match the current interval. now still starts and charges a new period.

Breaking: the closed response vocabulary subscription_plan_change_billing_starts gains prorated_now, and subscription_preview_mode gains quantity_change. Update exhaustive checks before using these values.

Use POST /v1/subscriptions/{subscription_id}/change-quantity with an Idempotency-Key, billing_starts: prorated_now, and quantity, line_items, or both to charge a quantity change. Each line names an existing subscription_line_item_id and its new quantity. Send up to 50 distinct lines. expected_version is optional. Digital line quantities can change even when other subscription lines ship. Shipping line edits, or a subscription multiplier on a subscription with anything that ships, return 400 NOT_ALLOWED. The adjustment creates no shipment or shipping charge. Subscription PATCH and the line-item routes continue to update quantities for future unpaid renewals without charging now.

The result includes billing_starts, subscription, order, and order_payment_attempt. A zero net charge returns null for both billing objects. A decline returns 200 with the unchanged subscription, a closed unpaid order, and a failed payment attempt. Retry an uncertain outcome with the original key.

A positive net charge below the processor minimum returns 409 ACTION_NOT_ALLOWED with reason minimum_charge and details[].minimum_money. A period without a Flint-paid order returns reason paid_period_required. Negative net charges return reason credit_exceeds_charge; use a quantity update without charging or schedule a plan change for period_end instead.

Use subscription preview mode quantity_change with the same quantity inputs to see the prorated charge, unused-time credit, recurring subtotal and renewal breakdown before applying the change. SubscriptionQuantityChangePreview returns interval and interval_count and omits subscription_plan_id; read the subscription for its current plan. Existing plan change previews retain billing_interval and billing_interval_count. Buyer previews keep their existing modes. Discount source gains proration, which deducts the elapsed portion of the period from the new terms' charge.

  • Breaking change
  • API
  • Subscriptions

Moving a trial's billing date moves its trial end#

On a trialing subscription, setting billing_schedule.owner to flint and changing billing_schedule.next_billing_at now moves trial_end_at too. The first paid period starts at that date, and Flint recomputes current_period_end_at and the billing anchor as it does when creating a trial. Supply billing_schedule.billing_anchor_day to keep an explicit anchor.

Previously, the billing date could move while the trial retained its original end. Integrations that change a trial's billing schedule must now treat the new date as the trial's conversion date. Trial-ending notices and a pending period-end cancellation follow that date. External-owned schedules keep their existing trial end.

If conversion is already in progress, the reschedule returns 409 OPERATION_IN_PROGRESS with retryable: true. The trial schedule stays as it was, and the conversion continues at its original boundary. Retry the schedule change after that operation finishes.

See Control the billing schedule and the Subscriptions reference.

  • API
  • Subscriptions

Free trials can start without a card#

A subscription to a plan with a trial can now start without a card when nothing is charged at creation. Omit payment_method_id. Flint uses the customer's default card, and if the customer has none, the subscription starts trialing with payment_method_id: null. A plan with a setup fee, or any start that charges at creation, still requires a card.

This extends the nullable payment_method_id and payment_method_due_at fields from Subscriptions can exist without a payment method. Imports behave as that entry describes. For a trial, payment_method_due_at is the first charge boundary, normally the trial end, until a card is bound, then null. Flint recomputes it when a schedule change moves the first charge. There is no new status, field, or event.

With subscription_lifecycle set to flint_sends, the trial-ending email asks the buyer to choose a card. It goes out 3 days before the boundary, or right away when less time remains. With merchant_sends, ask the buyer yourself when subscription.trial_ending arrives. Bind a card with PATCH /v1/subscriptions/{subscription_id}; the subscription stays trialing and charges it at the boundary, and stays trialing until that charge resolves. If the boundary arrives without a card, nothing is charged. Flint cancels the subscription and sends subscription.canceled and the cancellation email.

See Trial without a card.

  • API
  • Tax
  • Settings

Register a tax calculation callback#

/v1/tax-calculation-callbacks registers an HTTPS endpoint for your own tax engine, as /v1/delivery-rate-callbacks does for delivery rates. IDs begin with tcb_, and each configuration change publishes a revision beginning with tcbr_. You can create, read, list, PATCH with expected_version, and archive with DELETE. POST .../check-connection, POST .../test-deliveries, and POST .../rotate-secret work as they do for delivery rate callbacks. A test delivery sends a tax_calculation_evaluation_id (tce_...) and passes when your endpoint echoes it with empty line_item_calculations and charge_calculations.

A callback is inactive, active, or archived. request_timeout_seconds accepts 0.1 to 10 and defaults to 3. signing_methods defaults to ["jwt"], and the JWT aud claim is the callback's tcb_ ID. The routes need settings.read or settings.write; partner app install tokens can't call them. Changes send tax_calculation_callback.created, .activated, .deactivated, .updated, and .archived.

tax.calculation_callback_id in PATCH /v1/settings selects the environment's callback. Selecting a different callback replaces the previous one in a single write. Deactivating or archiving the selected callback returns 409 RESOURCE_IN_USE.

You can register, test, and select a callback now. Flint doesn't use a callback to calculate tax on orders, checkout sessions, or subscriptions yet, so their tax is the same whether or not one is selected. See the tax calculation callbacks guide.

  • API
  • Reports
  • Tax

tax_transactions_itemized_v2 report#

POST /v1/reports now accepts report_type: "tax_transactions_itemized_v2". tax_transactions_itemized_v1 is unchanged.

The v2 report has every v1 column, plus:

  • collection_source.resource_type and collection_source.resource_id, which identify what the collection came from: payment_intent, invoice_manual_payment, or gift_card_redemption.
  • exemption.source, exemption.reason, exemption.certificate_number, and exemption.customer_tax_exemption_id, from the exemption recorded on the sale. These are empty when the sale recorded no details.
  • post_tax_discount_money.amount, which is zero, and post_tax_discount_money.currency, which is the report currency.

It differs from v1 in its rows:

  • A collection row is one tax calculation applied to one collection, so an order collected in several parts has several rows per calculation. Each row's tax_money is that collection's share of the calculation's tax: the tax stored on its settlement allocation for a line item, or tax derived from the frozen calculation for a charge. Flint splits the calculation's other amounts across the rows by largest remainder.
  • An exempt_collection row is an automatic tax sale that recorded an exemption, read from the original collection's frozen assessment (the payment attempt's, or the owning issued invoice's), never from the current order or customer. It has no calculation, so the calculation ID, addresses, rates, and jurisdiction columns are empty.
  • A refund_reversal row reverses the tax of one original payment and tax calculation partition, so a refund can have several rows. A line item reversal uses the tax recorded on the refund; a charge reversal uses the tax derived for the original collection and keeps the refund's recorded total and discount. Each row carries the collection source of the collection it reverses.

The eight new columns follow the v1 columns. payment_intent_id is empty unless the collection was a payment intent.

See Reports and Tax reports.

  • Products
  • Catalog
  • Orders
  • Payment-links

Variant quantity price breaks#

Product variants now accept quantity_price_breaks on create and update, including default_variant and inline variants when creating a product. Each break defines a minimum_quantity and a lower unit_price_money. Minimum quantities start at 2 and strictly increase; unit prices strictly decrease from the base and use the same currency. Gift card variants reject a nonempty array.

Variant reads always return the array. On update, send the complete replacement, [] to remove all breaks, or omit the field to preserve it. null is invalid. Base-price updates must keep the complete schedule valid.

Catalog variant order lines now price from the variant's schedule using that line's own quantity. Order line items report catalog_pricing with source, price_list_id, and minimum_quantity. Changing a line's quantity on an open order selects from the schedule saved when the line was added. See Variant quantity pricing for the refusals that apply once an order has received payment.

Payment link reads include quantity_price_breaks for each offered variant in available_variants and for fixed variant lines in resolved_line_items. See Variant quantity pricing.

See Quantity price breaks for examples and validation rules.

  • Breaking change
  • API
  • Invoices
  • Webhooks

Invoice lifecycle events omit companion updates#

Invoice webhook behavior changes for every supported API version:

  • invoice.issue_failed and invoice.marked_uncollectible no longer send a companion invoice.updated for the same change. Handle the named event directly.
  • Applying or reversing a credit note allocation now sends invoice.updated when the invoice's credit and outstanding amounts change without an invoice status event. If the change sends invoice.credited, invoice.paid, or invoice.reopened, it sends that event without invoice.updated. The allocation still sends its own event.
  • Pausing or resuming reminders and recording the first view now send invoice.updated. Repeating the same setting or viewing the invoice again sends no new invoice event.
  • Each successful non-reminder delivery sends invoice.sent, including a later resend. Retrying the same delivery sends no new invoice event.

Invoice refund events follow the same transition rule: invoice.partially_refunded and invoice.refunded fire only when refund_status changes to the named value. For two partial refunds followed by a refund of the remaining amount, the first sends invoice.partially_refunded, the second sends invoice.updated, and the final refund sends invoice.refunded. A correction that returns refund_status to none sends invoice.updated. Replaying an unchanged refund fact sends no new invoice event.

Subscribe to invoice.updated alongside the invoice status events to keep invoice amounts current. Use refund.* to track each refund's progress; invoice refund status events describe changes to the invoice's aggregate refund_status.

See Invoicing, Credit notes, and the invoice event catalog.

  • Breaking change
  • API
  • Webhooks
  • Refunds
  • Disputes

Refund and dispute events follow committed changes#

A refund created already succeeded now sends refund.created and refund.succeeded together. A refund created in partially_succeeded or failed likewise sends creation and its status event. Previously, creation could send only refund.created. Update the same refund record when both events arrive.

Later refund changes send the matching status event, or refund.updated for other public changes. A commit that sends a status event does not also send refund.updated. A pending refund with no public field change no longer sends refund.updated. Replaying an unchanged refund or dispute sends no new event. Separate changes in the same second retain distinct event identities.

Dispute event types stay the same. Event created_at is when Flint records the event. Use the timestamps on data.object for the dispute's business times.

See Refund events and the event catalog.

  • Breaking change
  • API
  • Orders
  • Inventory
  • Catalog
  • Webhooks

Sell variants on backorder and pre-order#

A variant can now be sold ahead of its release, whether or not it tracks inventory, and a tracked variant can be sold past available stock. Backorders are off until you set backorder.enabled to true on an inventory item, so nothing changes for items you don't opt in. An order that stock can't cover still fails with 409 INVENTORY_INSUFFICIENT.

Variants. release_date is a YYYY-MM-DD date or null. Send it when you create a variant, change it with PATCH /v1/products/{product_id}/variants/{variant_id}, and read it from any variant. Flint doesn't stop a variant from selling or shipping before its release date.

Order lines. Merchant reads, buyer reads, and order.* webhooks add three fields to each line:

  • backordered_quantity: the line's units waiting for stock, 0 when none are. Lines that track inventory always carry it.
  • release_date: the variant's release date when the line was created, if it was in the future. Otherwise null.
  • expected_ship_date: appears once a delivery or payment hold exists, even with nothing backordered. It comes from the line's release_date and otherwise, for backordered units, from the item's backorder.expected_ship_date; a past item date is left out, and today's date still counts. Before payment it is Flint's current estimate. It freezes when the order is paid, so a pre-order that stock fully covers keeps its release date. After that it changes only through the line item PATCH, never because stock arrives. The date is the expected date, not a gate: Flint doesn't hold a fulfillment until it.

Backordered units are tentative while the order is unpaid and firm once it is paid in full. When stock arrives, Flint fills firm units oldest payment first, lowers the line's backordered_quantity, advances the order's version, and sends order.updated.

Changing a date. PATCH /v1/orders/{order_id}/line-items/{order_line_item_id} accepts expected_ship_date, or null to clear it, on a paid order. Existing requests to this route are unaffected. expected_ship_date can't be combined with other line item fields in one update, so send it on its own; expected_version, the order's version, is still accepted with it. A change advances the version and sends order.updated; resending the current date, or clearing an empty one, changes nothing.

Listing orders. GET /v1/orders?has_backordered_quantity=true lists orders with at least one backordered line, and false lists the rest.

Fulfillment. Backordered units stay in unassigned_quantity, but you can fulfill only unassigned_quantity minus the line's backordered_quantity. A fulfillment that claims more returns 409 INVENTORY_INSUFFICIENT with details[0].available_quantity, where the same request previously failed without a typed error. Flint creates the fulfillments for a paid delivery choice only when all of the remaining units are in stock, and never splits the choice into shipments on its own. Create a fulfillment yourself to ship the units you have sooner; Flint then creates fulfillments for the remainder only.

Edits and payment links. An order edit releases a line's backordered units before its committed ones. A payment link reports is_sold_out: false while its item's backorder limit has room left.

Bundle components and subscription renewals don't backorder, and neither do reservations you create. See Sell past available stock and Backordered and pre-ordered lines.

  • Breaking change
  • Api-request-logs

Request log search uses query#

Breaking: GET /v1/api-request-logs now accepts query for substring search on path. Replace path_query with query in your requests. The old parameter returns 400 INVALID_REQUEST with detail code UNKNOWN_FIELD.

Search matches only path, not query-string values. The characters %, _, and \ match literally. Start pagination again when changing the search text.

  • Breaking change
  • API
  • Returns
  • Inventory

Automatic return dispositions follow inspection conditions#

Accepted return inspections under receipt_disposition_mode: automatic now create dispositions based on condition, with reason: inspection_result:

  • new and unopened become sellable.
  • opened, used, incomplete, and undetermined become quality_control.
  • damaged and defective become damaged.

Previously, every accepted inspection created a sellable disposition. Update integrations that assume accepted goods always increase sellable stock. Lines without an inspection continue to receive sellable dispositions. All automatic dispositions now use reason: inspection_result, replacing return_policy.

When a tracked line has no inventory mapping, receipt creation, verification, inspection, and acceptance decisions now record the observation and return the generated disposition as failed with failure_code: inventory_item_unmapped. The line remains disposition_required. Cancel the disposition or create a replacement with replaces_return_disposition_id. Retry isn't available for this failure.

See Receiving and inspecting returns and Return policies.

  • API
  • Orders
  • Tax

Automatic tax supports service, handling, and surcharge fees#

Automatic tax now calculates taxable charges in all five charge categories: service_fee, shipping, delivery, handling, and surcharge. Each uses the general rate at the charge's location. A paid pickup with default tax settings uses service_fee and is taxed at the store.

Taxable charges whose type supplies no default category, such as setup_fee and other, still need tax.charge_tax_category. Set one of the five categories, set taxable: false, or use external tax.

Prepared food stays taxed at the general rate; rates specific to prepared food or restaurant meals aren't applied. food, clothing, medical_goods, and admission still require external tax because the tax provider cannot express their state-specific rules. See Sales tax.

  • Breaking change
  • API
  • Products
  • Bundles
  • Modifiers

Embedded modifier groups and category references#

Modifier set responses previously used separate shapes: existing entries carried modifier_group_id and modifier_group_name, while inline entries carried modifier_group. Every entry now has required modifier_group_id and modifier_group fields, with source set to existing or inline. modifier_group_name is removed, and the response is one object shape rather than a union. Create and update requests keep their source-specific fields.

The embedded group matches a group detail read and excludes archived choices, even when the group is archived. This applies to set reads and lists, create and update responses, expanded modifier sets on products, variants and bundles, and modifier_set.* event objects. Editing or archiving a shared group advances every referencing set's version and updated_at and sends modifier_set.updated, including for archived sets.

Category references previously returned {category_id, handle, name}. They now return {category_id, handle} wherever CategoryReference appears, including products, bundles, and order and invoice line items. A category rename leaves those products, bundles, and their versions unchanged. Order and invoice lines retain the category IDs and handles recorded when the line was created or billed.

To migrate:

  1. Replace reads of a set entry's modifier_group_name with modifier_group.name. Continue to prefer display_name when the set overrides the name.
  2. Read group rules and choices from the embedded modifier_group for both sources. Remove separate group lookups and response-union branches; keep source-specific branches when constructing requests.
  3. List GET /v1/categories and store names by category_id. Join category references to that map, and apply category.updated when a name changes.
  4. Apply modifier_set.updated when a shared group changes, including for archived sets you retain.

See Modifiers, Categories, and Catalog setup.

  • Breaking change
  • API
  • Checkout
  • Payment-methods

Checkout saved-card lists require verified authority#

GET /v1/payment-methods with a checkout credential that has no saved-card authority and no customer_id now returns 409 ACTION_NOT_ALLOWED with details[0].reason: verification_required and no param. Previously it returned 404 RESOURCE_NOT_FOUND for an empty customer ID. Update handling that matches that 404 to offer buyer verification or let the buyer continue with a fresh card.

The top-level remediation.next_actions includes create_checkout_session_customer_verification, with url: /v1/checkout-sessions/{checkout_session_id}/customer-verifications. Request a code there with purpose: use_saved_payment_methods, follow the supported email or phone flow, confirm the code, then retry listing with the checkout credential returned by confirmation. A code may not be offered. Recognize a returning buyer covers both flows.

Explicit customer IDs outside the credential's authority still return 404 RESOURCE_NOT_FOUND. Customer binding and verification still determine which cards a checkout may list. Linking the order to a customer alone grants no saved-card authority.

Ended-session refusals now say "The checkout session has ended." They keep 409 ACTION_NOT_ALLOWED, reason terminal_status, and the actual current_status. Route access is unchanged.

  • Breaking change
  • API
  • Refunds
  • Invoices

Credit-note refunds return gift cards first#

Breaking: POST /v1/refunds with refund_type: credit_note, and refunds created when issuing a credit note, now return gift card payments first. Previously, these requests returned only card and bank payments, which could turn gift card value into cash or reject a refund with gift card value still available.

Gift card legs credit their original cards in the creation transaction. Card and bank legs use the remaining amount, largest refundable payment first. Each leg is capped by its collections on the invoice minus prior refunds. Read tender_allocations for every leg; payment_refunds contains only card and bank legs. Gift-card-only refunds succeed on creation; a mixed refund can remain pending and later partially succeed if its card or bank leg fails.

Review integrations that assumed credit-note refunds always return cash. The same request can now return part or all of its amount to the original gift cards. Replaying an accepted request with its original key returns its stored result without another gift card credit.

  • API
  • Tax
  • Customers

Record customer tax exemptions#

Customer tax exemptions are available under /v1/customers/{customer_id}/tax-exemptions. Create and list records there; retrieve, update, or archive each record by its customer_tax_exemption_id, prefixed ctex_.

Records include a closed exemption reason, all-state or state-list US coverage, optional certificate and merchant-only evidence references, inclusive start and end dates, metadata, and a version fence. They report scheduled, active, expired, or archived. Expired and archived records cannot be edited. Archives stay retrievable by ID and never list. Each customer allows 100 unarchived records.

Reads require customers.read; writes require customers.write. API keys and Dashboard sessions can access these routes. Customer and checkout sessions cannot, and evidence references are never shown to buyers or printed on buyer documents.

Saving a record does not yet apply its coverage to sales or copy it onto order and invoice snapshots. The customer's existing blanket tax_exempt flag is unchanged.

  • Breaking change
  • API
  • Webhooks
  • Invoices
  • Orders
  • Refunds

Invoice and order refund events follow status changes#

Breaking: Refunds now send one event for each invoice or order whose refund projection changes in a commit. This applies to card-only refunds as well as credit-note refunds with gift card legs.

Committed changeInvoice eventOrder event
refund_status becomes partially_refundedinvoice.partially_refundedorder.partially_refunded
refund_status becomes refundedinvoice.refundedorder.refunded
The refunded amount changes while refund_status stays partially_refundedinvoice.updatedorder.updated

A refund status event has no accompanying invoice.updated or order.updated. Previously, card-only first and full settlements paired the invoice status event with invoice.updated. Further partial settlements repeated invoice.partially_refunded alongside invoice.updated, while an order that stayed partially_refunded sent no order event. Those further partial settlements now send only the affected resource's updated event. A correction back to refund_status: none also sends updated. Replays that leave the public resource unchanged send no new event.

For example, a $9 invoice paid with a $5 gift card and $4 card gets a $6 credit-note refund. Crediting the gift card sends invoice.partially_refunded and order.partially_refunded. Applying the remaining $1 card leg to the invoice's refunded amount sends invoice.updated, because its refund status stays partially_refunded. The order likewise sends order.updated when its own refunded amount changes without a status change. If a commit instead completes the full $9 refund on either resource, that resource sends refunded without updated.

To migrate, subscribe to invoice.partially_refunded, invoice.refunded, and invoice.updated when mirroring invoices, and the corresponding three order.* events when mirroring orders. Process each event's data.object and version through the same resource update handler; don't wait for a separate updated event after a status event. Count individual refunds and track their outcomes from refund.* events, rather than counting invoice or order status events. See the webhook event catalog.

  • API
  • Reports
  • Invoices

Export issued invoices with payments and outstanding balances#

Create an invoices_itemized_v1 report with POST /v1/reports to export invoices by issued_at and currency. Drafts are excluded. Each row includes invoice and customer details, order and subscription IDs, lifecycle dates, totals, late fees, payments, refunds, credits, write-offs, and the outstanding balance.

Values reflect the invoice when the report is generated. A retry or later report can include subsequent payments and adjustments. The export calls applied credit notes credited_money; Invoice still calls this amount credit_money. Money values use .amount and .currency columns.

See Invoice report columns for ordering, reconciliation, and the existing CSV and API path for accounting imports.

  • Breaking change
  • API
  • Merchants
  • Invoices
  • Reporting

One business time zone on the merchant#

Merchant.reporting_timezone is renamed timezone, in GET /v1/merchant responses and PATCH /v1/merchant requests. It is the business's IANA time zone, such as America/New_York.

Breaking: reporting_timezone is no longer returned or accepted. PATCH /v1/merchant rejects reporting_timezone as an unknown field. Send timezone instead. Sending null for timezone still returns 400 INVALID_REQUEST with param set to timezone, as it did for reporting_timezone.

Wherever a time zone matters, Flint now uses the same order: the time zone in the request, then the merchant's timezone, then UTC.

  • Reports and analytics cut days in the merchant's timezone when the request sends no timezone. Before, they used UTC, and the Dashboard used the viewer's time zone.
  • Locations take the merchant's timezone when POST /v1/locations leaves timezone out. Before, timezone was required.
  • Invoices take the merchant's timezone when a draft is written, or UTC when the merchant has none, and keep it. Before, they took settings.invoices.timezone. Flint keeps that setting but no longer uses it.
  • The Dashboard shows the merchant's timezone as the business time zone in Settings, and no longer falls back to the viewer's or device's time zone for analytics, reports, or the schedules it fills in.

A resource's timezone is a snapshot taken when Flint writes it, so changing the merchant's timezone later doesn't move existing invoices or locations.

Where a time zone Flint can't trust would move a deadline or money, Flint refuses the request before writing anything, instead of guessing. A timezone you send that isn't a valid IANA name returns 400 INVALID_REQUEST naming the field. If a saved time zone is invalid, the request returns 500 INTERNAL_ERROR and nothing changes; existing invoices and locations keep their values.

  • API
  • Invoices
  • Billing

Orders paid outside Flint past the monthly allowance cost $1 each#

Orders paid outside Flint now have a priced allowance instead of a limit. As the 2026-11-04 change describes, POST /v1/invoices/{invoice_id}/manual-payments records the payment whatever the account's usage is. The allowance and the price are:

  • The allowance is 20 orders plus 1 order for every $1,000 collected through Flint in the billing account's calendar month, New York time, rounded down.
  • Each counted order past the allowance costs $1, billed as its own line on your Flint bill after the month ends.
  • Collected through Flint is live USD payments by card, Apple Pay, Google Pay, ACH debit, and Affirm, counted in the month they were captured, minus refunds that succeeded that month, whatever month the payment was captured. It never goes below zero, and disputes and ACH returns do not reduce it.
  • An order counts once when it is paid in full and at least one payment on it was recorded outside Flint. Installments, retries, and replays do not count again, and reversing a payment does not remove the count. Sandbox payments do not count.
  • Billing starts with the first full calendar month, New York time, that this policy covers on your account. A month that began before the policy took effect is not billed.
  • A negotiated agreement can change the allowance and the price, or remove the allowance.

The invoicing guide has the rules and an example.

  • API
  • Orders
  • Receipts

Download an order's receipt as a PDF#

GET /v1/orders/{order_id}/receipt-pdf returns a receipt as application/pdf, named receipt-{order_number}.pdf. Use an API key with commerce.orders.read, or the checkout credential of the order's own checkout session to offer a download on your thank-you page. Buyers in a customer session, including one opened from an order access link, use GET /v1/me/orders/{order_id}/receipt-pdf.

The receipt is available under the same conditions as send-receipt, and under either order_receipts delivery mode: the order has a successful payment intent or gift card redemption, including after a refund. Before then, the routes return 409 ACTION_NOT_ALLOWED with reason status_not_reached and the order's current_status. An order paid only by a recorded cash, check, or wire payment returns reason unsupported_state, and its message points to the invoice PDF. A payment intent without an order has no receipt PDF.

It shows the lines, discounts, charges, tax, tip and total, each successful payment and gift card redemption, the refunds, and the balance due. Like the receipt email, it doesn't list recorded cash, check, or wire payments on an order that also has a card payment. Flint records the seller and buyer details when the order is first paid, so later changes to the customer or your tax identity don't alter the receipt. Orders have no receipt_url field; create a hosted link with POST /v1/orders/{order_id}/access-links.

Invoice and credit note PDFs rendered in test mode now carry a "Test mode" band. Their content is otherwise unchanged.

See Receipts and buyer links.

  • API
  • Tax
  • Orders
  • Invoices
  • Customers
  • Subscriptions

Tax exemptions apply to orders, invoices, and renewals#

Customer tax exemption records now apply to sales. A customer with tax_exempt: true is exempt everywhere. Otherwise Flint uses the customer's active record whose coverage contains every taxable destination. If any taxable destination falls outside its coverage, the whole order is taxed. If several match, the latest start_date wins, then the newest record. Start and end dates are inclusive in the merchant timezone. Subscription renewals always use the customer's exemption.

Orders take a new tax.exemption input with a type of customer (the default), order, or none. An order declaration sends a reason and coverage, plus optional certificate_number, description, and evidence_reference. As on a customer record, description is required when reason is other. none taxes the order even for an exempt customer. Once the order's tax commits, such as by a collected payment, an issued invoice, or a confirmed return replacement, changing the input returns 409 ACTION_NOT_ALLOWED with reason payment_collected.

tax.exemption on an order has new read-only fields: customer_tax_exemption_id, reason, coverage, certificate_number, start_date, end_date, and evidence_reference (merchant reads only). Its source can now be order. An issued invoice freezes the same details in snapshot.tax_exemption. The buyer copy omits evidence_reference, and the invoice PDF and receipt show a "Tax exempt" row with the reason and certificate number.

If a record expires, is archived, or changes before a payment attempt's first confirmation or authorization, payment returns 409 ACTION_NOT_ALLOWED with reason configuration_required, and Flint recalculates an ordinary unpaid order's tax. Capturing an established authorization later doesn't reprice it. An issued invoice keeps its frozen amounts; void it and issue a new one to charge tax. An unpaid exchange or replacement return resolution is refused the same way: cancel any open payment attempt on its order, cancel the resolution, create a new resolution, and confirm the new one. Paid sales keep their snapshots.

See Tax-exempt customers.

  • Breaking change
  • API
  • Organizations
  • Merchants

Public organizations API removed#

Breaking: Flint no longer exposes organizations through the public API. Organizations cannot group merchants or other resources, so they no longer have a public resource contract.

The following are removed:

  • All eight organization routes, including organization reads and writes and membership reads and writes.
  • organization_id on Merchant responses and merchant webhook objects, and the organization expansion on GET /v1/merchant.
  • The accounts.organizations.read and accounts.organizations.write scopes.
  • The organization resource type and organization schemas in OpenAPI.

Remove organization API calls and organization scopes from your integrations. Read and update your business profile through GET /v1/merchant and PATCH /v1/merchant. Manage team access in the Dashboard.

  • Breaking change
  • API
  • Orders
  • Fulfillments

Package and order lifecycle actions#

POST /v1/packages/{package_id}/transitions is removed. Send POST to the route matching the former action, and remove action from the body:

Previous actionNew route segmentOperation ID
mark_packed/mark-packedmarkPackagePacked
mark_shipped/mark-shippedmarkPackageShipped
mark_in_transit/mark-in-transitmarkPackageInTransit
mark_out_for_delivery/mark-out-for-deliverymarkPackageOutForDelivery
mark_delivery_attempted/mark-delivery-attemptedmarkPackageDeliveryAttempted
mark_delivered/mark-deliveredmarkPackageDelivered
mark_exception/mark-exceptionmarkPackageException
mark_returned/mark-returnedmarkPackageReturned

Each segment follows /v1/packages/{package_id}. Each request keeps the fields of its former branch, returns Package, and keeps the same scope and optional idempotency key. /void stays available.

A shipped package now accepts /mark-in-transit. While in transit, repeat that action to refresh expected_delivery_at. A changed estimate increments the version and emits package.updated; an unchanged estimate is a no-op. Repeats create no status event or buyer notification. Packages can also move back to in_transit after out_for_delivery or delivery_attempted when occurred_at is at or after their latest recorded status time. An older scan returns 409 ACTION_NOT_ALLOWED with reason out_of_order and latest_status_occurred_at in its details.

Package.supported_actions now includes void when allowed. Shipment publishes supported_actions with void when allowed. Order publishes close when closure is allowed, pay while open without an active attempt and with an outstanding balance or payment-method setup available. These lists describe stored resource facts and do not depend on the caller's permissions.

Buyer fulfillment and package projections no longer publish merchant supported_actions. Read buyer tasks from BuyerOrder.buyer_actions. Merchant Order no longer publishes buyer_actions.

See report carrier progress and object lifecycles.

  • API
  • Promotions

Limit promotions per customer and bind codes to a customer#

Promotions have a new optional field, max_uses_per_customer: a positive integer, or null for no per-customer limit. A customer's count is their reserved and redeemed uses across every code, automatic applications, and applications by promotion_id, in the same merchant and environment. Flint enforces it atomically when payment starts. A failed, canceled, or expired payment releases the use, and a refund doesn't restore it. max_uses stays a separate limit across all customers.

Promotion codes have a new nullable customer_id. A bound code can be redeemed only by that customer. Omit it on create for an unbound code. On PATCH, omit it to keep the binding, send a customer ID to bind the code to that customer, or send null to clear it. GET /v1/promotion-codes?customer_id= is an exact filter and leaves out unbound codes. Catalog and environment copies skip customer-bound codes; recreate the code for that customer in the target environment.

Eligibility rules have a new attribute, customer.paid_order_count, for offers such as "first order only". It counts the customer's other orders in the same merchant and environment that have a settled payment above zero, including a partial payment, or that completed with a zero total, including through a 100% promotion or gift card. Later refunds and disputes don't remove an order. Failed, canceled, and expired payments, unpaid drafts, and unpaid open invoices don't count. Guest purchases count once linked to the customer, including through link_guest_purchases; an unlinked purchase with the same email doesn't. Customer responses don't include this count.

Flint identifies the customer from the order, and otherwise from the customer your server named or verified by email on the checkout session. Customer group, verification, and metadata rules use the same identity. An email typed at checkout never identifies a customer. Three new PROMOTION_DECLINED reasons, all 409, handle the new cases:

  • customer_required: no customer is identified, and the promotion has a per-customer limit or a customer.paid_order_count rule, or the code is bound to a customer.
  • customer_mismatch: a customer is identified, but it isn't the customer the code is bound to.
  • customer_limit_reached: the customer has used the promotion max_uses_per_customer times.

For a first-order offer, combine customer.paid_order_count equal to 0 with max_uses_per_customer: 1, so two checkouts started together can't both reserve the offer. Treat a reason your integration doesn't recognize like not_eligible. See First order only, Give a code to one customer, and the Promotions reference.

  • API
  • Reports
  • Invoices

Receivables aging report#

Create a receivables_aging_v1 report through POST /v1/reports to export unpaid invoice balances in one currency as of a calendar date. Send as_of_date and currency, with an optional timezone that defaults to UTC. The cutoff is the end of that local date, capped at report creation for today's report.

The CSV has one row per unpaid invoice, with payment, credit, write-off, and late fee totals and five aging buckets. Each installment uses its own due date. Today's outstanding totals reconcile to invoice and customer receivables for the same currency when no intervening activity changes them.

POST /v1/reports now has two request branches selected by report_type. Existing report types keep their interval fields. The aging type requires as_of_date instead. Sending as_of_date on an interval report, or interval fields on an aging report, returns INVALID_REQUEST with detail NOT_ALLOWED. Report resources include as_of_date only for aging reports and retain the required interval timestamps.

Each attempt reads one consistent snapshot. Retries or a new report can include later-recorded entries whose effective time precedes the cutoff. QuickBooks, Xero, and NetSuite connectors remain outside these reports.

See Receivables aging for the request, columns, limits, and reconciliation rules.

  • Breaking change
  • API
  • Settings

Receipt settings removed from the settings API#

GET /v1/settings, GET /v1/settings/effective, and PATCH /v1/settings no longer return receipts. Sending receipts in a settings PATCH, including null, now returns 400 INVALID_REQUEST with detail code UNKNOWN_FIELD and param: receipts.

Remove receipts.auto_email_enabled, receipts.header_text, receipts.footer_text, and receipts.is_itemized from your settings requests. These fields were stored but did not change receipt sending or content.

Use customer_email_delivery.order_receipts to choose who sends receipts: flint_sends or merchant_sends. Receipt header, footer, and itemization customization are not supported.

  • Breaking change
  • API
  • Returns

Return receipt overflow reports quantity limits#

Creating a matched Return receipt beyond the outstanding handback quantity or the shipment's remaining allocation now returns 409 LIMIT_EXCEEDED, replacing 409 ACTION_NOT_ALLOWED for the same condition. Update integrations that branch on the old code.

The error includes param: line_items[i].quantity, requested_quantity, and available_quantity. Reduce the matched quantity to the available amount. Record known extra merchandise separately with type: excess.

Process refusals now identify the refusing Return line: a receipt location mismatch uses reason field_locked and param: receipt.receiving_location_id; an already processed line uses reason unsupported_state and param: line_items[i].return_line_item_id.

See Receiving and inspecting returns for receipt quantities and Process a return for the process flow.

  • API
  • Sandboxes
  • Onboarding

Create a sandbox that starts with onboarding not started#

Every sandbox used to start with a verified test identity, so there was nothing to onboard: account sessions had no requirements to collect, and every targeted_requirements code was refused.

  • initial_onboarding on POST /v1/sandboxes. Send not_started to create a sandbox whose requirements stay due. Flint prefills nothing, and readiness reports onboarding_not_started with the create_merchant_account_session action until you onboard the sandbox with the sandbox verification values. The default, complete, keeps today's behavior.
  • The Sandbox resource echoes initial_onboarding. Sandboxes created earlier read complete. A reset returns the sandbox to its initial_onboarding state: a not_started sandbox's replacement starts with no test payment account.
  • Untargetable requirement codes name the alternatives. When a targeted_requirements code can't be targeted, its INVALID_VALUE detail at targeted_requirements[i] now lists the codes the account can target, or says that nothing is outstanding.

See Create a sandbox.

  • API
  • Payments

Set statement text for new payments and read it on payment intents#

Set payments.statement_descriptor with PATCH /v1/settings to choose the static text for new payments. Use 5 to 22 Latin characters, with at least one letter and none of < > \ ' " * or control characters. Omit the field to leave it unchanged, or send null to restore the payment provider's default. This setting does not affect payment readiness.

Payment intents now include the read-only statement_descriptor field. It is null until a charge is created, and remains null if the provider supplies no descriptor. Card payments return the charge's calculated descriptor. Bank and other payment methods return the descriptor recorded for that charge. Changing settings later does not change it. Banks may display the text differently.

  • Breaking change
  • API
  • Subscriptions
  • Webhooks

Subscriptions can exist without a payment method#

Breaking: payment_method_id on merchant and buyer subscription responses and subscription.* webhook objects is now required and nullable. Update types and code that read it as always present, such as code that loads the card to show the last four digits.

Subscription objects also include the new required nullable payment_method_due_at, an RFC 3339 time. While no card is bound, it is the first or upcoming collection deadline. It is null once a card is bound, when an external schedule has no known billing date, and while the subscription is paused or canceled. The subscription.created object for a subscription without a card carries payment_method_id: null and the due time. There is no new status or event.

A subscription with billing_start.type of imported can now be created without a card. Omit payment_method_id and Flint uses the customer's default card. If the customer has no default, the subscription starts without a card. If the default can't be used, the request is rejected. An ID you send that isn't valid is still rejected. Immediate starts, scheduled starts, and trials still require a card at creation.

Bind a card with PATCH /v1/subscriptions/{subscription_id} and payment_method_id. Saving a card or making it the customer's default doesn't bind it. Flint emails the buyer a request to add a card 3 days before the billing date, or right away when the date is closer, when Flint sends subscription lifecycle email. If you set subscription_lifecycle to merchant_sends, ask the buyer yourself and use payment_method_due_at as the deadline.

A renewal with a positive balance and no card doesn't charge. The subscription becomes past_due with no payment attempt or last_payment_error, your dunning end action applies as configured, and scheduled retries wait until a card is bound. A renewal with a zero balance still collects.

See Import without a card.

Superseded in part: a trial with nothing to charge at creation can now start without a card too. See Free trials can start without a card.

  • API
  • Returns

Cancel unpaid replacement resolutions#

You can now cancel an unpaid replacement return resolution after Flint has created its replacement Order, the same way you already could for an exchange. Check supported_actions for cancel before calling.

Canceling ends the open checkout session, reverses the return credit applied to the Order, closes the replacement Order with closed_reason: "return_resolution_canceled", and frees the resolution's quantity for another resolution. Repeating a successful cancellation returns the canceled resolution and doesn't reverse the credit again.

The conditions are unchanged. Creating the Order must be the only effect that completed, and the Order must have no successful or in-progress payment, fulfillment, refund, or other use. A PaymentIntent still waiting for a payment method doesn't block cancellation. Otherwise canceling returns 409.

See Canceling an unpaid exchange.

  • Tax
  • Invoices

Preparing local-currency VAT invoice amounts#

Flint can now store ECB daily euro reference rates and HMRC monthly sterling period rates, including their source and effective dates. This prepares local-currency VAT amounts for invoices and credit notes.

Invoices still show amounts in USD. Continue handling any required local-currency taxable amount, VAT amount, and exchange-rate details outside Flint. See External tax.

  • Webhooks

Previous values on webhook change events#

Webhook status, aggregate, condition, and updated events can now include optional data.previous_attributes. Each member gives the whole previous value of a changed top-level field in data.object. A nested change includes the previous object or array in full; a field absent before the change appears as null.

This applies today only to event families already using Flint's event recorder. Other families gain previous values as they move to the recorder. Older events, events from families still using the legacy emission path, and synthetic test events omit the member. Created, deleted, and notification events never carry it. Accept its absence in your handler.

Previous values exclude bookkeeping fields (updated_at and version), clock-based values, observation fields, and fields that reflect another resource's current state. Their names and values use the same API version as data.object, including on retries and resends after an endpoint version change.

Use previous_attributes to react to a specific field change, such as a plan change, without treating every update as a change to that field. Read Choosing the right event for handler guidance and Webhook delivery for payload and versioning rules.

  • API
  • Checkout
  • Delivery
  • Tax

Delivery country requirements follow method coverage#

Delivery quotes, eligibility previews, pickup availability, and checkout session reads derive address input constraint.supported_countries from delivery methods instead of a fixed US and Canada list. Eligibility and rate-table rows determine coverage; alternative methods widen the list within each choice group. A country can still require a matching subdivision, postal code, or other eligibility input.

Unrestricted delivery coverage excludes CU, IR, KP, and SY. Crimea, Donetsk, and Luhansk are excluded when address data identifies the region.

Orders with automatic tax enabled include read-only tax.supported_countries, currently ["CA", "US"]. Intersect this list with delivery countries when collecting a shipping address. Tax off and external tax omit the field.

Hosted checkout, payment links, and the Apple Pay and Google Pay sheets use these lists: the address form and the sheets offer the countries delivery serves, narrowed to tax.supported_countries under automatic tax. The address form also collects the state or region and postal code for Australia, Germany, France, Ireland, Italy, Japan, Mexico, the Netherlands, New Zealand, Spain, and the United Kingdom as each writes them, and sends state codes as ISO 3166-2 subdivisions, so state conditions match.

  • Breaking change
  • API
  • Checkout
  • Invoices
  • Payment-links
  • Returns
  • Subscriptions

Hosted checkout launches omit checkout_auth_token#

Superseded by The checkout session surface embedded is now headless.

New hosted checkout creation and launch responses now omit checkout_auth_token. They return the hosted url, including its #checkout_token fragment, for opening the buyer's checkout. This applies to order, quick-pay, and subscription-plan checkout creation, keyless payment-link resolution, and invoice and return-resolution checkout launches, including their customer-account forms. New hosted results and their stored idempotency receipts use this URL-only shape. A hosted launch replay whose receipt was stored before this change returns the original response, including checkout_auth_token, until its stored idempotency key expires.

Send the buyer to data.url, or data.checkout_session.url for an invoice launch. If your integration uses checkout_auth_token to run its own checkout UI, send "surface": "embedded" on a create or launch route that supports it. Embedded responses continue returning checkout_auth_token and omit the hosted URL.

Hosted checkout still exchanges the launch token from its URL for the credential it needs. Customer-verification confirmation still returns a new checkout_auth_token when it binds the checkout to the verified customer.

  • API
  • Subscriptions
  • Orders

Download a numbered receipt for each subscription charge#

Each paid subscription charge can now be downloaded as a numbered PDF receipt with GET /v1/orders/{order_id}/receipt-pdf, or with GET /v1/me/orders/{order_id}/receipt-pdf in a customer session. These are the order receipt routes. This covers signup charges, renewals, and change-plan now charges.

A subscription receipt is numbered by the order's order_number and shows the plan name, subscription_cycle, and the period the charge covers. It also shows your tax identity and the buyer's. Flint records both when the charge is paid, so a tax ID added to the customer later appears only on later charges.

Flint records the plan name when it makes a charge, so renaming a plan doesn't change the receipts of earlier charges. A receipt for a charge made before Flint recorded the name shows the plan's current name.

To list a subscription's receipts, use GET /v1/orders?subscription_id= or GET /v1/me/orders?subscription_id=. No new list routes were added. A zero-amount order that only ships an already-paid cycle has no receipt. See Download receipts.

  • API
  • Tax
  • Customers
  • Subscriptions

Automatic tax supports tax-exempt customers#

A customer with tax_exempt: true now gets zero tax in automatic mode. Orders record tax.status: exempt, taxability_reason: customer_exempt, and the customer in tax.exemption. No buyer location, tax calculation, or automatic tax fee is needed. Checkout, invoices, and subscription renewals use the same assessment.

If the customer's exemption is removed before payment starts, Flint marks the order's tax incomplete and returns 409 ACTION_NOT_ALLOWED with reason configuration_required. Update the order's tax to recalculate before retrying payment.

See Tax-exempt customers.

  • Breaking change
  • API
  • Api-keys
  • Errors

Credential types and authentication failures#

Authentication now classifies one bearer credential before checking whether the route accepts its type.

  • A recognized credential on a route that does not accept it returns 401 INVALID_CREDENTIAL with reason: wrong_credential_type, replacing malformed and missing-credential failures. details[0].auth_type names the recognized type, and accepted_auth_types lists the public types the route accepts. Known refresh tokens, device codes and stored secrets cannot authenticate requests. First-party dashboard sessions are omitted from these facts.
  • Expired CLI, partner, onboarding and dashboard credentials report expired. Withdrawn CLI authorization, removed contexts, inactive partner installs or grants, and lost onboarding merchant access report revoked, replacing unknown. These remain 401 INVALID_CREDENTIAL.
  • The Bearer scheme is case-insensitive. Leading and trailing spaces or tabs and spaces or tabs between the scheme and token are accepted. Tokens containing whitespace or non-ASCII bytes are malformed. Unknown flint_ prefixes and unprefixed values without a compact JWS shape are malformed. Onboarding sessions use devsess_v1..
  • More than one Authorization header, even with identical values, returns 400 INVALID_REQUEST with detail NOT_ALLOWED, param: Authorization, and conflicting_fields: ["Authorization"].
  • Missing credentials return AUTHENTICATION_REQUIRED with a message naming the accepted types. Its next steps point to the operation's OpenAPI security requirements.

The top-level OpenAPI extension x-flint-credential-types lists {prefix, auth_type, kind} for each known prefix. See the credential prefix registry for each type and kind. Credential reasons and these type vocabularies are extensible. Keep a fallback for values you do not recognize.

An accepted credential in the wrong mode still returns 403 FORBIDDEN with live_mode_required or test_mode_required.

  • API
  • Tax
  • Delivery
  • Orders

Tax delivery charges on external-tax orders with one template#

POST /v1/orders and PATCH /v1/orders/{order_id} now accept tax.delivery_charge_calculation on orders that use external tax. It has the same price_mode and components as a charge's tax.calculation, with percentage components only. Send null on update to clear it.

When a delivery selection creates a positive delivery charge, including a paid pickup, Flint copies the template onto the charge. Changing the template later doesn't change existing charges. Send tax.charge_calculations to override a generated charge. A new selection creates the charges again and applies the template again.

Without a template, a selection still succeeds. The order's tax status is incomplete, and payment returns 409 ACTION_NOT_ALLOWED with reason configuration_required and names the charge.

Checkout sessions, payment links, and invoices no longer refuse paid delivery methods on external-tax orders. They require tax.delivery_charge_calculation on the order instead, and return 400 INVALID_REQUEST with detail REQUIRED when it's missing. Previously they returned detail NOT_ALLOWED.

Invoices still freeze their totals at issue. A later paid delivery selection changes the taxed order's total and blocks invoice collection. Add delivery as a merchant charge before issue and offer free methods at checkout; see Invoice checkout.

Switching an order that has a paid delivery selection to external tax now treats the generated charge like any other charge: send its calculation in tax.charge_calculations in the same request. See Tax delivery charges.

  • Breaking change
  • API
  • Orders
  • Tax

External tax accepts foreign jurisdictions and VAT and GST types#

External tax now accepts any ISO 3166-1 alpha-2 jurisdiction country and adds country and province jurisdiction levels. Percentage components add vat, gst, hst, pst, and qst; the last three require Canada. retail_delivery_fee remains the only flat tax type.

Country-level jurisdictions outside the US omit jurisdiction.state in responses. US jurisdictions keep the existing two-letter subdivision requirement.

Outside the US, a percentage component can send taxability_reason: reverse_charge with percent: 0. Order breakdowns and invoice documents preserve that reason. Foreign tax types and jurisdictions flow through invoicing, refunds, and row-based reporting. Automatic tax coverage remains US-only. Orders and tax reports remain in USD.

See External tax for subdivision rules and examples.

  • Breaking change
  • API
  • Orders

Lines with nothing to fulfill return a validation error#

POST /v1/orders/{order_id}/fulfillments now returns 400 INVALID_REQUEST with detail code NOT_ALLOWED at line_items[i].order_line_item_id when the named line exists but does not require fulfillment. Previously it returned 404 RESOURCE_NOT_FOUND for that existing line. Unknown line IDs still return 404 RESOURCE_NOT_FOUND.

Check the line's fulfillment_requirements before creating a fulfillment. For an unassigned catalog digital or service line, the error explains that future orders need a manual fulfillment profile on the variant whose allowed_types matches product_type. Existing orders retain their fulfillment requirements. A custom digital or service line needs fulfillment.requirement: "required", resolution_mode: "manual", and its type in allowed_types. See Fulfillment.

  • API
  • Delivery
  • Products
  • Orders

Digital and service variants can use a manual delivery profile#

Variants of digital and service products now accept delivery_profile_id. The profile's configuration must have requirement: "required", resolution_mode: "manual", and allowed_types exactly ["digital"] for a digital product or ["service"] for a service product. Any other profile returns 400 INVALID_REQUEST with detail code NOT_ALLOWED at delivery_profile_id, or at the nested path of the request that carried it.

Nothing changes for variants you leave unassigned. They keep requirement: "none" and delivery_configuration_status: "not_applicable", no default profile applies, and Flint creates no delivery or fulfillment. Delivering from your own app after order.paid stays valid. fee products still reject delivery_profile_id.

Assigning a profile affects future orders only. Order lines keep the fulfillment requirement they were created with, so existing orders don't change. For an order line from an assigned variant, create the fulfillment yourself after the order is paid with POST /v1/orders/{order_id}/fulfillments, then complete it through the usual fulfillment actions. A service line takes a service fulfillment, never a digital one.

See Assign a manual profile to digital and service variants and Fulfillment.

  • API
  • Invoices
  • Billing

Offline payments can be recorded beyond the monthly allowance#

POST /v1/invoices/{invoice_id}/manual-payments no longer returns 409 LIMIT_REACHED with reason external_paid_orders. Record a check, wire or cash payment when you receive it, including after the monthly allowance is used.

Live usage still counts each order once when it is paid in full and at least one payment was recorded outside Flint. Installments and retries do not count again, and a later reversal does not remove the count. Usage resets at the start of each calendar month in New York time. Sandbox payments do not count.

The retired error reason remains readable in historical request logs. Negotiated allowances come from the account's effective agreement.

  • Breaking change
  • Orders
  • Invoices

Order routing inputs and response vocabularies#

Breaking: order creation, order updates, and quick pay invoices now use InventoryRoutingSourceInput instead of OrderInventoryRoutingSourceInput. Send type and only the matching ID: location_id for fixed_location, inventory_allocation_policy_id for policy, or inventory_allocation_policy_revision_id for policy_revision. A missing ID returns 400 INVALID_REQUEST with detail REQUIRED at the ID's path. Fields from another branch return detail INVALID_VALUE.

OrderTaxLocation no longer includes device_id or the device value for address_source. The remaining sources are provided, fulfillment, customer, location, and merchant.

FulfillmentEvent.event_type and BuyerFulfillmentEvent.event_type now publish the eleven values public reads can return: carrier_scan, status_changed, shipped, in_transit, out_for_delivery, delivered, delivery_attempted, tracking_updated, exception, returned, and custom. Status transitions continue to use status_changed, with previous_status and current_status describing the change. The vocabulary remains extensible, so clients must accept future values.

Regenerate clients to remove the retired input type and response constants.

  • API

Find orders by product, variant, or email#

GET /v1/orders now accepts product_id, variant_id, and email before pagination. Product and variant filters match any line item referencing the given ID. The email filter matches the order's buyer_email or linked customer's email using exact equality after trimming and lowercasing, with accents preserved. Send one bare address and encode plus signs as %2B.

Each filter accepts one value and combines with other filters using AND. A valid value with no match returns an empty page. Keep the same effective filters while following page tokens. See List and find orders.

  • API
  • Webhooks
  • Merchants

Partner apps can receive merchant readiness and profile events#

Partner apps can subscribe to merchant.readiness_updated and merchant.updated on webhook endpoints with the installed_merchants event source. The installed merchant's grant must hold merchants.profile.read.

Use merchant.readiness_updated to read GET /v1/merchant with that install's token and act on its current readiness. merchant.updated reports changes to the merchant profile, business name, status, API version, logo, or icon.

Dispute, payout, and balance events still go only to the merchant's own endpoints.

See Partner app installs for endpoint setup and Merchant events for payload details.

  • API
  • Returns

Buyer exchange previews and net original prices#

Buyer exchange and replacement previews now work without pricing_basis. Buyer requests must still omit this merchant-only field. Replacements use original_price. Exchanges use original_price when every replacement matches selected returned merchandise by variant, bundle, or product; otherwise they use current_price.

original_price now supports same-product variant swaps and preserves what the buyer paid after discounts. Exact variant matches come first, then same-product source lines in request order. Each source contributes its own allocated amount, including the same cent remainders a refund would use. Replacement tax is calculated separately.

Merchant exchange and replacement requests still require pricing_basis. Omitting it now returns 400 INVALID_REQUEST with detail code REQUIRED on pricing_basis. An unmatched original_price now returns 400 INVALID_REQUEST with detail code INVALID_VALUE on the affected replacement_line_items[i], instead of a conflict naming an internal type. Preview parameters have a resolution. prefix.

See Choose replacement merchandise.

  • Breaking change
  • API
  • Subscriptions

Plan changes default to an interval the target offers#

Breaking: merchant and buyer plan changes and their previews now select the target plan's own billing_interval and billing_interval_count when both fields are omitted and the target does not offer the subscription's current pair. These requests previously returned 400. If the target offers the current pair, Flint keeps it.

The rule applies to every billing_starts value: now, next_renewal, and period_end. A scheduled period_end change keeps the interval resolved when it was scheduled, including after edits to the target plan.

To choose a particular interval, send both fields explicitly. A pair the target does not offer still returns 400 INVALID_REQUEST, detail code INVALID_VALUE, on billing_interval. Its message now names the requested pair and all offered pairs.

Creating or updating a subscription plan or offer with several interval options and no lines that ship returns the response warning billing_interval_options_same_price. Every option bills the same line prices once per period. For example, a USD 15.00 line bills USD 15.00 each year on yearly; prices are not scaled to an annual amount. Use separate plans for different prices per interval.

See Choose the plan change interval and Offer intervals and quantities.

  • API
  • Subscriptions

Record who requested a subscription cancellation#

POST /v1/subscriptions/{subscription_id}/cancel now accepts optional initiated_by: buyer, merchant, or integration. It defaults to merchant, including when the request body is omitted. Flint records the value in cancellation_details.requested_by and cancellation_reason, including in subscription webhooks. Both response vocabularies remain extensible and now include integration.

On merchant cancel and skip-cycle routes, initiated_by records attribution only. It does not apply the store's buyer limits. To enforce those limits, use a customer session on POST /v1/me/subscriptions/{subscription_id}/cancel or POST /v1/me/subscriptions/{subscription_id}/skip-cycle. These routes always record buyer and do not accept initiated_by.

  • Breaking change
  • API
  • Refunds
  • Invoices

Credit-note refunds move to the refunds API#

Superseded by Credit-note refunds return gift cards first.

Breaking: POST /v1/credit-notes/{credit_note_id}/refunds and GET /v1/credit-notes/{credit_note_id}/refunds have been removed.

Create refunds through POST /v1/refunds with refund_type: credit_note and credit_note_id. Omit amount_money to refund all available credit, resolved once when Flint accepts the request. Replace expected_version with expected_credit_note_version; stale versions return 409 VERSION_CONFLICT at that field with details[0].current_version. Creation still needs both commerce.refunds.write and commerce.credit_notes.write, and requires an Idempotency-Key.

List through GET /v1/refunds?credit_note_id=..., with commerce.refunds.read. Results use refund created_at descending with refund_id as the tiebreaker, replacing ordering by when each refund was applied to the note. Unknown or other-merchant credit note IDs return an empty page. Recover a lost response with GET /v1/refunds?idempotency_key=...; this also finds refunds created by issuing a credit note with refund, using the caller's original issue key.

reason is optional on both the new variant and issueCreditNote's refund input. Omit it to record no reason, send none to the processor, and omit the reason line from the buyer email. reason_message accepts 1 to 1,024 characters on every refund type and on issue-with-refund; a longer note returns 400 INVALID_REQUEST at the field. The new variant also accepts metadata and external_reference_id.

Credit-note refunds now return the invoice's gift card payments first, then card and bank payments. See Credit-note refunds return gift cards first.

  • Breaking change
  • API
  • Customers

A customer with no email can be given one in either account mode#

Breaking: a missing email can be set in flint_hosted mode. PATCH /v1/customers/{customer_id} used to return 409 ACTION_NOT_ALLOWED with details[0].reason managed_externally for an email in flint_hosted mode. It now accepts email when the customer has none. Changing, case-changing, or clearing an existing email still requires merchant_hosted. In either mode, an email another customer has returns 409 ALREADY_EXISTS.

Breaking: a paid checkout session can fill a missing email. When the order's customer has no email, Flint sets it to the buyer_email the checkout collected once the payment settles. It does this before it sends the buyer's notices or provisions a subscription, so they have an address. It never replaces an existing email and changes no other customer field. When another customer in the environment already has the address, the customer stays without an email and the order keeps the buyer's contact. Paying an order with an API key and no checkout session never changes the customer.

If your code assumes a customer created without an email stays without one after checkout, read email from the customer again. See Who can change the email and Associate the customer before collection.

  • API
  • Disputes
  • Webhooks

Disputes include network reason codes and evidence recommendations#

Dispute.network_reason_code carries the card network's opaque reason code. Read it with the disputed payment's card brand, because codes differ by network. It is null when the network supplied no supported code. A code change can send dispute.updated.

Dispute.recommended_evidence_types lists the evidence types Flint recommends for the stored reason and case type, most useful first. Use the ones that fit what you sold. It is [] when Flint has no recommendation, including bank returns. The evidence vocabulary is extensible, so integrations must tolerate new types.

Both fields are always present in dispute responses and webhook payloads. Webhook recommendations are captured with the dispute snapshot. See Prepare evidence for the mapping and what each type means.

  • Breaking change
  • API
  • Orders
  • Inventory

Inventory errors identify the cause and short demand#

Inventory failures on order payment, delivery quotes, checkout, and fulfillment no longer all return 409 INVENTORY_INSUFFICIENT. Branch on the error code and details[0].reason:

  • A fixed Location with inventory_allocation_enabled: false returns 409 ACTION_NOT_ALLOWED with reason configuration_required, naming the Location. Payment refuses it before creating an attempt. Enable allocation before paying again.
  • A missing Location named in the request returns 404 RESOURCE_NOT_FOUND at that field. A missing Location in saved routing returns 409 ACTION_NOT_ALLOWED with reason configuration_required. Correct the routing source.
  • An inactive Location or unavailable item or allocation policy returns 409 ACTION_NOT_ALLOWED with reason unsupported_state. Change the named resource or routing source.
  • An inventory race returns 409 CONCURRENT_MODIFICATION when the same request can succeed on retry. If the request must be rebuilt, it returns 409 VERSION_CONFLICT naming the order. Follow the error's retry guidance.
  • An order-owned reservation that already exists unexpectedly, belongs to another owner, or is closed returns 500 INTERNAL_ERROR. A merchant-created reservation that prevents the operation returns 409 RESOURCE_IN_USE.
  • A routing dependency failure returns 503 SERVICE_UNAVAILABLE. Retry with backoff.

For stock shortages on pay, quote, checkout, and reservation create, INVENTORY_INSUFFICIENT has one details item per short demand, ordered by request position, then demand_key. Each item has the opaque demand_key, inventory_item_id, requested_quantity, available_quantity, and shortage_quantity. For an order demand, it also has order_id and order_line_item_id. It includes bundle_component_id or inventory_reservation_line_id when applicable. Buyer credentials receive the same facts except inventory_item_id. Use the line identity directly; don't parse demand_key for it. The details don't include variant_id or bundle_id.

Shortage param values point only to input in the current request: demands[i].quantity on reservation create. Pay and quote omit param. Top-level error fields mirror the first detail. Replace checks for the old unindexed demands or lines params.

A reservation commit or consume refused because stock is at risk now returns 409 ACTION_NOT_ALLOWED with reason stock_at_risk, remediation.retry: "none", and error_source: "merchant". Each detail names an affected inventory_reservation_line_id; the error no longer points to the nonexistent request field inventory_reservation_line_ids. Flint records inventory_action_required and its event separately after the refusal. Retrying with the same Idempotency-Key returns the same refusal. Replenish, reallocate, or release the affected stock, then send a new request with a new key.

  • Breaking change
  • API
  • Customers

JSON bodies reject null and rate limits name credentials#

JSON routes now reject a request body of null with 400 INVALID_REQUEST, detail code INVALID_VALUE, and param: body. Previously, some routes treated null as an empty object, which could create an empty customer or leave an update unchanged. Send a JSON object instead. On routes with an optional body, you can still omit the body or send {}. This does not change which individual fields accept null.

Flint-Rate-Limited-Reason: credential replaces api_key for a credential's own rate limit, including API keys and customer session secrets. Update any handling that matches the old value. The shared customer and merchant reasons remain customer and merchant.

In RateLimit-Policy and RateLimit, policy names <class>.credential.second and <class>.credential.minute replace <class>.key.second and <class>.key.minute. Update parsers that match those names. Quotas and retry timing are unchanged. See Rate limits.

  • Breaking change
  • API
  • Errors
  • Orders

Error recovery instructions fit the request#

Breaking: when an order has no receipt email on file and a send-receipt request omits email, a credential that may send email now receives 400 INVALID_REQUEST with a REQUIRED detail at email, instead of 409 ACTION_NOT_ALLOWED with reason configuration_required. The message is "email is required because this order has no receipt email on file." Send email in the corrected request. POST /v1/payment-intents/{payment_intent_id}/send-receipt returns the same response for an order-owned payment intent.

If the credential cannot send email, such as a buyer session, the missing stored address remains 409 ACTION_NOT_ALLOWED with reason configuration_required. Update status-based handling of send-receipt errors to recognize the validation response.

remediation.next_steps now follows the specific failure's instruction, then the reason's instruction, then the code's default. On a route that takes an Idempotency-Key, a request that sent a nonblank key gets one of these sentences:

  • same_request: "Keep the same Idempotency-Key."
  • after_refresh: "Use a new Idempotency-Key."
  • INVALID_REQUEST: "Use a new Idempotency-Key for the corrected request."

Other none errors get no extra sentence; a new attempt is a new request and needs a new key. Routes that take no key and requests that sent no key get no key instruction. The three idempotency error codes describe key handling directly.

An unsupported limit or per_page query parameter now suggests page_size in details[].suggestions, and starting_after or cursor suggests page_token, when the route accepts that parameter.

See Error handling and Retry after an error.

  • Breaking change
  • API
  • Returns
  • Refunds
  • Credit-notes

Return fees use refundable value and credit-note refunds use gift cards first#

Percentage restocking fees now apply to the returned units' refundable value before the fee, after discounts and including allocated tax. Previously they applied to gross subtotal. A $18.00 unit discounted to $16.20 with a 10% fee now deducts $1.62 instead of $1.80. For each return, percentage fees use its pinned policy percentage and round down to the smallest currency unit. Fees across several returns under the same percentage never add up to more than that percentage of what was paid. At 50%, units allocated $14.37, $14.37, and $14.36 incur fees of $7.18 each, totaling $21.54, below the $21.55 policy cap. Earlier fees, waivers, failures, and policy revisions do not change a new return's fee. This applies to refunds, exchanges, and store credit. Flat fees keep their fixed amount; both fee types are capped at the returned units' refundable value.

Credit-note refunds now include original gift-card principal applied to the invoice and use the same tender planner as direct and Return refunds: gift cards first, then processor payments. Previously credit-note refunds considered only processor payments. Each refund stays within the invoice's applied payment principal and excludes tips. Named line items, charges, and flat tax on direct and Return refunds still go back to the tender that paid for them.

Processor-only refunds also use this planner and require the order's original settlement allocations, just as mixed-tender refunds do.

Update calculations that predict restocking fees or credit-note refund tenders. Read the Refund's tender_allocations to reconcile where value went. Existing committed refunds keep their stored allocations when replayed.

See return policy fees, Return refund destinations, and refund tender allocation.

  • Breaking change
  • API
  • Merchants
  • Customers
  • Orders

Consistent postal address and email validation#

Breaking: New and updated email contacts require one bare email address with a valid host and at most 320 characters. Display names, whitespace, incomplete addresses such as a.b@, and malformed hosts such as a@bad_domain.example are rejected. Plus addressing and internationalized domain names remain supported.

This applies to merchant email and support_email, onboarding contact and owner updates, customer and buyer contact updates, gift card recipients, notification contacts, receipt recipients, reply-to addresses, new risk-list email entries, tax setup contacts, and invoice preview recipients. Field-specific limits still apply: payment-intent receipt_email allows at most 255 characters, while explicit order and payment receipt recipients allow at most 254. Requiredness, clearing, and recipient-list policies are unchanged.

Complete postal addresses now share one country-dependent contract across merchant profiles, saved customer addresses, Locations, order deliveries, subscription addresses, checkout prefill, invoice remit-to addresses and defaults, and document tax identities. Send line1, city, and an uppercase ISO 3166-1 alpha-2 country. US addresses also require state and postal_code; other countries may omit either. For example, a Hong Kong address can omit both. Where the input supports null, it also represents omission. Supplied blank strings are rejected. New and replacement merchant and document-identity addresses now reject unrecognized country codes consistently with public address inputs.

Email-based sign-in, verification of existing customers, lookups, filters, and wallet identity checks retain their existing validation rules. Checkout verification that creates a new customer applies the new contact email rules. Stored contacts and provider-prefilled values remain usable for unrelated updates, subscription renewals, receipt delivery, and purchases made before these rules changed.

Tax operations still require the geography needed to calculate tax. Saving a complete postal address doesn't guarantee that it contains enough information for tax calculation. Partial delivery and postal-code tax inputs keep their separate rules.

Before sending contact updates, remove display names and spaces and correct malformed domains. When saving a non-US address, omit fields it doesn't use rather than sending empty strings. See Merchant profile updates and Customer addresses.

  • Breaking change
  • API
  • Subscriptions
  • Customers

Subscriptions require a customer email#

Breaking: POST /v1/subscriptions requires the customer to have an email in both customer account modes. A customer without one is refused with 409 and CUSTOMER_EMAIL_REQUIRED on param: customer_id. A subscription preview for that customer returns is_valid: false with the same code. Existing subscriptions are unchanged.

A customer's email can't be cleared while they have a subscription that isn't canceled. See subscriptions and customers.

  • Breaking change
  • API
  • Subscriptions

Imported subscriptions count the current paid period#

Breaking: billing_start.completed_cycles for billing_start.type: "imported" now defaults to 1 and must be at least 1, including the period already paid on the previous billing system. Previously it defaulted to 0 and accepted an explicit zero.

When you omit the field, the subscription reports completed_cycles: 1 and its first Flint renewal has subscription_cycle: 2. Send the full count from the previous system to continue a longer billing history. An explicit 0 returns 400 INVALID_REQUEST with detail code INVALID_VALUE and param: billing_start.completed_cycles. Create previews apply the same default and validation.

Skip-cycle, pause, cancel, and renew now accept an empty body on both /v1/subscriptions/{subscription_id} and /v1/me/subscriptions/{subscription_id} action routes. An empty body uses the same defaults as {}.

See Importing subscriptions for the billing start options.

  • Breaking change
  • API
  • Subscriptions
  • Webhooks

Schedule a subscription plan change for the next charged renewal#

billing_starts now accepts period_end on merchant plan changes, plan change previews, and plan plan_change_options. It keeps the current plan until the next renewal Flint charges, then applies the target terms frozen when the change was scheduled. next_renewal still switches the plan immediately and charges its price from the next payment.

Breaking: the closed response vocabulary subscription_plan_change_billing_starts gains period_end. Update exhaustive timing checks in your integration. The added snapshot fields, result field, buyer action, and webhook event types are additive.

Every subscription includes the required nullable scheduled_plan_change snapshot. It records the target plan, interval, quantity, recurring subtotal, requester, scheduling time, and nullable effective_at. The buyer projection also includes the target plan summary. Every plan change result includes the required billing_starts used; plan change previews include required nullable effective_at.

Send scheduled_plan_change: null with a subscription PATCH to keep the current plan. Other values are invalid. Clearing an already empty field leaves the version unchanged and sends no event. Buyers can clear only buyer-scheduled changes through the new cancel_plan_change action; clearing a merchant-scheduled change returns 409 ACTION_NOT_ALLOWED, reason not_offered.

Scheduling or replacement sends the snapshot event subscription.plan_change_scheduled. An explicit clear sends subscription.plan_change_canceled. Applying the change uses subscription.plan_changed; cancellation and supersession clear it without an extra canceled event. Changes to the effective date alone do not send a replacement event. Flint sends no plan change email.

Pauses and skips keep the change pending until a charged renewal. Order now applies it before the early charge, and archived target plans still apply their frozen terms. A failed boundary payment and its retries use the new plan. Pending changes block cadence, quantity, and line edits with reason plan_change_scheduled.

See Schedule or clear a pending change and Let buyers change plans.