Skip to content
Changelog

Week of October 12, 2026

96 changes to the Flint API, SDKs, and docs, newest first, from October 12, 2026 to October 18, 2026. The newest changes are on the changelog.
  • API
  • Orders
  • Payments

Payments made with your API key take Apple Pay and Google Pay#

Superseded by Create order payments through the payment intents collection.

Payment intents you create with your API key, and payments on orders you create with it, now accept Apple Pay and Google Pay. Before, a wallet on these payments returned 400 PAYMENT_OPTION_NOT_ALLOWED ("apple_pay is not supported for api payments"). Orders from payment links and Flint-hosted checkout already took wallets.

  • A wallet ConfirmationToken or a saved wallet card works with your API key on POST /v1/orders/{order_id}/pay and POST /v1/payment-intents/{payment_intent_id}/confirm, including an off-session charge of a saved wallet card.
  • apple_pay and google_pay are accepted in payment_options on POST /v1/payment-intents and POST /v1/orders/{order_id}/payment-intents.
  • Wallets on these payments have the same limits as cards: up to $100,000 per payment, or $250,000 with an approved higher limit. A limit you set in the dashboard for payments made with your API key also applies to wallets.

A one-shot POST /v1/orders/{order_id}/pay sends no list of payment options, so Flint starts from your checkout settings. The payment intent it creates now leaves out the options this payment can't use, and its payment_options lists the rest:

  • Affirm, when the request has no checkout session. Affirm needs a page to send the buyer back to, and on this route only a checkout session provides one.
  • Options outside your payment limits for the amount, such as ACH debit on a payment below its minimum.

Before, any of these refused the whole payment, even one made with a card. For example, with Affirm turned on and wallets off, a card payment between $50 and $30,000 returned 400 FIELD_REQUIRED for payment_return_url, and an ACH debit maximum on your account refused a larger card payment with AMOUNT_EXCEEDS_LIMIT. When an option you request yourself, or the credential you pay with, is outside a limit, Flint still refuses it with the same error.

  • Breaking change
  • API
  • Api-keys

Create API keys from a scope preset#

POST /v1/api-keys, POST /v1/developer/sandboxes with issue_test_key: true, and POST /v1/developer/sandboxes/{sandbox_id}/test-key accept scope_preset in place of scopes. full_access grants every scope a key in the new key's mode can hold that the caller can grant; a key grants only scopes it holds. read_only grants the read scopes of that set. Flint resolves the preset when it creates the key and stores the result as the key's scopes, so scopes added later aren't added to the key. {"name": "ci", "scope_preset": "full_access"} is a complete request. access replaced scope_preset on 2026-10-27; see Key access.

Breaking: each of these routes takes exactly one of scopes or scope_preset. Sending neither returns 400 INVALID_REQUEST with detail REQUIRED and param: scopes, including from an onboarding session, which no longer gets a default scope set on the sandbox routes. Sending both returns detail NOT_ALLOWED with both fields in conflicting_fields. POST /v1/developer/sandboxes without issue_test_key: true now rejects scopes, scope_preset, and test_key_name with detail NOT_ALLOWED instead of ignoring them. The sandbox routes' scopes items now publish the scope enum.

Breaking: the POST /v1/developer/sandboxes response no longer has a top-level secret_key. The issued test key at data.api_key has the same shape as POST /v1/api-keys data, so read the secret from data.api_key.secret_key.

  • Breaking change
  • API
  • Catalog

Products and bundles reference categories by handle only#

Breaking: POST /v1/products, PATCH /v1/products/{product_id}, POST /v1/bundles, and PATCH /v1/bundles/{bundle_id} take category_handles instead of categories. Each value must exactly match the handle of a category that already exists. Flint no longer matches category names, normalizes the value, or creates a category from a product or bundle write. Create categories with POST /v1/categories first.

A handle that matches no category returns 404 RESOURCE_NOT_FOUND with param naming the entry, such as category_handles[2], and details[0].resource_type set to category. Nothing is saved. A handle sent twice returns 400 INVALID_REQUEST. The INVALID_CATEGORY and AMBIGUOUS_CATEGORY codes are removed.

Sending category_handles on a product or bundle update replaces the categories without expected_version. If you send expected_version, Flint still checks it. Responses still return categories as {category_id, handle, name} objects.

PATCH /v1/categories/{category_id} accepts metadata: null to remove all of your metadata keys. Concurrent category updates are applied one after the other, so the CATEGORY_MODIFIED code is removed.

  • Breaking change
  • API
  • Catalog
  • Promotions

Product and promotion create return their variants and codes#

Superseded by Promotion codes, gift card loads, and buyer transactions use top-level routes.

POST /v1/products returns variants: every variant the request created, ordered by position and then variant_id, in the same shape GET /v1/products/{product_id}/variants/{variant_id} returns. A simple product returns its default variant there. You no longer need to list the variants and match them back by SKU to learn their IDs. Other product responses leave variants out; GET /v1/products/{product_id}/variants lists them.

POST /v1/promotions returns codes: the codes the request created, in request order, each with its promotion_code_id. An automatic promotion returns codes: []. Other promotion responses leave codes out; GET /v1/promotion-codes?promotion_id= lists them.

Breaking: product create accepts at most 100 variants, and promotion create accepts at most 100 codes. More returns 400 INVALID_REQUEST with param set to variants or codes. Add more variants with POST /v1/products/{product_id}/variants and more codes with POST /v1/promotions/{promotion_id}/codes.

  • Breaking change
  • API
  • Customers
  • Errors

Customers without an email, create-or-return by email, and null for empty fields#

Email is optional. POST /v1/customers creates a customer without email, for example a buyer at the register who doesn't give one. Any number of customers can have no email. Customer.email and the expanded customer on orders, payments, invoices, and other resources are null for them.

Create or return. Send on_email_conflict: "return_existing" with email, and Flint returns the customer that already has that email, unchanged, with 200. When none does, Flint creates the customer and returns 201. The default, error, keeps today's conflict. return_existing without email returns 400 INVALID_REQUEST with detail REQUIRED and param email. Two requests racing for one new email both get the same customer. A replay with the same Idempotency-Key returns the original status and body. See Headless storefront.

Duplicate emails return ALREADY_EXISTS. 409 CUSTOMER_EMAIL_ALREADY_USED is now 409 ALREADY_EXISTS with param email, on POST /v1/customers, PATCH /v1/customers/{customer_id}, and /v1/me/email-change-requests. With merchant credentials, details[0].current_resource names the customer that has the email, {"resource_type": "customer", "resource_id": "cus_..."}, replacing blocking_resources and blocking_resource_count. Buyer credentials don't receive the other customer.

Merchant email changes. When your store's customer_account.mode is merchant_hosted, PATCH /v1/customers/{customer_id} accepts email and null clears it. The change keeps the buyer's customer sessions, cancels an email change the buyer had started, and sends customer.updated. With a Flint-hosted account (flint_hosted, the default), the email is how the buyer signs in, so a different email or null returns 409 CUSTOMER_EMAIL_BUYER_MANAGED; the buyer still changes it through /v1/me/email-change-requests. See Customers.

Empty fields are null. Customer responses and customer.* webhooks always include name, email, phone, internal_note, external_reference_id, and segment, with null when there's no value. Before, a cleared or never-set field was omitted. Customer sessions reading /v1/me still don't receive internal_note, external_reference_id, or segment. The expanded customer summary always includes name, email, and phone, with null when empty.

Gift card purchases need the buyer's email. Buying a gift card with a payment whose customer has no email returns 409 GIFT_CARD_BUYER_EMAIL_REQUIRED instead of a verification error. Gift card purchase limits are tracked by the buyer's email.

  • Breaking change
  • API
  • Errors

Stale versions return VERSION_CONFLICT, and status refusals return ACTION_NOT_ALLOWED#

Correction: This entry originally said the change covered every endpoint. The October 18 rollout covered the routes whose retired codes are listed below. It did not cover products, variants, bundles, subscriptions, subscription plans, risk rules, orders, order line items, or delivery selection fences. It also did not add the promised current_api_version fact to API version pin conflicts.

Breaking: on the routes listed below, a stale expected_version, or another stale expected_* value, returns 409 VERSION_CONFLICT. param names the field you sent, and details[0] carries resource_type, resource_id, and current_version when known. Read the resource and retry with its current version. These codes are removed:

  • SETTINGS_CONCURRENT_MODIFICATION, INVOICE_DRAFT_CHANGED, CREDIT_NOTE_CHANGED, MERCHANT_CHANGED, MODIFIER_GROUP_CHANGED, MODIFIER_SET_VERSION_CONFLICT, PAYMENT_LINK_CHANGED, GIFT_CARD_VERSION_CONFLICT, SUBSCRIPTION_OFFER_VERSION_CONFLICT, API_VERSION_CHANGED, and LOCATION_CHANGED.
  • INVENTORY_CHANGED, INVENTORY_COUNT_CHANGED, and INVENTORY_TRANSFER_CHANGED. Inventory no longer picks a code from the URL.

When a write loses internal contention before any effects begin and your basis is still current, it returns 409 CONCURRENT_MODIFICATION. This includes requests without a fence and requests whose fence still matches. The failed request applied no changes. Retry the same request with the same Idempotency-Key.

A few writes can lose that race after part of the change has started, so retrying the same request isn't safe for them. They keep their codes without param when you sent no expected_version, and return VERSION_CONFLICT when you did: FULFILLMENT_CHANGED, SHIPMENT_CHANGED, PACKAGE_CHANGED, RETURN_VERSION_CONFLICT, and DELIVERY_RESOURCE_VERSION_CONFLICT. Re-read the resource and retry.

A missing expected_version where a write requires one returns 400 INVALID_REQUEST with details[0].code REQUIRED, and one that isn't a positive integer returns INVALID_VALUE, both with param expected_version. ORDER_REVISION_REQUIRED, INVALID_EXPECTED_VERSION, and DELIVERY_EXPECTED_VERSION_INVALID are removed. This replaces the October 16 note that kept ORDER_REVISION_REQUIRED.

A refusal because of the resource's status returns 409 ACTION_NOT_ALLOWED, with resource_type, resource_id, current_status, and supported_actions when the resource publishes them:

  • Inventory transfers, counts, and reservations. INVENTORY_TRANSFER_ACTION_NOT_ALLOWED and INVENTORY_RESERVATION_CLOSED are removed; a closed reservation keeps closed_reason. Committing a reservation after owner.expires_at returns ACTION_NOT_ALLOWED with details[0].reason expired instead of INVENTORY_RESERVATION_EXPIRED.
  • Changing an archived product or subscription plan, with current_status: archived. PRODUCT_ARCHIVED and PLAN_ARCHIVED are removed.

Also:

  • Applying an inventory count after stock at a counted level moved returns 409 INVENTORY_COUNT_PHYSICAL_REVISION_CHANGED as the top-level code, the code its details already used.
  • An unknown category handle on a promotion rule, return policy, or return reason returns 404 RESOURCE_NOT_FOUND with param naming the entry and details[0].resource_type category, like product and bundle writes. UNKNOWN_CATEGORY_HANDLE is removed.
  • A Location that is still in use returns LOCATION_IN_USE in details[0].code as well as the top-level code. The LOCATION_CONFLICT detail code is removed.
  • When Flint can't authenticate checkout session credentials because of a server problem, the request returns 503 SERVICE_UNAVAILABLE with remediation.retry same_request instead of 401 CHECKOUT_SESSION_AUTH_UNAVAILABLE.

See Error handling.

  • Breaking change
  • API
  • Inventory

Inventory adjustments say what happened#

Breaking: adjustment lines no longer take signed changes. on_hand_quantity_delta, quality_control_quantity_delta, damaged_quantity_delta, and quarantined_quantity_delta are removed from the request, and reason now decides what each line carries:

  • received and returned add quantity to on hand; sold, theft, and loss remove it. An optional condition (sellable by default, quality_control, damaged, or quarantined) says where the units land or come from.
  • condition_changed moves quantity from from_condition (sellable by default) to to_condition and leaves on hand unchanged.
  • counted and correction set any of on_hand_quantity, quality_control_quantity, damaged_quantity, and quarantined_quantity to the values you send and leave the others unchanged. correction requires note.

Breaking: the reasons received_stock, damage, manual_correction, and other are removed, from the request, InventoryAdjustment.reason, the reason list filter, and movement reasons. Use received for received_stock, condition_changed with to_condition: "damaged" (or loss with condition: "damaged") for damage, and correction for manual_correction and other.

New: sold records a sale made outside Flint in one call. It doesn't check availability, so selling into claimed stock creates a shortage and flags the affected reservations; only a sale that would take stock below zero returns 409 INVENTORY_INSUFFICIENT.

New: a counted or correction line accepts expected_physical_version (0 for a level that doesn't exist yet), which returns 409 VERSION_CONFLICT with current_physical_version when on-hand or a condition changed since you read the level. Holds and commitments don't change it. It also accepts source_observation_sequence, which returns 409 INVENTORY_SOURCE_SEQUENCE_CHANGED and applies nothing unless the value is newer than the last one accepted for that source, item, and Location. Counts from the same source share the sequence.

Breaking: InventoryAdjustmentLine.inventory_movement_id can be null. A counted or correction line that already matches the level writes no movement; the level still appears in resulting_inventory_levels. Each line now always includes its four *_quantity_delta fields, including zeros, so the change a line made is readable without a default.

An adjustment sent without source_system now records source_system.type: "manual", as reservation transitions and safety stock changes already do.

  • Breaking change
  • API
  • Locations

One PATCH for Locations, with a flat allocation status#

Breaking: PATCH /v1/locations/{location_id}/geography and PATCH /v1/locations/{location_id}/inventory are removed. Send address, timezone, coordinate, coordinate_source, and inventory_allocation_status to PATCH /v1/locations/{location_id}, alone or together with name, status, metadata, and external_reference_id. expected_geography_revision and expected_inventory_revision are gone; the optional expected_version covers every field. A Location's version now advances on every change, including geography and allocation.

address is still replaced as a whole. A request that sends address must also send coordinate, as the new coordinate or null to clear it; without it the request returns 400 INVALID_REQUEST with detail REQUIRED and param: coordinate. An address change no longer clears an omitted coordinate. coordinate_source is sent with a coordinate and cleared with it. geography_version stays on the Location as a read-only value that advances only when the geography changes.

Breaking: the Location inventory object, with its allocation_status and inventory_version, is replaced by inventory_allocation_status (active or inactive) on every Location response. It is returned with merchants.locations.read alone, and the inventory_allocation_status list filter no longer needs commerce.inventory.read. On POST /v1/locations, send inventory_allocation_status instead of the inventory block; it defaults to inactive. Writing it on create or PATCH requires commerce.inventory_locations.write.

Breaking: every Location can hold stock. Adjustments, counts, transfers, and Return restocks no longer return 409 INVENTORY_LOCATION_NOT_CONFIGURED; that code, LOCATION_GEOGRAPHY_CHANGED, and LOCATION_INVENTORY_CHANGED are removed. inventory_allocation_status still decides whether reservations, allocation policies, order holds, and pickup use the Location's stock. Routing no longer reports the inventory_not_configured eligibility reason, and an active allocation no longer blocks setting a Location to inactive.

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

Mode and sandbox_id name the environment everywhere#

Superseded by Context headers must match fixed credentials.

The API now names where a request runs with mode (test or live) and, in test mode only, sandbox_id.

Breaking: responses no longer carry Flint-Merchant-Environment-Id. Read Flint-Mode, and Flint-Sandbox-Id in test mode, which every test-mode response now carries, including public checkout, payment link, invoice, and gift card reads. A CLI OAuth request that sends a Flint-Sandbox-Id header that disagrees with the token's sandbox returns 403 FORBIDDEN with details[0].reason oauth_context_mismatch and param Flint-Sandbox-Id.

Breaking: GET /v1/oauth/authorize takes sandbox_id instead of environment_id, and GET /v1/oauth/authorize/preview accepts it too. Send it only with mode=test; omit it to install into the merchant's default sandbox. With mode=live it returns invalid_request. PartnerEnvironmentGrant.environment_id becomes sandbox_id, present only on test grants, on the install routes and in partner_app_install.* events. Installed-merchant partner events carry source.sandbox_id in test mode instead of source.environment_id.

Breaking: partner webhook endpoints drop mode (test, live, or both). An endpoint whose event_sources includes installed_merchants sends installed_merchant_modes, ["test"], ["live"], or ["test", "live"]; it is required there and returns 400 INVALID_REQUEST with detail NOT_ALLOWED on any other endpoint. Lifecycle events from partner_app arrive in both modes, so one endpoint can now carry lifecycle events and live installed-merchant events together.

Breaking: POST /v1/api-keys no longer takes sandbox_id. A test key mints a test key in its own sandbox, and a live key mints a live key. SANDBOX_ID_NOT_ALLOWED is removed. To mint a test key with a live key, use POST /v1/developer/sandboxes/{sandbox_id}/test-key.

Breaking: POST /v1/oauth/device/authorize and POST /v1/oauth/device/reauthorize take mode (test or live, default test) instead of environment.

Breaking: ResourceTimeline and its entries drop environment_id. The timeline belongs to the environment of the key that reads it.

An onboarding request whose partner install token names a different sandbox now returns 403 FORBIDDEN with details[0].reason sandbox_selection_forbidden, the same reason as other credentials, instead of environment_selection_forbidden.

  • Breaking change
  • API
  • Promotions

Promotions and codes report availability apart from status#

Breaking: a promotion's status is now active, inactive, or archived. It no longer reads expired, not_yet_started, exhausted, or no_active_codes. Those states move to two new fields on every promotion:

  • available is true when the promotion can apply right now: it is active, inside its schedule, under its max_uses, and, when code-gated, has a code a buyer can redeem.
  • unavailable_reason says why when available is false: inactive, archived, not_yet_started, expired, exhausted, or no_active_codes.

So a promotion you set to active with a future schedule.starts_at reads status: active, available: false, and unavailable_reason: not_yet_started.

Breaking: a promotion code's status is now active or inactive. It no longer reads expired or exhausted. Codes gain available and unavailable_reason too, and a code's availability now includes its promotion: an active code under an inactive, ended, or archived promotion reads available: false with unavailable_reason: promotion_unavailable. The code's own inactive, expired, or exhausted comes first.

Breaking: the status filter on GET /v1/promotions takes active, inactive, and archived, and on GET /v1/promotion-codes it takes active or inactive. Both lists take a new available=true|false filter. To list promotions that can apply now, use GET /v1/promotions?available=true instead of status=active.

Breaking: the promotion decline reason disabled is renamed inactive, in PROMOTION_DECLINED errors, meta.warnings[].reason, and discount preview candidates.

Errors that report a promotion's or code's details[0].current_status, such as PROMOTION_DECLINED and PROMOTION_NOT_REDEEMABLE, now carry its status value. SUBSCRIPTION_OFFER_PROMOTION_UNAVAILABLE adds the promotion's unavailable_reason as details[0].reason.

Promotion status has the details.

  • Breaking change
  • API
  • Returns

A Return lists its children by ID and expands them in one read#

Breaking: receipt_count, inspection_count, disposition_count, resolution_count, and shipment_count are removed from the Return, and resolution_count from each Return line. In their place, every Return response carries return_receipt_ids, return_inspection_ids, return_disposition_ids, return_resolution_ids, and shipment_ids, oldest first, and each line carries return_resolution_ids. An array keeps every child in every status, so its length is the count the removed field reported. A /v1/me read carries only return_resolution_ids.

GET /v1/returns/{return_id} now expands return_receipts, return_inspections, return_dispositions, return_resolutions, and shipments, each in the order of its ID array. Each expansion returns up to 100 objects; past that the read returns 400 INVALID_REQUEST with detail INVALID_VALUE and param: "expand", and you page the collection from its list route with return_id. Expanding shipments also needs commerce.orders.read. See Read a whole Return.

An expanded shipment summary, on Returns and on fulfillments, now includes return_id when the shipment sends a Return's items back.

  • Breaking change
  • API
  • Subscriptions

Subscriptions show next_billing_at only while a renewal will run#

Superseded by Boolean and currency field renames and integer bounds.

Breaking: next_billing_at on a subscription is now present only while a trialing or active subscription has a billing date and isn't set to cancel at the end of its period. A canceled, paused, past_due, or incomplete subscription, a scheduled start, and one set to cancel have none, even when they had a date before. Read scheduled_resume_at for a pause with a length, next_retry_at for a payment retry, starts_at for a scheduled start, and current_period_end_at for when a canceling subscription ends. The same applies to subscriptions in webhook payloads, on /v1/me, and in expansions.

Breaking: next_billing_after and next_billing_before match only subscriptions that have a next_billing_at. With sort_by=next_billing_at, subscriptions without one sort last in both directions; ascending used to list them first.

A past_due subscription reports missed_billing_at, the billing date whose payment failed. When it's before current_period_end_at, the first paid period was never paid, and canceling ends the subscription right away whatever cancel_immediately says.

billing_interval, billing_interval_count, recurring_amount_money, and line_items are always present on a subscription, including the response to POST /v1/subscriptions. line_items is [] when there are none.

Buyers reading with a customer session now receive starts_at and awaiting_billing_schedule.

Subscriptions has the details.

  • Breaking change
  • API
  • Subscriptions

Stop selling a subscription plan without ending its subscriptions#

A subscription plan's status is now active, inactive, or archived. Send status on POST /v1/subscription-plans and PATCH /v1/subscription-plans/{subscription_plan_id} to set active (the default on create) or inactive. Only DELETE archives a plan; sending archived returns 400 INVALID_REQUEST with detail INVALID_VALUE.

An inactive plan takes no new subscribers. Creating or previewing a subscription on it, creating a checkout session or payment link for it, and paying an order that signs a buyer up for it return 409 PLAN_NOT_ACTIVE with current_status: "inactive". Its current subscriptions keep renewing, the plan stays editable, and setting it back to active takes signups again. To change a plan's price, create a new plan and set the old one to inactive.

Setting a plan to inactive is refused with 409 RESOURCE_IN_USE while an active payment link sells it. Subscriptions and open checkout sessions don't block it; a buyer already in checkout for the plan gets 409 PLAN_NOT_ACTIVE when they pay. GET /v1/subscription-plans returns active and inactive plans by default, and status=inactive lists only inactive ones.

Breaking: DELETE /v1/subscription-plans/{subscription_plan_id} archives an active or inactive plan. When subscriptions, active payment links, or open checkout sessions remain, it returns 409 RESOURCE_IN_USE instead of PLAN_HAS_ACTIVE_SUBSCRIPTIONS, PLAN_HAS_ACTIVE_PAYMENT_LINKS, or PLAN_HAS_OPEN_CHECKOUT_SESSIONS. details[0].blocking_resources lists up to 25 subscription, payment_link, and checkout_session references, and blocking_resource_count gives the total.

Breaking: status on subscription plans and on expanded plan summaries can be inactive. Handle the new value wherever you branch on plan status.

A product, variant, or bundle on an inactive plan can't be deleted or archived, the same as one on an active plan, because the plan can be activated again.

Stop selling a plan has the details.

  • API

New in the API: week of October 12, 2026#

312 additions across Inventory, Gift cards, and 42 more areas. These are additions, so nothing you already use needs to change.

Related: Payments made with your API key take Apple Pay and Google Pay, Create API keys from a scope preset, Products and bundles reference categories by handle only, Product and promotion create return their variants and codes, Customers without an email, create-or-return by email, and null for empty fields, Stale versions return VERSION_CONFLICT, and status refusals return ACTION_NOT_ALLOWED, Inventory adjustments say what happened, One PATCH for Locations, with a flat allocation status, Mode and sandbox_id name the environment everywhere, Promotions and codes report availability apart from status, A Return lists its children by ID and expands them in one read, Subscriptions show next_billing_at only while a renewal will run, Stop selling a subscription plan without ending its subscriptions, Pay an order with your API key while its checkout session is open, Lists include archived records only when status names them, Checkout sessions take tax from the order, Count observations keep the conditions you didn't count, Not-found, authentication, and server errors use generic codes, One shape for references that can point at more than one resource type, Routes that move money or stock require an Idempotency-Key, and other writes never do, Inventory reservations need only a key, an item, and a quantity, Create and issue an invoice in one call, and sell tracked stock with quick pay, List time ranges exclude their _before bound, and sort values name response fields, Declined payments return 2xx with last_payment_error, and 402 is gone, List a payout's balance transactions with payout_id, Balance transactions add up to your balance, and payouts in progress show only in held_money, Flint chooses the balance source for a payout, Every report covers up to 366 days, and the report list filters by type and status, Variants select options by name, Webhooks and delivery rate callbacks are signed only with Standard Webhooks, Checkout sessions stay open when you edit the order, Validation errors use INVALID_REQUEST, and enum values match exactly, Consistent names for versions, references, and checkout settings, Clear fields with null; empty strings are rejected, Webhook events carry their resource in data.object, and event names follow one rule, Buyer lists accept only buyer-visible filters, and rejected customer sessions return 401, Catalog updates handle null consistently and reject changes to archived products, Duplicate customer emails name the existing customer, Customer session secrets end with their refresh token, Archived devices report archived and release their fingerprint, Dispute field names, review refunds, and risk previews, Effective settings include promotion defaults, Fulfillment command results, external references, and delivery configuration lists, Gift card command responses, funding limit errors, and customer null handling, Inventory errors name the field, and every inventory resource reads by ID, Location errors name the field, and country codes must be uppercase, Manual discount scope must match discount_class, Analytics stays in one currency, and payouts and balances match their webhooks, Order field renames, revision checks, and null handling, Payment intent, payment method, and refund request fixes, Payment links keep opening after you turn promotions off, Promotion updates change only the subfields you send, Promotion removal warnings reflect the returned order, Returns and credit note errors, fences, and a preview rename, Archived promotions use the disabled decline reason, Catalog, checkout, subscription, and account state conflicts return 409, A charge's tax category decides its automatic tax, Merchant credentials can apply code-gated promotions by ID, Discount errors name the field you sent, Exhausted promotions are removed before payment, Idempotency replays include metadata and keys come from callers, Invoice installments carry the tip first, Invoice lists use cursor page tokens, Order create resolves requested promotions together, Orders report the requested tip only in tips, Order totals failures return 500 ORDER_TOTALS_UNAVAILABLE, Order, delivery, and promotion state conflicts return 409, Payments in progress return 409 PAYMENT_IN_PROGRESS, Creating a payment intent returns it flat in data, Payment intent tips are validated, payment_intent events carry the full payment intent, Payment, refund, and invoice state conflicts return 409, Promotions without eligibility rules omit `eligibility_rules`, Promotion write and discount removal errors name the field you sent, Promotion declines use 409 for promotion state, and displaced promotions are reported, New promotion decline reason `superseded_by_higher_priority`, Promotion rules reject unknown enum values, Percent promotions apply to the remaining balance, Promotion updates keep omitted combines_with classes, Refund amounts default to the sum of named targets, Repeated query parameters are validated, Request body field validation, Refunds, wallet cards, and gift card refund allocations use consistent response fields, Subscription payments completed after cancellation are refunded, Timestamps carry whole seconds, Partly paid orders keep their unpaid tip payable, Delivery rate callbacks receive the quote's expiry, Delivery rate callback URL errors use INVALID_URL and INVALID_URL_HOST, Checkout sessions reject an empty delivery method list, Delivery errors name the field to fix, Delivery methods no longer return offer_windows, Dimensions use millimeter, centimeter, or inch, Location sets accept stores without inventory allocation, Pickup search distances use meter, kilometer, and mile, State conditions recognize military addresses and can't be passed with an unknown state

Inventory
24 additions
Gift cards
8 additions
Checkout sessions
11 additions
Delivery quotes
1 addition
Orders
30 additions
  • Query parameter
    expected_versionon DELETE /v1/orders/{order_id}/charges/{order_charge_id}

    Order version from the last order read.

  • Query parameter
    expected_versionon DELETE /v1/orders/{order_id}/gift-cards/{gift_card_id}

    Order version from the last order read.

  • Query parameter
    expected_versionon DELETE /v1/orders/{order_id}/line-items/{order_line_item_id}

    Order version from the last order read.

  • Query parameter
    payment_link_idon GET /v1/orders

    Filter by the payment link whose checkout created the order.

  • Query parameter
    activity_typeon GET /v1/orders/{order_id}/activities

    Filter by activity type.

  • Request field
    expected_versionon PATCH /v1/orders/{order_id}

    Order version from the last order read.

  • Request field
    expected_versionon PATCH /v1/orders/{order_id}/charges/{order_charge_id}

    Optional order version from the last order read.

  • Request field
    expected_versionon POST /v1/orders/{order_id}/close

    Optional order version from the last order read.

Subscriptions
27 additions
Returns
23 additions
  • Query parameter
    expected_versionon DELETE /v1/returns/{return_id}/line-items/{return_line_item_id}

    Optional version of the parent Return.

  • Request field
    expected_versionon PATCH /v1/returns/{return_id}

    Optional version of the Return.

  • Request field
    automatic_resolution_typeon POST /v1/returns/{return_id}/decide

    Optional refund, store_credit, or no_monetary_action that Flint creates and confirms automatically.

  • Request field
    automatic_resolution_typeon POST /v1/returns/{return_id}/process

    Optional refund, store_credit, or no_monetary_action that Flint creates and confirms automatically.

  • Field

    IDs of every disposition recorded for this Return, oldest first, including failed and canceled dispositions.

  • Field

    Present only when `expand` includes `return_dispositions`.

  • Field

    IDs of every inspection recorded for this Return, oldest first, including superseded inspections.

  • Field

    Present only when `expand` includes `return_inspections`.

Customer account
10 additions
Payment links
9 additions
  • Query parameter
    has_subscription_planon GET /v1/payment-links

    Filter by whether the payment link references a subscription plan.

  • Query parameter
    updated_afteron GET /v1/payment-links

    Inclusive lower bound on updated_at.

  • Query parameter
    updated_beforeon GET /v1/payment-links

    Exclusive upper bound on updated_at.

  • Request field
    sales_end_aton PATCH /v1/payment-links/{payment_link_id}

    RFC3339 timestamp after which the link stops starting checkouts and resolve fails with `ACTION_NOT_ALLOWED` and reason `not_offered`.

  • Request field
    sales_end_aton POST /v1/payment-links

    RFC3339 timestamp after which the link stops starting checkouts and resolve fails with `ACTION_NOT_ALLOWED` and reason `not_offered`.

  • Field

    RFC3339 timestamp after which the link stops starting checkouts and resolve fails with `ACTION_NOT_ALLOWED` and reason `not_offered`.

  • Field

    RFC3339 timestamp after which the link stops starting checkouts and resolve fails with `ACTION_NOT_ALLOWED` and reason `not_offered`.

  • Event

    A payment link was created.

Products
9 additions
  • Request field
    category_handleson PATCH /v1/products/{product_id}

    Relationship set of category handles that must already exist.

  • Request field
    external_reference_idon PATCH /v1/products/{product_id}/variants/{variant_id}

    Caller-owned identifier for this resource in an external system.

  • Request field
    selected_optionson PATCH /v1/products/{product_id}/variants/{variant_id}

    Option name and value selections for this variant.

  • Request field
    category_handleson POST /v1/products

    Relationship set of category handles that must already exist.

  • Request field
    option_nameon POST /v1/products

    Name of one of the product's options.

  • Request field
    selected_optionson POST /v1/products

    Option name and value selections for this variant.

  • Request field
    valueon POST /v1/products

    Value of the named option.

  • Field

    The product's complete non-archived variants, ordered by `position` and then `variant_id`.

Webhooks
9 additions
  • Field

    Last event sent before a backpressure disconnect.

  • Values

    credit_note_allocation.createdcredit_note_allocation.reversedcustomer_deletion_request.completedcustomer_deletion_request.createdcustomer_deletion_request.rejectedfulfillment_event.created

  • Values

    credit_note_allocation.createdcredit_note_allocation.reversedcustomer_deletion_request.completedcustomer_deletion_request.createdcustomer_deletion_request.rejectedenvironment_grant.created

  • Values

    credit_notecredit_note_allocationcustom_domaincustomer_deletion_requestdelivery_location_setdelivery_method

  • Values

    credit_note_allocation.createdcredit_note_allocation.reversedcustomer_deletion_request.completedcustomer_deletion_request.createdcustomer_deletion_request.rejectedfulfillment_event.created

  • Values

    credit_note_allocation.createdcredit_note_allocation.reversedcustomer_deletion_request.completedcustomer_deletion_request.createdcustomer_deletion_request.rejectedenvironment_grant.created

  • Values

    credit_note_allocation.createdcredit_note_allocation.reversedcustomer_deletion_request.completedcustomer_deletion_request.createdcustomer_deletion_request.rejectedenvironment_grant.created

  • Value
Customers
7 additions
  • Request field
    is_merchant_verifiedon PATCH /v1/customers/{customer_id}

    Flag you set on the customer, for example after checking ID in store.

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

    Free-form label you assign, such as wholesale, so promotion and delivery rules can match groups of customers.

  • Request field
    is_merchant_verifiedon POST /v1/customers

    Flag you set on the customer, for example after checking ID in store.

  • Request field
    segmenton POST /v1/customers

    Free-form label you assign, such as wholesale, so promotion and delivery rules can match groups of customers.

  • Field

    Flag you set on the customer, for example after checking ID in store.

  • Field

    Free-form label you assign, such as wholesale, so promotion and delivery rules can match groups of customers.

  • Values
Invoices
6 additions
  • Query parameter
    has_outstanding_balanceon GET /v1/invoices

    Filter by whether settlement_amounts.outstanding_money is greater than zero.

  • Query parameter
    activity_typeon GET /v1/invoices/{invoice_id}/activities

    Filter by activity_type.

  • Request field
    inventory_routing_sourceon POST /v1/invoices

    Where this invoice backing order's tracked demand is routed: a fixed Location, an allocation policy, or an immutable policy revision.

  • Request field
    issueon POST /v1/invoices

    Issue the invoice immediately after creating it.

  • Field

    Version of the invoice payment term captured in this snapshot.

  • Value
Fulfillment records
5 additions
Locations
5 additions
  • Request field
    addresson PATCH /v1/locations/{location_id}

    Complete replacement postal address, validated as on create.

  • Request field
    coordinateon PATCH /v1/locations/{location_id}

    Complete replacement coordinate.

  • Request field
    coordinate_sourceon PATCH /v1/locations/{location_id}

    Source of the coordinate sent in the same request.

  • Request field
    timezoneon PATCH /v1/locations/{location_id}

    IANA timezone for local schedules, validated as on create.

  • Field

    Read-only version that advances only on geography changes and is pinned by tax and delivery dependencies.

Promotions
5 additions
Settings
5 additions
Analytics
4 additions
Money movement
4 additions
  • Query parameter
    expandon GET /v1/balance-transactions

    Include related objects in the response.

  • Query parameter
    order_idon GET /v1/balance-transactions

    Exact-match filter on `order_id`.

  • Query parameter
    payout_idon GET /v1/balance-transactions

    Lists the balance transactions this payout carried, newest first.

  • Query parameter
    expandon GET /v1/payouts

    Include related objects in the response.

Partner app installs
4 additions
Refunds
4 additions
Subscription plans
4 additions
Credit notes
3 additions
  • Request field
    line_itemson PATCH /v1/credit-notes/{credit_note_id}

    Full replacement of the draft's owned line collection; requires expected_version.

  • Request field
    line_itemson POST /v1/credit-notes

    Initial draft corrections.

  • Field

    Itemized corrections against frozen invoice lines.

Disputes
3 additions
Return inspections
3 additions
API keys
2 additions
API request logs
2 additions
Bundles
2 additions
  • Request field
    category_handleson PATCH /v1/bundles/{bundle_id}

    Relationship set of category handles that must already exist.

  • Request field
    category_handleson POST /v1/bundles

    Relationship set of category handles that must already exist.

Delivery configuration
2 additions
Delivery revocations
2 additions
Devices
2 additions
Partner OAuth
2 additions
  • Query parameter
    response_typeon GET /v1/oauth/authorize/preview

    OAuth response type.

  • Query parameter
    stateon GET /v1/oauth/authorize/preview

    Opaque state value returned to the partner callback.

Payments
2 additions
Reports
2 additions
  • Query parameter
    report_typeon GET /v1/reports

    Return reports with any of these report types.

  • Query parameter
    statuson GET /v1/reports

    Return reports in any of these statuses.

Delivery previews
1 addition
Demo sessions
1 addition
Merchants
1 addition
  • Event

    A merchant's published payment, payout, or onboarding readiness changed in live or sandbox mode, for example after an account or verification update, a payment or payout capability change, or a processing pause or resumption.

Payment method domains
1 addition
Return dispositions
1 addition
Return resolutions
1 addition
Risk controls
1 addition
  • Field

    Whether Flint manages the list or the merchant created it.

Sandboxes
1 addition
  • Values

    accounts.api_keys.readaccounts.api_keys.writeaccounts.devices.readaccounts.devices.writeanalytics.readcheckouts.checkout_sessions.read

Webhook events
54 additions
  • Field
    Balance.observed_at

    When Flint observed these amounts, as an RFC 3339 UTC instant at second precision.

  • Field
    DeliveryEligibilityExpression.customer_merchant_verified

    Matches the is_merchant_verified flag you set on the customer against value.

  • Field
    DeliveryEligibilityExpression.customer_segment

    Matches the free-form segment you assign to the customer against values.

  • Field
    ExpandedPayoutSummary.arrival_date

    Expected settlement date of the transfer, in YYYY-MM-DD format using the UTC date of the expected arrival.

  • Field
    GiftCardFundingSource.external_reference_id

    Your reference for the payment or import record that funded this value, such as a POS sale ID.

  • Field
    GiftCardPurchaseRefundValueAllocation.amount_money

    The value allocated to the card.

  • Field
    GiftCardRedemption.order_payment_attempt_id

    The order payment attempt the redemption belongs to.

  • Field
    GiftCardRedemption.sale_reference

    Your reference for the sale the redemption pays for.

Errors
9 additions
  • API
  • Checkout
  • Orders
  • Payments
  • Delivery

Pay an order with your API key while its checkout session is open#

Paying an order with your API key while its checkout session was open returned 409 ORDER_COLLECTION_IN_PROGRESS, and for an order with delivery, the selection made on the session was out of reach. Now the payment runs, and it uses the session's current delivery selection, so the delivery charge on the order is the one charged. You can quote, select, and pay a phone or server-side order with your API key alone. See Take the order yourself.

While the session is open, the payment must send expected_outstanding_money, the order's outstanding_money you read. Without it the payment returns 400 FIELD_REQUIRED, and a balance that changed returns 409 ORDER_CHANGED_REFRESH_REQUIRED with the current balance in details[0].current_money. Paying an order with no open session keeps the field optional.

Only one payment for the order runs at a time. While the buyer is paying, your request returns 409 ORDER_PAYMENT_ATTEMPT_ACTIVE. While yours runs, a payment or an order change with the checkout credential returns 409 PAYMENT_IN_PROGRESS, and reading the session returns the new problems[] code payment_in_progress, which names neither your payment nor its amount. The hosted page tells the buyer a payment for the order is already being processed.

A payment with your API key that collects money, the whole balance or part of it, commits the delivery selection and ends the session as invalidated with the new terminal_reason value order_paid_elsewhere. Flint sends checkout_session.invalidated, the session's checkout credential can still read it, and the hosted page tells the buyer the order was paid another way. A declined payment leaves the session open with the buyer's selection in place. See Paying the order with your API key.

  • Breaking change
  • API
  • Locations
  • Risk
  • Delivery
  • Payouts

Lists include archived records only when status names them#

Every list follows one rule now: it leaves out records whose status is archived or deleted unless your status filter names that status. Leave status out and you get every other status. Pagination states the rule.

Breaking: include_archived is removed from these lists, and sending it returns UNSUPPORTED_QUERY_PARAM. Name the statuses you want in status instead, such as status=active,inactive,archived.

  • GET /v1/delivery-profiles, /v1/delivery-zones, /v1/delivery-location-sets, /v1/delivery-methods, and /v1/delivery-rate-callbacks
  • GET /v1/risk-rules and /v1/risk-lists
  • GET /v1/payout-settings/destinations

Breaking: these lists used to include archived records when you left out status. They now leave them out:

  • GET /v1/subscription-offers
  • GET /v1/return-policies and /v1/return-reasons
  • GET /v1/invoice-payment-terms
  • GET /v1/developer/sandboxes, which also drops the all status value. Send status=active,archived to list every sandbox.

Breaking: GET /v1/locations no longer lists only active locations by default. Leave out status and you get active and inactive locations. Archived ones appear only with status=archived.

The status filter on the delivery lists, payout destinations, subscription offers, invoice payment terms, and sandboxes accepts several values, as repeated keys or one comma-separated value. Risk rules and risk lists now publish a read-only status, active or archived, and their lists take a status filter that works the same way.

  • Breaking change
  • API
  • Checkout

Checkout sessions take tax from the order#

An order has one tax setting, its own tax. Hosted checkout now asks the buyer for a tax location whenever the order's automatic tax needs one and the order doesn't ship, whatever created the session. Before this change, hosted checkout asked only when the session was created with tax.enabled: true. An order with automatic tax whose session left tax out never asked, so paying failed with ORDER_TAX_NOT_READY. This also affected sessions created from quick_pay_item or subscription_plan_id without tax, when the merchant's tax.default_enabled setting turned tax on for the new order. Flint now also uses a prefilled address to set the tax location for those orders, as it already did when tax.enabled was sent.

Breaking: POST /v1/checkout-sessions accepts tax only with quick_pay_item or subscription_plan_id, where it sets the tax of the order Flint creates. With order_id, sending tax returns 400 INVALID_REQUEST with detail NOT_ALLOWED and param: tax. Set tax on the order with PATCH /v1/orders/{order_id} instead.

Breaking: checkout sessions no longer return tax, in responses or in checkout_session.* webhooks. Read tax on the session's order. Payment links keep tax: a link's tax still sets the tax of each order it creates.

Breaking: an order's tax no longer returns taxability_reason or failure_reason. Both repeated tax.status, which is unchanged: not_required, requires_location, calculated, exempt, or incomplete. A calculated order with nothing taxable has pricing_amounts.tax_money of zero. This applies to every order response, including /v1/me orders and order webhooks. Each row in tax.tax_breakdowns keeps its own taxability_reason.

  • API

Count observations keep the conditions you didn't count#

PATCH /v1/inventory-counts/{inventory_count_id} now requires only inventory_item_id and counted_on_hand_quantity in each observation. counted_quality_control_quantity, counted_damaged_quantity, and counted_quarantined_quantity are optional.

When you leave a condition quantity out, Flint saves the line's expected_<condition>_quantity for it, and the saved line reports that value as counted. Applying the count then leaves that condition unchanged. Send 0 only when you counted none of that condition. Before this change, a counting screen that sent 0 for every empty box zeroed damaged, quality control, and quarantined stock nobody had counted, and those units became available to sell.

If counted_on_hand_quantity is below the sum of the three condition quantities, including the ones Flint filled in, the PATCH returns 400 INVALID_REQUEST with param set to observations[i].counted_on_hand_quantity. That refusal used to be INVENTORY_CONDITION_INVALID on the condition field; no route returns that code any more.

The Dashboard's count entry form now sends only the boxes you fill in, and each empty condition box shows the quantity it keeps.

  • Breaking change
  • API
  • Errors

Not-found, authentication, and server errors use generic codes#

Superseded by Context headers must match fixed credentials.

Breaking: the public API now returns a small set of generic error codes for missing resources, credential failures, and server failures. Branch on code, find the input in param, and read the facts in details[0]. Error handling and Authentication describe each code.

Not found#

An unknown ID in the path, the query, or the body returns 404 RESOURCE_NOT_FOUND. param names where the ID came from, such as order_id, promotion_id, or to_delivery_method_id. details[0].resource_type is the missing resource's type, such as promotion, or delivery_method for to_delivery_method_id, and details[0].resource_id is the ID you sent. It replaces every per-resource code, such as ORDER_NOT_FOUND, GIFT_CARD_NOT_FOUND, PROMOTION_NOT_FOUND, DISCOUNT_NOT_FOUND, SUBSCRIPTION_OFFER_NOT_FOUND, PAYMENT_LINK_NOT_FOUND, CHECKOUT_SESSION_NOT_FOUND, INVOICE_NOT_FOUND, PAYMENT_METHOD_NOT_FOUND, DISPUTE_NOT_FOUND, IMAGE_ASSET_NOT_FOUND, REPORT_NOT_FOUND, the INVENTORY_*_NOT_FOUND codes, DELIVERY_RESOURCE_NOT_FOUND, and CUSTOMER_ACCOUNT_RESOURCE_NOT_FOUND. A missing Flint Wallet, formerly FLINT_WALLET_NOT_FOUND, has details[0].resource_type flint_wallet and no param.

These lookups returned another status and now return 404:

Former codeFormer status
CREDIT_NOTE_INVOICE_LINE_NOT_FOUND, MERCHANT_ENVIRONMENT_NOT_FOUND, ORDER_CHARGE_NOT_FOUND, ORDER_LINE_ITEM_NOT_FOUND, REFUND_ADJUSTMENT_NOT_FOUND, RISK_LIST_ALIAS_NOT_FOUND, SANDBOX_NOT_FOUND400
PAYOUT_DESTINATION_NOT_FOUND, PAYOUT_NOT_FOUND409
FULFILLMENT_METHOD_UNAVAILABLE for a delivery method that doesn't exist409

FULFILLMENT_METHOD_UNAVAILABLE stays 409 for a method that isn't active, or for a zone, location set, or rate callback that is missing or not active.

Authentication and authorization#

A credential failure at 401 uses one of two codes:

  • AUTHENTICATION_REQUIRED when no credential was sent. It replaces API_KEY_REQUIRED, AUTH_REQUIRED, CHECKOUT_SESSION_REQUIRED, CHECKOUT_SESSION_AUTH_REQUIRED, CHECKOUT_CREDENTIAL_REQUIRED, ONBOARDING_SESSION_REQUIRED, CUSTOMER_SESSION_REQUIRED, and BUYER_INVOICE_CREDENTIAL_REQUIRED.
  • INVALID_CREDENTIAL when a credential was sent but can't be used. details[0].reason says why, and remediation.next_steps says what to do for that reason:
details[0].reasonFormer codes
malformedINVALID_AUTHORIZATION_HEADER, INVALID_API_KEY, CHECKOUT_SESSION_SECRET_REQUIRED
unknownAPI_KEY_NOT_FOUND, INVALID_OAUTH_TOKEN, INVALID_PARTNER_TOKEN, INVALID_BEARER_TOKEN, INVALID_CHECKOUT_SESSION, INVALID_ONBOARDING_SESSION, INVALID_CUSTOMER_SESSION, BUYER_INVOICE_CREDENTIAL_INVALID, AUTHENTICATION_FAILED
revokedAPI_KEY_REVOKED, and API_KEY_SANDBOX_UNAVAILABLE for a key whose sandbox was archived or is inactive
expiredAPI_KEY_EXPIRED, CUSTOMER_SESSION_EXPIRED
mode_mismatchAPI_KEY_MODE_MISMATCH, SANDBOX_SELECTION_REQUIRED for a test key not bound to a sandbox, and API_KEY_SCOPE_UNSUPPORTED
wrong_credential_typeEXTERNAL_API_KEY_REQUIRED, CHECKOUT_CREDENTIAL_REQUIRED for merchant authentication on a checkout-only route, PARTNER_AUTH_UNSUPPORTED, ONBOARDING_PARTNER_AUTH_UNSUPPORTED

The reason set can grow, so treat an unfamiliar reason like unknown. EXTERNAL_API_KEY_REQUIRED and the merchant-authentication case of CHECKOUT_CREDENTIAL_REQUIRED returned 403 and now return 401.

A 403 is INSUFFICIENT_SCOPE, unchanged, or FORBIDDEN with details[0].reason set to the former code in lower case, such as checkout_recovery_restricted. FORBIDDEN replaces MERCHANT_ACCESS_REQUIRED, SANDBOX_MANAGEMENT_REQUIRES_LIVE_KEY, PARTNER_APP_MANAGEMENT_REQUIRES_LIVE_KEY, DEMO_SESSION_ROUTE_NOT_ALLOWED, CHECKOUT_LAUNCH_TOKEN_RESTRICTED, CHECKOUT_RECOVERY_RESTRICTED, CHECKOUT_RECOVERY_ATTEMPT_MISMATCH, CHECKOUT_SESSION_PAYMENT_REQUIRED, CHECKOUT_SESSION_ORDER_MISMATCH, OAUTH_CONTEXT_MISMATCH, SANDBOX_NOT_ACCESSIBLE, SANDBOX_SELECTION_FORBIDDEN, and ENVIRONMENT_SELECTION_FORBIDDEN. AUTHORIZATION_FAILED becomes FORBIDDEN with reason not_permitted. Paying an order with your API key and save_payment_method: true stays 403, now FORBIDDEN with reason not_checkout_session and param save_payment_method, because only the buyer's checkout session can save a card.

These keep their codes: 400 SANDBOX_SELECTION_REQUIRED for an onboarding request when the merchant has no default sandbox, 400 ME_CUSTOMER_ID_FORBIDDEN, the 400 cases of CHECKOUT_SESSION_REQUIRED and INVALID_CUSTOMER_SESSION, the refresh-token codes CUSTOMER_SESSION_REFRESH_EXPIRED and CUSTOMER_SESSION_REFRESH_REUSED, the verification codes INVALID_VERIFICATION, VERIFICATION_ALREADY_USED, and VERIFICATION_ATTEMPTS_EXCEEDED, 401 CHECKOUT_SESSION_AUTH_UNAVAILABLE, and refusals that depend on the request rather than the credential, such as CHECKOUT_SESSION_UPDATE_FIELD_NOT_ALLOWED and REQUEST_BLOCKED.

Server errors#

  • 500 INTERNAL_ERROR replaces the 500 codes that asked you to retry the same request, such as IDEMPOTENCY_LOAD_FAILED, SANDBOX_LIST_FAILED, CHECKOUT_SESSION_LOOKUP_FAILED, AUTH_CONTEXT_MISSING, ENVIRONMENT_LOOKUP_FAILED, IDENTITY_RESOLUTION_FAILED, and PAYMENT_METHOD_DOMAINS_UNAVAILABLE.
  • 502 EXTERNAL_SERVICE_ERROR replaces ORDER_TAX_CALCULATION_FAILED and PAYMENT_PROCESSOR_ERROR.
  • 503 SERVICE_UNAVAILABLE replaces the 503 codes, such as DELIVERY_SERVICE_UNAVAILABLE, DELIVERY_PREVIEW_UNAVAILABLE, CUSTOMER_VERIFICATION_UNAVAILABLE, GIFT_CARDS_UNAVAILABLE, RISK_EVALUATION_UNAVAILABLE, PAYOUT_ENTRIES_UNAVAILABLE, REPORTING_UNAVAILABLE, PAYMENT_METHOD_DOMAIN_REGISTRATION_FAILED, PROCESSING_FEE_PRICING_UNAVAILABLE, IDENTITY_UNAVAILABLE, and OAUTH_UNAVAILABLE. Retry-After is still sent when Flint knows the delay.
  • 504 REQUEST_TIMEOUT replaces the other 504 codes.

These server codes stay, because their recovery differs from a plain retry: AUTOMATIC_TAX_UNAVAILABLE, ORDER_TOTALS_UNAVAILABLE, PAYMENT_PROCESSING_UNAVAILABLE, PROFILE_UPDATE_STATUS_UNKNOWN, IDEMPOTENCY_RECOVERY_REQUIRED, DANGLING_EXPANSION_REFERENCE, FLAT_TAX_REFUND_STATE_INVALID, FULFILLMENT_EVENT_SUBJECT_INVALID, SENSITIVE_IDEMPOTENCY_RESULT_INVALID, and the image ingestion codes IMAGE_PROCESSING_FAILED, IMAGE_PROCESSING_CAPACITY_EXCEEDED, IMAGE_PROCESSING_TIMEOUT, IMAGE_SOURCE_TIMEOUT, and IMAGE_SOURCE_UNAVAILABLE. An image that fails processing in a way a retry can't fix returns 400 IMAGE_FORMAT_UNSUPPORTED instead of IMAGE_PROCESSING_FAILED. *_UNAVAILABLE codes returned with a 4xx status, such as PAYMENT_OPTION_UNAVAILABLE and INVENTORY_UNAVAILABLE, keep their names.

Validation#

Four more validation codes now return 400 INVALID_REQUEST, with the same param:

Former codedetails[0].code
NULL_NOT_ALLOWEDINVALID_VALUE
INVALID_FIELD_TYPEINVALID_VALUE
UNKNOWN_FIELDUNKNOWN_FIELD
INVALID_EXPAND, EXPANSION_LIMIT_EXCEEDEDINVALID_VALUE, with param expand

Per-operation error codes#

Each operation's x-flint-error-codes is now generated from the route's authentication schemes, body, idempotency, pagination, expand support, path parameters, and handler. It lists exactly the codes the operation can return, top-level code and details[].code alike, and only public codes. A route that takes no body no longer lists body-size or content-type errors, and a route without expand no longer lists expand errors.

  • Breaking change
  • API
  • Money-movement
  • Gift-cards
  • Inventory
  • Returns
  • Checkout

One shape for references that can point at more than one resource type#

Breaking: the fields and filters below change shape with no alias. An old query parameter returns UNSUPPORTED_QUERY_PARAM.

A field that can point at more than one kind of resource is now always an object with resource_type and resource_id, and the field's name says what it is (related_resource, source, linked_resource). resource_type is the resource's ID field name without _id, such as refund or gift_card_load. OpenAPI publishes every value as one extensible ResourceType enum, which errors, request logs, resource timelines, webhook events, and these references share. Accept values you don't recognize.

WhereOldNew
Balance transactionrelated_resource: {"type": "refund", "refund_id": "ref_..."}related_resource: {"resource_type": "refund", "resource_id": "ref_..."}
GET /v1/balance-transactionsrelated_object_type, related_object_idrelated_resource_type, related_resource_id. reserve and adjustment are no longer values; filter by type instead. A missing type or a mismatched ID returns INVALID_REQUEST with details[0].code REQUIRED or INVALID_VALUE
Inventory movementsource_reference: {"source_reference_type", "source_reference_id"}source_reference: {"resource_type", "resource_id"}, where resource_type is fulfillment, inventory_reservation_line, inventory_count, inventory_transfer, or product_variant. Movements from a return receipt carry return_id and no source_reference. The source_reference_type and source_reference_id filters keep their names and take those values
Gift card transactionsource_type, source_idsource: {"resource_type", "resource_id"}, or null on adjustments and cash-outs
GET /v1/gift-card-transactionssource_type values such as refund and gift_card_purchase_refundsource_type takes ResourceType values: gift_card_load, gift_card_redemption, gift_card_funding_disposition, refund_allocation, or purchase_refund_allocation. Select adjustments and cash-outs with the new multi-value transaction_type filter, such as transaction_type=adjustment,cash_out
Return resolution execution_blockers[]linked_resource_type, linked_resource_idlinked_resource: {"resource_type", "resource_id"}, returned to merchant credentials only
Checkout session delivery_pinned_dependencies[]delivery_dependency_type, delivery_dependency_iddependency: {"resource_type", "resource_id"}. A location geography pin is location, with its version in location_geography_version; a location set revision is delivery_location_set, with the revision in revision_id. The internal evaluation schema pin is no longer listed
Error blocking_resources[]resource_type: "other"Every blocker is a ResourceType value. A delivery method or profile held by your checkout or catalog defaults is reported as your merchant; change those defaults with PATCH /v1/settings

On a gift card transaction, a refund paid back to the card was source_type: "refund" with the refund's tender allocation ID in source_id. It is now refund_allocation, matching refund_allocation_id in the refund's tender_allocations. A refund of the card's purchase is purchase_refund_allocation, matching purchase_refund_allocation_id in the load's purchase_refunds. transaction_type still says what each posting did.

  • Breaking change
  • API
  • Idempotency

Routes that move money or stock require an Idempotency-Key, and other writes never do#

Superseded by Gift card lifecycle verbs and shared status words, Create order payments through the payment intents collection.

Every route has one idempotency class, set by the route and never by the request body: required for routes that create a new money or stock movement each time they run, optional for every other write, and none for reads, previews, and lookups. Each endpoint's API reference entry marks its class, and the Idempotency guide lists every required route.

Breaking: these routes now reject a request with no Idempotency-Key:

  • POST /v1/payment-intents and POST /v1/orders/{order_id}/payment-intents
  • POST /v1/payouts
  • POST /v1/invoices/{invoice_id}/manual-payments and POST /v1/invoices/{invoice_id}/manual-payments/reverse
  • POST /v1/subscriptions
  • POST /v1/credit-notes/{credit_note_id}/issue, with or without refund
  • POST /v1/orders/{order_id}/pay, for every action
  • POST /v1/refunds, for every refund

Breaking: a missing key on a required route returns 400 INVALID_REQUEST with details[0] { "code": "REQUIRED", "param": "Idempotency-Key" } instead of 400 IDEMPOTENCY_KEY_REQUIRED. Flint rejects it before reading the body, and nothing runs. IDEMPOTENCY_KEY_REQUIRED is removed.

A required route keeps its key for as long as the command's effects exist, so a retry that arrives days later returns the original result instead of charging, paying out, or refunding again. A replay returns a one-time secret, such as a full gift card code or the client_secret in an order payment's pending action, only within 24 hours of the original request.

These routes no longer require a key and accept an optional one: PATCH /v1/gift-cards/{gift_card_id}, gift card transitions and code rotation, gift card notifications and their cancellation, gift card redemption capture and cancel, inventory counts and their updates, apply, and cancel, PATCH /v1/inventory-levels/{inventory_level_id}, inventory reservation commit, consume, and release, inventory transfer transitions, POST /v1/payment-links/{payment_link_id}/resolve, POST /v1/subscription-delivery-migrations, POST /v1/me/flint-wallet/payment-methods/{id}/store-setups, POST /v1/webhook-endpoints/{webhook_endpoint_id}/test-events, and POST /v1/webhook-deliveries/{webhook_delivery_id}/resend. A request without a key runs once and is not replayed.

Flint's SDKs and CLI already send a key on every write. Raw HTTP callers add the header to the routes above.

  • Breaking change
  • API
  • Inventory

Inventory reservations need only a key, an item, and a quantity#

Holding stock from your own cart takes less input, and reservations no longer show values that only Flint's checkout uses.

  • owner.expires_at is optional. It defaults to 15 minutes after the reservation is created, and a value you send must still be within 15 minutes. A retry with the same Idempotency-Key and body returns the original reservation and deadline.
  • demands[].demand_key is optional and defaults to the demand's inventory_item_id. When the same inventory_item_id appears in more than one demand, send demand_key on each of them; otherwise the request returns 400 INVALID_REQUEST with param set to that demand's demand_key.
  • demands[].splitting_behavior is optional. Without it, the routing source's rule decides.
  • On allocation policies, configuration.maximum_locations_per_assignment is optional. It defaults to 10 for split_when_required, and single_location always uses 1. Sending another value with single_location returns 400 INVALID_REQUEST.

Breaking: POST /v1/inventory-reservations no longer accepts assignments, destination_fingerprint, demands[].order_line_item_id, demands[].bundle_component_id, or owner.type. Sending any of them returns 400 INVALID_REQUEST.

Breaking: a reservation's owner is {"type": "merchant", "key", "expires_at"} for one you created, or {"type": "order", "order_id", "expires_at"} for stock Flint holds for an order or checkout. order_id is absent only on a closed reservation whose order Flint can no longer identify. Earlier responses could show five owner types with Flint's internal key. GET /v1/inventory-reservations now lists every owner by default; owner_type accepts merchant or order, and owner_key matches only reservations you created.

Breaking: reservations drop inventory_action_required.next_actions, inventory_routing_source.location_ids, and lines[].location_geography_version. inventory_action_required.reason is inventory_shortage, hold_expired, payment_pending, or other.

Breaking: when other writes keep changing the same stock while Flint applies an inventory command, Flint retries internally and, if that fails, returns 409 CONCURRENT_MODIFICATION with no param. Retry the same request with the same Idempotency-Key. Before, these requests could return 409 INVENTORY_CHANGED for an expected_version you never sent. INVENTORY_CHANGED now means only that the expected_version you sent is stale. A safety stock change with PATCH /v1/inventory-levels/{inventory_level_id} that sends no expected_version now applies over a concurrent change instead of failing.

  • Breaking change
  • API
  • Invoices
  • Inventory
  • Idempotency

Create and issue an invoice in one call, and sell tracked stock with quick pay#

POST /v1/invoices can now create and issue an invoice in one request, and quick pay invoices can sell catalog items whose stock Flint tracks.

  • Add issue to the create request, for example "issue": {"delivery_mode": "email"}, and the response is 201 with the invoice already open, carrying invoice_number, issued_at, and public_url. issue.delivery_mode takes the issue endpoint's values and defaults to merchant_default. If a check fails before the invoice is created, such as RECIPIENT_EMAIL_REQUIRED, nothing is created. If issuing fails after the invoice is created, it stays a draft, the error's details name it (resource_type invoice and its resource_id), and retrying with the same Idempotency-Key finishes issuing that invoice without sending the email or starting an automatic charge twice. issue together with scheduled_send_at returns 400 INVALID_REQUEST with detail NOT_ALLOWED and param issue.
  • quick_pay.inventory_routing_source takes the same shape as an order's inventory_routing_source. It is required when any line item tracks inventory; without it, the request returns 400 INVALID_REQUEST with detail REQUIRED and param quick_pay.inventory_routing_source. Before, a quick pay invoice couldn't include tracked items at all. Flint holds, commits, and releases the stock as it does for any order.
  • A replay of POST /v1/invoices includes public_url for 24 hours. After that, read the current link with GET /v1/invoices/{invoice_id}.

Breaking: POST /v1/invoices requires the Idempotency-Key header, because a create that issues an automatic-collection invoice charges the customer. A request without it returns 400 INVALID_REQUEST with detail REQUIRED and param Idempotency-Key. The Flint SDKs and CLI send a key for you.

The invoicing guide now also says that collection and payment_due are optional and default to merchant_default, as the API already behaved.

  • Breaking change
  • API
  • Payments
  • Invoices
  • Subscriptions
  • Inventory
  • Payouts

List time ranges exclude their _before bound, and sort values name response fields#

Breaking: on every list, a {field}_before filter excludes the instant it names, and {field}_after includes it. created_after=2026-09-01T00:00:00Z&created_before=2026-10-01T00:00:00Z is exactly September, and the next window starts at 2026-10-01T00:00:00Z without sharing a record. Before, most lists included the _before instant too, and GET /v1/reviews and the returns lists, such as GET /v1/returns, /v1/me/returns, and /v1/return-inspections, excluded the _after instant. A fractional-second bound compares as the instant you send. arrival_after and arrival_before on GET /v1/payouts don't change.

Breaking: two range filters drop _at from their names:

  • GET /v1/invoices and GET /v1/me/invoices: due_at_after and due_at_before are now due_after and due_before.
  • GET /v1/subscriptions and GET /v1/me/subscriptions: next_billing_at_after and next_billing_at_before are now next_billing_after and next_billing_before.

The old names return UNSUPPORTED_QUERY_PARAM.

Breaking: sort_by values are the response field they sort by:

  • GET /v1/payment-intents, /v1/refunds, /v1/me/payments, and /v1/me/refunds: amount is now amount_money.
  • GET /v1/products/{product_id}/variants: unit_price is now unit_price_money.

Breaking: GET /v1/inventory-movements takes sort_direction instead of order. It still defaults to asc, oldest first, and order returns UNSUPPORTED_QUERY_PARAM.

In the OpenAPI document, every sort_by and sort_direction parameter publishes its default, and every range parameter's description reads "Inclusive lower bound on created_at." or "Exclusive upper bound on created_at." for its field. Pagination states the rules once.

  • Breaking change
  • API
  • Payments
  • Orders
  • Invoices

Declined payments return 2xx with last_payment_error, and 402 is gone#

A declined, blocked, or failed payment is now resource state, never an error. Read status and last_payment_error in the response body; Declines and payment attempts has the table.

Breaking: Flint no longer returns 402, and the payment_error error type is removed. These routes return 2xx with the resulting resource when a payment declines or a risk rule blocks it:

  • POST /v1/payment-intents/{payment_intent_id}/confirm returns the payment intent, at requires_payment_method with last_payment_error after a decline or block. POST /v1/payment-intents and POST /v1/payment-intents/{payment_intent_id}/capture no longer list 402 either.
  • POST /v1/subscriptions/{subscription_id}/renew and POST /v1/me/subscriptions/{subscription_id}/renew return 200 with a renewal result, subscription, order, and payment_attempt, instead of the bare subscription. A declined charge has payment_attempt.status: "failed" with last_payment_error.
  • POST /v1/invoices/{invoice_id}/collect returns 200 with the invoice and the failed invoice_payment_attempt.
  • POST /v1/orders/{order_id}/pay already returned 200 for declines; its reference no longer lists 402.

Breaking: the decline error codes are removed, including CARD_DECLINED, INSUFFICIENT_FUNDS, PAYMENT_BLOCKED, PAYMENT_FAILED, PAYMENT_NOT_COMPLETED, SUBSCRIPTION_RENEW_PAYMENT_FAILED, and INVOICE_PAYMENT_FAILED. The reason is last_payment_error.code.

Breaking: every payment attempt reports a failure in last_payment_error, with code, message, failed_at, and remediation, the same shape a payment intent uses:

  • Order payment attempts drop failure_code and failure_message. A failure caused by a payment sets last_payment_error; any other reason an attempt ended, such as inventory_unavailable, is in the new extensible status_reason, with other for a reason Flint can't name. attempt_failed is retired.
  • Invoice payment attempts drop failure_code and failure_message.
  • Subscription payment retries drop failure.

PaymentErrorSummary now always carries all four fields. A payment intent's last_payment_error follows fixed rules: a processor timeout or outage returns a 5xx and never writes it, cancellation and expiry keep the last failure, and a later attempt that succeeds or needs buyer action clears it.

The decline vocabulary adds lost_card, stolen_card, do_not_honor, and fraudulent, which used to read as card_declined. Show the buyer a plain decline for lost_card, stolen_card, and fraudulent, not the reason. Responses to a buyer credential (/v1/me and checkout session credentials) report all four as card_declined with buyer copy; merchant credentials, API keys and the CLI, see the real code.

  • Breaking change
  • API
  • Payouts
  • Balances

List a payout's balance transactions with payout_id#

Superseded by Payout contents stay available in every status, Payout success status and dispute actions.

Reconciling a deposit is one paginated call that returns full balance transactions.

  • GET /v1/balance-transactions?payout_id=po_... lists the balance transactions a paid payout carried, with amount_money, fee_money, net_money, order_id, and related_resource. Their net_money adds up to the payout's amount_money. The payout's own payout row isn't included, and the filter combines with the list's other filters.
  • With payout_id, a payout that doesn't exist returns 404 RESOURCE_NOT_FOUND, a payout that isn't paid returns 409 ACTION_NOT_ALLOWED with details[0].current_status, and a paid payout whose contents are still being prepared returns 503 SERVICE_UNAVAILABLE with Retry-After. If Flint re-prepares a payout's contents while you page through them, the next page_token returns 400 INVALID_PAGE_TOKEN; start again from the first page.
  • GET /v1/balance-transactions filters by order_id and accepts expand=order, resolved for the whole page at once.
  • GET /v1/payouts accepts expand=payout_destination.

Breaking: GET /v1/payouts/{payout_id}/entries and the PayoutEntry schema are removed. Use GET /v1/balance-transactions?payout_id=.... Each entry's balance_transaction_id, type, occurred_at, and net_money are on the balance transaction with the same names. Rows come newest first, like the rest of the list, where entries came oldest first. A payout that isn't paid returns 409 instead of an empty list. The payouts_itemized_v1 report is unchanged.

  • Breaking change
  • API
  • Payouts
  • Webhooks
  • Reports

Balance transactions add up to your balance, and payouts in progress show only in held_money#

Summing net_money over balance transactions in any window now gives the change in your balance, including while a payout you created is still in progress. The funds a pending payout sets aside show in one place: held_money on the balance.

Breaking: balance transactions no longer include payout hold rows.

  • GET /v1/balance-transactions, GET /v1/balance-transactions/{balance_transaction_id}, balance_transaction.created, balance_transaction.updated, and the balance_transactions_itemized_v1 report leave out the rows Flint used to set funds aside for a payout and release them. Fetching one of those rows by ID returns 404 RESOURCE_NOT_FOUND.
  • type no longer takes payout_hold or payout_hold_release, and hold_detail is removed.
  • status is pending or available. reserved, superseded, reversed, and failed are removed from the field and from the status filter, which returns 400 for them.
  • A list without a status filter returns every row. Before, it left out reversed and superseded rows, so a row could drop out of later lists.

Breaking: the balance and the payout drop fields.

  • GET /v1/balances and balance.updated drop held_by_type and unavailable_money. held_money is the amount set aside for payouts you created that haven't been debited from your balance yet, and available_money already leaves it out.
  • Payouts drop held_money on REST responses, expanded payouts, and payout webhooks. Read the total from the balance.

Breaking: GET /v1/balance-transactions page tokens issued before October 17, 2026 return 400 INVALID_PAGE_TOKEN. Start the list again without page_token.

These fixes apply now:

  • Each payout you create has exactly one payout balance transaction. Before, a payout you created could also appear a second time when Flint imported your processor's history, so a window was off by the payout amount.
  • A failed payout's return posts as payout_failure and a canceled payout's as payout_cancellation, each exactly once, so the payout nets to zero. Before, both could post as payout_reversal.
  • Canceling a payout succeeds once your balance has been debited, and a payout_cancellation returns the amount to available_money. Before, the cancel could fail with 404 PAYOUT_NOT_FOUND and leave the payout pending.
  • If your processor rejects a payout you create, the amount goes back to available_money. Before, it could stay in held_money.
  • GET /v1/balances and balance.updated leave active payout holds out of available_money every time. Before, some balance reads and events left them in.
  • Breaking change
  • API
  • Payouts

Flint chooses the balance source for a payout#

A payout draws from one balance source: card funds or bank funds. You no longer have to name the source when your balance holds both.

  • Omit balance_source_type on POST /v1/payouts and Flint chooses card when card funds cover the amount, otherwise bank_account. Before, the request failed whenever both sources had funds, even if one covered the amount.
  • Each source's amount is what available_by_source_type on GET /v1/balances shows, which already leaves out funds held for your other payouts.
  • A retry with the same Idempotency-Key returns the same payout and source.

Breaking: BALANCE_SOURCE_TYPE_REQUIRED is retired. When no single source covers the amount, or the source you named doesn't, POST /v1/payouts returns 409 INSUFFICIENT_AVAILABLE_BALANCE. details[0].available_by_source_type lists what each source has available. To pay out more than one source holds, create one payout per source.

Breaking: balance_source_type on POST /v1/payouts and the GET /v1/payouts filter no longer accept fpx, and return 400 INVALID_REQUEST for it. The *_by_source_type maps on the balance are an open set of keys; US accounts show card and bank_account.

Breaking: payouts always include balance_source_type, on REST responses, expanded payouts, and payout webhooks. An earlier payout created without a source shows card, and GET /v1/payouts?balance_source_type=card includes it.

Breaking: STANDARD_PAYOUT_REQUIRES_MANUAL_SCHEDULE no longer sets param, and details[0].current_interval shows your current interval.

  • API
  • Reports

Every report covers up to 366 days, and the report list filters by type and status#

Every report type now accepts an interval of up to 366 calendar days in the report's timezone. Before, only payments_itemized_v1 and tax_summarized_v1 accepted more than 90 days, so a calendar quarter of 91 or 92 days returned 400 REPORT_INTERVAL_TOO_LARGE for the other types. A calendar quarter or a calendar year, including a leap year, is now one report.

The documented row limit is now 100,000 source or output rows, down from 1,000,000, which matches what a single database read allows. A report also fails when one database read returns more than 64 MiB or runs longer than 20 seconds. Before, those reads were retried for up to about five hours and the report then failed with generation_failed. Now the report fails on the first attempt with failure_reason: limit_exceeded and no file. The 500 MiB, 25-minute, and 10,000-group limits don't change. Split a long interval into smaller reports when a report fails this way.

GET /v1/reports accepts two optional filters:

  • report_type: one or more report types.
  • status: one or more of pending, succeeded, and failed.

Each takes repeated keys or one comma-separated value. Page tokens are bound to the filters they were issued with. Tokens from lists without filters keep working.

A succeeded report keeps status: succeeded after its download expires. Read download.expires_at to know whether the file is still available; after that instant the download route returns 410 REPORT_DOWNLOAD_EXPIRED, and a new POST /v1/reports produces a fresh file.

See Reports.

  • Breaking change
  • API
  • Catalog

Variants select options by name#

Breaking: a variant selects its option values with selected_options, a list of {option_name, value} pairs. It replaces selected_option_values on POST /v1/products (default_variant and variants) and on POST /v1/products/{product_id}/variants. Names match the product's options and values case-insensitively. client_option_key and client_value_key are gone from product options, option values, and selections, and a selection no longer takes option_value_id. Sending any of them returns 400 INVALID_REQUEST with detail UNKNOWN_FIELD.

JSON
"selected_options": [{ "option_name": "Size", "value": "16 oz" }]

On product create, a name that matches no option or value in the same request returns 400 INVALID_REQUEST with detail INVALID_VALUE, and param names the entry, such as variants[1].selected_options[0].value. On the variant routes, a name that matches no stored option or value returns 404 RESOURCE_NOT_FOUND with details[0].resource_type set to product_option or product_option_value.

Breaking: POST /v1/products/{product_id}/variants takes the variant's fields at the top level of the body. Remove the variant wrapper: {"variant": {...}} now returns 400 INVALID_REQUEST with detail UNKNOWN_FIELD. Error param values on this route no longer start with variant..

PATCH /v1/products/{product_id}/variants/{variant_id} accepts selected_options. Send the variant's complete selection to move it to other values without recreating it. The variant_id stays the same, so inventory items, payment links, and bundles keep pointing at the variant, and orders placed before the change keep the values they were placed with. The update uses the same rules as create, and the product's version advances. A combination another variant uses returns 409 VARIANT_OPTION_COMBINATION_ALREADY_EXISTS. A variant in an active bundle can't change its values for active options and returns 409 VARIANT_IN_ACTIVE_BUNDLE; set the bundle to inactive first. Resending the variant's current selected_options is always allowed, including entries for options or values that are no longer active. Leaving out an option that is no longer active keeps the variant's value for it, unless the update selects an active option with the same name, which replaces it.

The same PATCH also accepts external_reference_id. Send a string to set it or null to clear it.

  • Breaking change
  • API
  • Webhooks

Webhooks and delivery rate callbacks are signed only with Standard Webhooks#

Breaking: webhook deliveries and delivery rate callbacks carry one signature: the Standard Webhooks headers webhook-id, webhook-timestamp, and webhook-signature. These headers are removed:

  • X-Flint-Signature, the older t=<unix>,v1=<hex> signature. Verify webhook-signature instead, as Step 4 of the Webhooks guide shows. The Flint SDKs' verifyWebhook and any Standard Webhooks library already check these headers.
  • X-Flint-Webhook-ID. webhook-id carries the same event ID, so deduplicate on it.
  • X-Flint-Event-Type, which repeated the body without a signature. Read event_type from the verified body. On a delivery rate callback, a connection check's body is {"type":"connection_check"} and a test delivery has "test": true.
  • X-Flint-Key-ID on delivery rate callbacks. X-Flint-Key-IDs still lists every key with a signature on the request, current key first.

X-Flint-Webhook-Endpoint-ID stays, so one URL that serves several endpoints can choose the secret before verifying. The OpenAPI document's x-flint-webhooks.signing no longer lists legacy_headers.

  • Breaking change
  • API
  • Checkout
  • Orders
  • Payments

Checkout sessions stay open when you edit the order#

Changing an order's line items, discounts, charges, tax, or tip with your API key ended its open checkout session with terminal_reason: "order_mutated" and sent checkout_session.invalidated. The session now stays open with the same ID, URL, and checkout credential. It keeps the buyer's saved contact and time zone, and a buyer who confirmed their email with a code keeps that credential. Flint re-prices the order in place and sends order.updated. This applies to hosted and embedded sessions.

The buyer approves the new total before paying. A payment with the checkout credential already requires expected_outstanding_money and returns 409 ORDER_CHANGED_REFRESH_REQUIRED when it no longer matches the order. POST /v1/orders/{order_id}/pay now also accepts an optional expected_version with the pay, confirm_payment_intents, and setup actions. A mismatch returns the same 409 with param: expected_version, which catches an edit that changes the order but not its total. Starting a payment advances the order's version, so after a declined or failed attempt, use the order in the pay response or read it again before retrying. If you also send accepted_gift_card_allocation, its order_version must match, or the request returns 400 INVALID_GIFT_CARD_SELECTION.

An edit that keeps what delivery was priced from, such as a charge, tip, or tax change, keeps the buyer's delivery selection. A change to line items, quantities, prices, or discounts releases it, quotes from before the edit return DELIVERY_QUOTE_STALE, and paying returns FULFILLMENT_SELECTION_REQUIRED until the buyer selects from a new quote.

Closing the order, or an edit that leaves nothing to pay, still ends the session with order_mutated. Sessions for an invoice, a return, or a subscription plan keep their current behavior. A session already past expires_at ends as expired when you edit the order. Changing customer_id while a session is open still returns 409 ORDER_CUSTOMER_CHECKOUT_ACTIVE.

Breaking: creating a new session after an order edit now returns 409 CHECKOUT_SESSION_ALREADY_EXISTS, with the open session in existing_checkout_session_id. Keep using that session, or replace it on purpose with replace_checkout_session_id. Don't wait for checkout_session.invalidated after an edit. See Changing the order during checkout.

  • Breaking change
  • API
  • Errors

Validation errors use INVALID_REQUEST, and enum values match exactly#

Breaking: validation failures that had a different code on each endpoint now return INVALID_REQUEST (400), with param naming the field and message saying what to send. details[0] repeats param and message with code REQUIRED for a missing field or INVALID_VALUE for a value Flint rejects. When no single field is at fault, such as an update that sends none of its fields, there is no param and details[0].code is INVALID_REQUEST. Branch on INVALID_REQUEST once instead of per endpoint. It replaces about 320 codes, for example:

  • Missing fields: LINE_ITEM_NAME_REQUIRED, EXPECTED_VERSION_REQUIRED, AMOUNT_MONEY_REQUIRED, RANGE_REQUIRED, FIELD_REQUIRED, and the MISSING_* codes.
  • Unsupported values: INVALID_STATUS, INVALID_PAYMENT_STATUS, INVALID_REFUND_STATUS, and the other INVALID_<RESOURCE>_STATUS filter codes, INVALID_SORT_BY, INVALID_SORT_FIELD, INVALID_SORT_DIRECTION, INVALID_CAPTURE_METHOD, INVALID_ENUM_VALUE, and similar.
  • Malformed timestamps: INVALID_CREATED_AFTER, INVALID_UPDATED_BEFORE, INVALID_INTERVAL_START_AT, INVALID_TIMESTAMP, and similar.
  • Inverted ranges: INVALID_CREATED_RANGE, INVALID_REPORT_INTERVAL, SHIPMENT_CREATED_RANGE_INVALID, the min_quantity above max_quantity case of INVALID_QUANTITY_RANGE, and INVALID_RANGE. param names the later bound.
  • Malformed IDs: INVALID_ID, INVALID_ID_FORMAT, INVALID_RESOURCE_ID, INVALID_SOURCE_ENVIRONMENT_ID, and similar.
  • Boolean query parameters: INVALID_ACTIONABLE, INVALID_HAS_PLAN, INVALID_BOOLEAN, and similar.
  • Other malformed requests: VALIDATION_ERROR, INVALID_REQUEST_BODY, INVALID_GIFT_CARD_REQUEST, INVALID_CUSTOMER_ACCOUNT_REQUEST, and REQUEST_FAILED on a 400.

Also:

  • Enum values in bodies, query parameters, and headers must match the published value exactly. ACTIVE, " active", and "active " return INVALID_REQUEST. Enum list filters still trim spaces around each comma-separated value.
  • An explicit null on a field that can't be cleared returns NULL_NOT_ALLOWED everywhere, including fields that returned INVALID_METADATA or INVALID_WEBHOOK_ENDPOINT for it.
  • Codes that ask you to do something other than correct a field keep their names, such as ORDER_REVISION_REQUIRED, IDEMPOTENCY_KEY_REQUIRED, MERCHANT_ONBOARDING_REQUIRED, and DELIVERY_RECIPIENT_REQUIRED.
  • When a request is complete but would leave a saved resource without something it needs, the specific code stays: BUNDLE_COMPONENTS_REQUIRED for an update that leaves an active bundle without components, and INVENTORY_ROUTING_SOURCE_REQUIRED for paying an order, or updating a plan or payment link, whose tracked line items have no routing source. The same fields missing from a create request return INVALID_REQUEST.
  • Some update-only codes keep their names, such as NAME_REQUIRED and CHARGE_NAME_REQUIRED.
  • A payment link line item with min_quantity or max_quantity below 1 returns INVALID_QUANTITY with param naming the field, such as line_items[0].min_quantity, instead of INVALID_QUANTITY_RANGE with param line_items.

Each operation's x-flint-error-codes lists INVALID_REQUEST, REQUIRED, and INVALID_VALUE, and Error handling describes it.

  • Breaking change
  • API
  • Orders
  • Checkout
  • Payments
  • Gift-cards
  • Customers

Consistent names for versions, references, and checkout settings#

Breaking: every field, filter, and value below is renamed with no alias. A request that sends an old field returns UNKNOWN_FIELD, and an old query parameter returns UNSUPPORTED_QUERY_PARAM. Error param values and messages use the new names. Error codes keep their names, such as ORDER_REVISION_REQUIRED and CHECKOUT_SESSION_REVISION_CONFLICT.

A counter that guards against concurrent changes is now always version, its fence is expected_version, and a conflict reports current_version. A counter for one part of a resource is <part>_version. revision now names only snapshots with their own IDs, such as return policy revisions and delivery configuration revisions, and those names are unchanged.

Orders#

WhereOldNew
Orderorder_revisionversion
Update, close, line item add, charge add and update, discount apply, remove, and reprice, gift card selection, and pay requestsorder_revisionexpected_version
DELETE line item, charge, and gift card routes, queryorder_revisionexpected_version
gift_card_estimate and accepted_gift_card_allocationorder_revisionorder_version
ORDER_CHANGED_REFRESH_REQUIRED errororder_revisioncurrent_version, with param naming the fence you sent

Every order DELETE returns the order, so its expected_version is the order's version.

Inventory#

WhereOldNew
Inventory level, including a movement's resulting_inventory_levelinventory_level_physical_revisionphysical_version
Inventory level, including a movement's resulting_inventory_levelinventory_level_claim_revisionclaim_version
Inventory movementinventory_level_revisioninventory_level_version
Inventory movementinventory_level_physical_revisioninventory_level_physical_version
Inventory movementinventory_level_claim_revisioninventory_level_claim_version
Inventory count linecaptured_physical_revisioncaptured_physical_version
Inventory count conflict errorcaptured_physical_revisioncaptured_physical_version
Inventory count conflict errorcurrent_physical_revisioncurrent_physical_version
Inventory count conflict error, conflict_type valuephysical_revisionphysical_version

Locations and delivery#

WhereOldNew
Locationgeography_revisiongeography_version
location.inventoryinventory_revisioninventory_version
Inventory assignments, reservation lines, and checkout delivery pinned dependenciesgeography_revisionlocation_geography_version
Delivery revocation targetslocation_geography_revisionlocation_geography_version
Delivery quotes, delivery selections, and the delivery rate callback requestdelivery_quote_revisiondelivery_quote_version
Delivery rate callback request, execution_legs[]origin_geography_revisionorigin_geography_version
Delivery quotes and delivery selectionseligibility_context_revisioneligibility_context_version
DELIVERY_ELIGIBILITY_CONTEXT_CHANGED errorparam: expected_eligibility_context_revisionNo param, because no request field caused it
WhereOldNew
Checkout session and payment link tip, and tipping settingsis_custom_tip_enabledcustom_tip_enabled
Checkout session and payment link tip, and tipping settingsis_smart_tips_enabledsmart_tips_enabled
receipts settingsis_auto_email_enabledauto_email_enabled
Checkout session and payment link customer_collectionenable_address_autocompleteaddress_autocomplete_enabled
checkout settingspromotion_code_entry_enabledpromotion_codes_enabled
Checkout sessionrecovery_modeis_in_recovery
Checkout sessionsave_payment_method_offeredcan_save_payment_method
Checkout sessionsave_payment_method_phone_offeredcan_save_payment_method_with_phone
GET /v1/payment-links filterhas_planhas_subscription_plan
Checkout session customer verification (cscv_)customer_verification_idcheckout_session_customer_verification_id
Checkout session customer verification confirm route, path parameter{customer_verification_id}{checkout_session_customer_verification_id}
resource_type for a cscv_ IDcustomer_verificationcheckout_session_customer_verification
Checkout session modifier conflict, conflict_details[]latest_revisioncurrent_version

Customer verifications at /v1/customer-verifications (cver_) keep customer_verification_id.

Returns and credit notes#

WhereOldNew
Credit notes, their webhooks, and create and update requestscredit_note_linesline_items
Credit note line itemcredit_note_line_idcredit_note_line_item_id
Credit note line itemdescriptionname
Return eligibility preview line itemis_self_service_enabledself_service_enabled
Return inspection, its create request, and the GET /v1/return-inspections filterlocation_idinspection_location_id
POST /v1/return-policies/{return_policy_id}/revisionsexpected_current_return_policy_revision_idRemoved

Publishing a return policy revision now takes one fence: the policy's version as expected_version, which is required. Without it the request returns 400 naming expected_version. Publishing and policy updates both raise version, so it detects a concurrent publish or edit.

In the OpenAPI spec, CreditNoteLine is CreditNoteLineItem, CreditNoteLineRequest is CreditNoteLineItemInput, and the ReturnEligibilityCheck schemas are ReturnEligibilityPreview schemas.

Invoices, subscriptions, and timelines#

WhereOldNew
Invoice payment terms snapshotrevisionversion
subscription.delivery, including its webhooksrevisiondelivery_version
Resource timeline entryimage_revisionimage_version

Gift cards#

WhereOldNew
POST /v1/gift-card-redemptionsexternal_reference_idsale_reference
Gift card redemptions and their webhooksexternal_reference_idsale_reference, null for source_type: flint_order
Gift card redemptions from a Flint order's paymentexternal_reference_id, which held the payment attempt IDorder_payment_attempt_id
GET /v1/gift-card-redemptions filterexternal_reference_idsale_reference
POST /v1/gift-cards/{gift_card_id}/cash-outsexternal_reference_idpayout_reference
Gift card transactions and gift_card_transaction.createdexternal_reference_idpayout_reference, set only on cash_out transactions
GET /v1/gift-card-transactions filterexternal_reference_idpayout_reference

sale_reference is your reference for the sale a redemption pays for. payout_reference is your reference for the payout you made outside Flint, such as a check number or transfer ID. Gift cards and funding sources keep external_reference_id.

Customers#

WhereOldNew
Customer and its create and update requestsis_verifiedis_merchant_verified
Customer and its create and update requestsgroup_idsegment
Promotion rule attributecustomer.is_verifiedcustomer.is_merchant_verified
Promotion rule attributecustomer.group_idcustomer.segment
Delivery eligibility conditioncustomer_verifiedcustomer_merchant_verified
Delivery eligibility conditioncustomer_groupcustomer_segment

is_merchant_verified is a flag you set, for example after checking ID in store. Flint never sets it, and it is unrelated to customer verifications. segment is a free-form label, such as wholesale, not an ID.

Payments#

WhereOldNew
Payment method domainpayment_optionspayment_option_statuses
PaymentIntent confirm, pay payment_source and setup_payment_source, and pay payment_intents[]confirmation_tokenstripe.confirmation_token
PaymentIntent, including buyer payments and payment webhooksoriginRemoved; read payment_flow
GET /v1/payment-intents and GET /v1/me/payments filteroriginRemoved; filter by payment_flow

payment_option_statuses reports each wallet's domain status. Send a Stripe ConfirmationToken as {"stripe": {"confirmation_token": "ctoken_..."}}; errors about it name stripe.confirmation_token, prefixed by its containing object, such as payment_source.stripe.confirmation_token. payment_flow names the channel for other payments (checkout, payment_link, virtual_terminal, api), and for an invoice or subscription payment it names that flow instead (invoice, subscription_initial, subscription_renewal). To see the channel an invoice payment came through, read origin on its checkout session or order, which keep it.

Organizations and payout destinations#

WhereOldNew
Organization status and the GET /v1/organizations status filterdeletedarchived
Payout destination status, its webhooks, and the GET /v1/payout-settings/destinations status filterdeletedarchived
GET /v1/payout-settings/destinationsinclude_deletedinclude_archived

A deleted organization or payout destination stays readable by ID, so it reports archived. The payout_destination.deleted event keeps its name, and its payload reports status: archived. Categories still report deleted, because deleting one removes it.

  • Breaking change
  • API
  • Errors

Clear fields with null; empty strings are rejected#

Breaking: "" in any request string field returns 400 INVALID_REQUEST, with param naming the field, such as line_items[2].note. This includes enums, IDs, timestamps, URLs, and nested fields. Before, many update routes treated "" as a clear, and other fields stored it. The message says when null clears the field. The exceptions are state and postal_code in an AddressInput or OrderDeliveryDestinationAddressInput and state in a saved address, which are "" in countries that have none. Saved addresses, under /v1/me/addresses and /v1/customers/{customer_id}/addresses, require postal_code.

Breaking: a metadata value can't be "". {"metadata": {"color": ""}} returns INVALID_REQUEST with param set to metadata.color. To delete a key on an update, send {"metadata": {"color": null}}. "metadata": null still clears all of your keys.

Breaking: to clear a field, send null. Fields that used to clear on "" now clear on null, including:

  • PATCH /v1/merchant: email, phone, support_email, support_phone, support_url, and website_url. Before, null on these was ignored.
  • PATCH /v1/categories/{category_id}: description and external_reference_id. Before, null was ignored.
  • PATCH /v1/delivery-methods/{delivery_method_id}: description.
  • PATCH /v1/settings: customer_account.merchant_account_url, customer_account.presentation.account_name, customer_account.presentation.custom_domain, and each customer_account.route_templates entry; the branding colors and font_family; receipts.header_text and receipts.footer_text; the four legal URLs; tax.default_line_item_tax_category and tax.default_delivery_tax_category; and the invoices text fields.
  • PATCH /v1/bundles/{bundle_id}: a component's delivery_profile_id. Leaving it out still keeps the inherited profile.
  • PATCH /v1/payment-links/{payment_link_id}: description, inactive_message, external_reference_id, redirects.success_redirect_url, and redirects.cancel_redirect_url; theme.primary_color, theme.accent_color, and theme.title; payments.payment_note; the four legal URLs; expiration.expiration_url; custom_text.shipping_address_label and custom_text.order_summary_message; and event_config.venue and event_config.ticket_prefix.
  • PATCH /v1/products/{product_id}: default_variant_id, where the product's options allow it. PATCH /v1/products/{product_id}/variants/{variant_id}: name.
  • PATCH /v1/payout-settings: statement_descriptor.
  • POST /v1/onboarding/advance: profile.email, profile.support_email, profile.support_phone, profile.support_url, and profile.website_url.
  • PATCH /v1/orders/{order_id}: delivery_destination.address.line2, delivery_destination.recipient.name, and delivery_destination.recipient.phone. PATCH /v1/orders/{order_id}/line-items/{order_line_item_id}: gift_card_recipient.name and gift_card_recipient.message.
  • PATCH /v1/subscriptions/{subscription_id} and POST /v1/me/subscriptions/{subscription_id}/delivery: delivery.recipient.name, delivery.recipient.email, and delivery.recipient.phone. POST /v1/checkout-sessions/{checkout_session_id}/delivery-selections: recipient.name, recipient.email, and recipient.phone.
  • PATCH /v1/customers/{customer_id}: phone, internal_note, external_reference_id, segment, and default_invoice_payment_term_id.
  • PATCH /v1/customers/{customer_id}/addresses/{customer_address_id} and PATCH /v1/me/addresses/{customer_address_id}: phone and label. PATCH /v1/me: name and phone.
  • PATCH /v1/payment-intents/{payment_intent_id}: external_reference_id and receipt_email.
  • PATCH /v1/orders/{order_id}: buyer_note, internal_note, and external_reference_id.
  • PATCH /v1/invoices/{invoice_id}: memo, footer, po_number, reference, recipient_email, and external_reference_id.
  • PATCH /v1/subscription-plans/{subscription_plan_id}: description and external_reference_id.
  • PATCH /v1/webhook-endpoints/{webhook_endpoint_id}: description.

Breaking: an empty string that used to return a field-specific code, such as INVALID_CAPTURE_METHOD, INVALID_CHECKOUT_SURFACE, or INVALID_EXTERNAL_REFERENCE_ID, now returns INVALID_REQUEST.

Breaking: where a field trimmed its value and then treated an empty result as a clear, such as PATCH /v1/settings text fields, a category description, and order notes, a value that is only spaces now returns INVALID_REQUEST instead of clearing the field.

Breaking: null on a field that can't be cleared returns 400 NULL_NOT_ALLOWED on routes that ignored it before, including the merchant's business_name and reporting_timezone, a category, API key, modifier group, or modifier set name, an address recipient_name, and a location geography's timezone.

Request string fields in the OpenAPI spec publish minLength: 1, and fields you can clear are nullable, with a description that says to send null. Where a schema is shared with responses that can return "", requests use a separate copy named with an Input suffix, such as AddressInput, ThemeConfigInput, and PromotionRuleInput; response schemas don't change.

  • Breaking change
  • API
  • Webhooks

Webhook events carry their resource in data.object, and event names follow one rule#

Breaking: every webhook event's data now has one member, object: the affected resource as its GET returns it, without expansions or the few caller-specific fields the event catalog lists. This replaces the four shapes events used before (flat fields, the bare resource, a {"payment_intent": ...} style wrapper, and {"object": ...} on a few events). The envelope's payload_version is now 2. Events that carried only an ID now carry the full resource, and every event in the OpenAPI document has a typed schema: event_type is narrowed to its one value and data.object references the resource's schema.

JSON
{
  "webhook_event_id": "whev_1kmn0aExample",
  "event_type": "order.paid",
  "payload_version": 2,
  "api_version": "2026-09-07",
  "mode": "test",
  "merchant_id": "mer_1kmn0aExample",
  "created_at": "2026-07-03T14:00:00Z",
  "test": false,
  "request": null,
  "data": {
    "object": {
      "order_id": "ord_1kmn0aExample",
      "status": "closed",
      "payment_status": "paid"
    }
  }
}

The object shown is abbreviated; deliveries carry the order as GET /v1/orders/{order_id} returns it.

Fields that only existed on events are gone. Read them from the resource or from the event that owns them:

  • Transition details such as previous_status, current_status, changed_fields, previous_values, reason, cause, and initiated_by are no longer sent. Fulfillment transitions are recorded on fulfillment_event.created, whose fulfillment event carries previous_status and current_status.
  • resource_updated_at and revision copies such as inventory_level_revision are gone. Use the resource's updated_at and version.
  • subscription.payment_succeeded and subscription.payment_failed no longer carry order_id or payment_intent_id. The renewal order sends order.paid, and the payment sends payment_intent.*.
  • Invoice events no longer carry payment attempt, delivery attempt, refund, or late fee details. Payment attempts have their own events (below), late fees are in the invoice's late_fees, and delivery attempts are listed at GET /v1/invoices/{invoice_id}/delivery-attempts.
  • custom_domain.status_changed no longer carries previous_status. Custom domain status objects, including those in GET /v1/settings, now include domain_type.
  • merchant.readiness_updated carries the merchant, so merchant_environment_id is gone.
  • delivery_revocation.created carries the delivery revocation as GET /v1/delivery-revocations/{delivery_revocation_id} returns it, so its estimated impact uses active_quote_count and current_selection_count instead of active_quotes and provisional_selections.

Breaking: the envelope's test field is always present: true on synthetic events from the test-events endpoint and false on every other event. It used to be omitted unless true. Partner app envelopes carry it too.

Breaking: partner app deliveries no longer add routing fields to data. Installed-merchant deliveries used to merge source_type, mode, merchant_id, partner_app_install_id, environment_grant_id, and environment_id into data, which overwrote resource fields with the same name, such as a gift card transaction's source_type. The partner envelope now carries them in source, and data is byte-identical to the merchant event:

JSON
{
  "webhook_event_id": "whev_1kmn0aExample",
  "event_type": "customer.created",
  "payload_version": 2,
  "api_version": "2026-09-07",
  "partner_app_id": "pa_1kmn0aExample",
  "created_at": "2026-07-03T14:00:00Z",
  "test": false,
  "source": {
    "type": "installed_merchants",
    "merchant_id": "mer_1kmn0aExample",
    "partner_app_install_id": "pinst_1kmn0aExample",
    "mode": "test",
    "environment_grant_id": "egrt_1kmn0aExample",
    "environment_id": "test_1kmn0aExample"
  },
  "data": { "object": { "customer_id": "cus_1kmn0aExample" } }
}

Partner app lifecycle events carry source.type partner_app with the install's merchant_id and partner_app_install_id.

Breaking: event types are named <resource_type>.<event> with exactly one dot, where <resource_type> is the resource in data.object. These types were renamed:

Previous nameNew name
credit_note.allocation_createdcredit_note_allocation.created
credit_note.allocation_reversedcredit_note_allocation.reversed
customer.deletion_requestedcustomer_deletion_request.created
customer.deletion_completedcustomer_deletion_request.completed
customer.deletion_rejectedcustomer_deletion_request.rejected
inventory.action_requiredinventory_reservation.action_required
inventory.count.appliedinventory_count.applied
inventory.level.updatedinventory_level.updated
inventory.receipt.createdinventory_receipt.created
inventory.reservation.at_riskinventory_reservation.at_risk
inventory.reservation.closedinventory_reservation.closed
inventory.reservation.committedinventory_reservation.committed
inventory.reservation.consumedinventory_reservation.consumed
inventory.reservation.createdinventory_reservation.created
inventory.reservation.hold_expiredinventory_reservation.hold_expired
inventory.reservation.releasedinventory_reservation.released
inventory.shortage.detectedinventory_level.shortage_detected
inventory.transfer.closedinventory_transfer.closed
inventory.transfer.departedinventory_transfer.departed
inventory.transfer.lostinventory_transfer.lost
inventory.transfer.receivedinventory_transfer.received
inventory.transfer.returnedinventory_transfer.returned
invoice.payment_processinginvoice_payment_attempt.processing
invoice.payment_failedinvoice_payment_attempt.failed
invoice.payment_attempt_canceledinvoice_payment_attempt.canceled
invoice.payment_attempt_expiredinvoice_payment_attempt.expired
merchant.readiness.updatedmerchant.readiness_updated
order.fulfillment.createdfulfillment.created
order.fulfillment.updatedfulfillment.updated
order.fulfillment.completedfulfillment.completed
order.fulfillment.status_changedfulfillment.status_changed
order.fulfillment.event.createdfulfillment_event.created
order.fulfillment.shipment.createdshipment.created
order.fulfillment.shipment.updatedshipment.updated
order.fulfillment.package.createdpackage.created
order.fulfillment.package.updatedpackage.updated
order.inventory_exception.createdorder.inventory_exception_created
order.inventory_exception.resolvedorder.inventory_exception_resolved
payment_intent.fulfillment_hold.updatedpayment_intent.fulfillment_hold_updated
payout_destination.deletedpayout_destination.archived
partner_app.install.createdpartner_app_install.created
partner_app.install.updatedpartner_app_install.updated
partner_app.install.permissions_updatedpartner_app_install.permissions_updated
partner_app.install.revokedpartner_app_install.revoked
partner_app.install.environment_grant.createdenvironment_grant.created
partner_app.install.environment_grant.revokedenvironment_grant.revoked

The invoice payment attempt events now carry the payment attempt, including failure_code and failure_message, instead of the invoice.

Breaking: two duplicate events were removed:

  • order.inventory_action_required was always sent with order.inventory_exception.created. Use order.inventory_exception_created.
  • delivery_rate.created, delivery_rate.updated, and delivery_rate.archived were always sent with delivery_method.created or delivery_method.updated, whose delivery method includes its rates. Use the delivery method events.

Events Flint queued before this change and delivers afterwards arrive with payload_version: 1, their previous data shape, and their new event name, so switch on payload_version while those drain. Webhook endpoints still accept the previous names in enabled_events for one release. Flint stores and returns the new name, removed events map to the event that replaces them, and existing endpoints subscribed to a previous name receive the new event. Deliveries use only the new names, so update handlers that switch on event_type.

  • Breaking change
  • API
  • Customers

Buyer lists accept only buyer-visible filters, and rejected customer sessions return 401#

Superseded by Boolean and currency field renames and integer bounds.

Each /v1/me list now accepts an explicit set of filters on fields the buyer can see. Other filters return 400 with UNSUPPORTED_QUERY_PARAM. The removed filters are:

  • GET /v1/me/orders: external_reference_id, return_id, return_resolution_id
  • GET /v1/me/payments: external_reference_id, risk_level, dispute_status, return_id, return_resolution_id, query
  • GET /v1/me/refunds: payment_intent_id, reason, refund_method, external_reference_id, return_resolution_id, query
  • GET /v1/me/fulfillments: external_reference_id, location_id, query
  • GET /v1/me/shipments and GET /v1/me/packages: external_system, external_reference_id, query
  • GET /v1/me/invoices: external_reference_id, query
  • GET /v1/me/subscriptions: awaiting_billing_schedule, subscription_offer_id
  • GET /v1/me/returns: external_reference_id, query, receiving_location_id, resolution_type, work_type

query on GET /v1/me/orders searches the order ID, order number, buyer note, and line item names. It no longer matches the merchant note, the external reference ID, or the buyer email.

Payments read with a customer session no longer include dispute_status or settlement_status, so a buyer can't tell that a payment was disputed. GET /v1/me/payments now documents its items as BuyerPaymentIntent, which also omits the fee, net, and risk fields buyers never received.

Refunds read with a customer session now include return_id, so GET /v1/me/refunds?return_id= filters on a field the buyer receives.

Draft invoices are no longer visible to buyers. GET /v1/me/invoices leaves them out and rejects status=draft, and getting a draft invoice, its PDF, or its credit notes returns 404.

A /v1/me request whose customer session secret is malformed, unknown, or revoked now returns 401 with INVALID_CUSTOMER_SESSION instead of 404 with CUSTOMER_SESSION_NOT_FOUND. Treat it as a sign-out: authenticate the buyer again and create a new customer session. An expired secret still returns 401 with CUSTOMER_SESSION_EXPIRED. See Customer sessions.

POST /v1/me/subscriptions/{subscription_id}/payment-method with another customer's payment method now returns 404 with PAYMENT_METHOD_NOT_FOUND, before any check of that payment method's status. With an API key, another customer's payment method still returns PAYMENT_METHOD_CUSTOMER_MISMATCH, now also before status checks. On both routes, a payment method that doesn't exist returns PAYMENT_METHOD_NOT_FOUND with param set to payment_method_id, instead of RESOURCE_NOT_FOUND.

POST /v1/me/email-change-requests counts every attempt toward its limit of three per 15 minutes, including attempts refused because the address is already used. Over the limit, it returns 429 with EMAIL_CHANGE_RATE_LIMITED and a Retry-After header.

POST /v1/customer-sessions/{customer_session_id}/revoke now returns 404 for a session in another sandbox, matching revoke-all.

Update, 2026-10-23: Customer session authentication failures now return 401 INVALID_CREDENTIAL. details[0].reason is unknown for a malformed, unknown, or revoked customer session secret, and expired for an expired secret. Re-authenticate the buyer for unknown; refresh the session and retry for expired. These current codes replace the authentication codes described above. See Customer sessions.

  • Breaking change
  • API
  • Catalog

Catalog updates handle null consistently and reject changes to archived products#

Breaking: on PATCH for products, variants, bundles, devices, modifier groups, and modifier sets, null clears an optional field, such as description, sku, barcode, modifier_set_id, or metadata. null on a required field or a list now returns 400 NULL_NOT_ALLOWED with the field in param. Before, null on some fields was ignored, and null on options, categories, and components returned INVALID_OPTIONS, INVALID_CATEGORIES, or INVALID_COMPONENTS.

Breaking: metadata: null on a modifier group or modifier set now clears its metadata. Before, it was ignored.

Breaking: PATCH /v1/modifier-groups/{modifier_group_id} changes only the text settings you send. Before, sending {"text": {"max_length": 80}} reset required, multiline, and min_length. null on text.min_length or text.max_length clears it, and an empty text object returns 400 FIELD_REQUIRED.

Breaking: metadata limits apply to the result of a PATCH, after your changes are merged into the stored keys, on products, variants, bundles, categories, devices, and Locations. A patch that would leave more than 50 keys returns 400.

Breaking: PATCH /v1/products/{product_id} on an archived product returns 409 PRODUCT_ARCHIVED with current_status: archived. Before, it returned 404.

Empty categories, selected_options, components, modifiers, and modifier_groups arrays are now returned as [] instead of being left out. DELETE responses for products, variants, and bundles include modifier_set_id like GET does.

  • API
  • Customers
  • Errors

Duplicate customer emails name the existing customer#

POST /v1/customers with an email that another customer in the same environment already uses still returns 409 CUSTOMER_EMAIL_ALREADY_USED with param set to email. The error now also includes blocking_resources with that customer's ID, such as [{"resource_type": "customer", "resource_id": "cus_..."}], and blocking_resource_count of 1, so you no longer need GET /v1/customers?email= to find it.

Only merchant credentials receive blocking_resources. Buyer email changes through /v1/me/email-change-requests return the same code without naming the other customer. See Headless storefront.

  • API
  • Customers

Customer session secrets end with their refresh token#

A customer session's secret could outlast its refresh_token. A session created with a 24 hour expires_in_seconds and a 1 hour refresh_expires_in_seconds had a secret valid for 24 hours, and a refresh just before the refresh deadline issued a secret valid past it.

POST /v1/customer-sessions and POST /v1/customer-sessions/refresh now end the secret no later than refresh_token_expires_at, and expires_at returns that earlier time. When the refresh token ends, the buyer signs in again, as the refresh window promises.

INVALID_CUSTOMER_SESSION errors for an out-of-range lifetime now name expires_in_seconds, refresh_expires_in_seconds, and account_url_expires_in_seconds, the fields you send. See Customer sessions.

  • Breaking change
  • API
  • Devices

Archived devices report archived and release their fingerprint#

Breaking: a device retired with DELETE /v1/devices/{device_id} now reports status: archived instead of deleted, and GET /v1/devices?status=archived lists archived devices. PATCH on an archived device returns 409 DEVICE_ARCHIVED with current_status: archived, replacing DEVICE_DELETED.

Archiving a device releases its hardware_fingerprint, which the archived device no longer returns. POST /v1/devices with that fingerprint creates a new device instead of returning the archived one. When two registrations with the same fingerprint race, both return the same device, one with already_existed: true.

Breaking: a location_id that doesn't match a location now returns 404 RESOURCE_NOT_FOUND on device create and update, and a malformed location_id on create returns 400. Before, both returned 409 LOCATION_UNAVAILABLE, which now means only that the location isn't active.

Breaking: the status and sort_by filters on GET /v1/devices match exactly. Values in another letter case or with surrounding spaces return 400.

  • Breaking change
  • API
  • Disputes
  • Risk

Dispute field names, review refunds, and risk previews#

Breaking: dispute fields are renamed in API responses and dispute.* webhooks:

BeforeAfter
evidence_deadline_passedis_evidence_deadline_passed
evidence_response_allowedcan_respond_with_evidence
evidence_submission_past_dueis_evidence_submission_past_due
action_requiredis_action_required

Disputes no longer include metadata, which was always empty.

Breaking: reviews report their refund as refunded_money instead of refunded_amount_money, in API responses and review.* webhooks. GET /v1/reviews also accepts created_before.

Breaking: POST /v1/risk-previews returns 200 for a rule with problems, with valid: false, analysis: null, and every problem in issues. It previously returned a 400 for the first problem only. Malformed requests still return 400. Previews now need only risk.read.

Risk lists include origin and editable, like rules. Flint's default lists have editable: false: renaming one now returns LIST_RESERVED, as archiving one already did. You can still add and remove their values.

Reusing an Idempotency-Key on a risk rule, list, or list item route for a different rule, list, or item now returns an idempotency conflict instead of replaying the first response.

  • API
  • Settings
  • Promotions

Effective settings include promotion defaults#

GET /v1/settings/effective now returns all three promotions fields. Unset values default to automatic_enabled: true, codes_enabled: true, and max_promotions_per_order: 2. Existing promotion settings and legacy coupon settings continue to apply.

GET /v1/settings continues to return stored values without filling in promotion defaults.

  • Breaking change
  • API
  • Fulfillment
  • Delivery

Fulfillment command results, external references, and delivery configuration lists#

Superseded by Fulfillment lifecycle verbs.

Breaking: external_system and external_reference_id no longer deduplicate shipments and packages. A second create with the same reference makes a second shipment or package, and an update can reuse a reference. To retry a create safely, send the same Idempotency-Key. The replayed field and the FULFILLMENT_SHIPMENT_PROVIDER_REFERENCE_CONFLICT and SHIPMENT_PACKAGE_PROVIDER_REFERENCE_CONFLICT errors are gone.

Breaking: fulfillment, shipment, and package commands that produce events or emails return data as the resource plus events, fulfillment_notifications, and unchanged, all always present. The event array is always named events, replacing event on transitions and voids and fulfillment_event on package create and update. Package transitions no longer return package_status_update. Commands without side effects return the resource itself in data:

Routedata
PATCH /v1/fulfillments/{fulfillment_id}The fulfillment. It previously returned the order
POST /v1/fulfillments/{fulfillment_id}/shipmentsThe shipment
PATCH /v1/shipments/{shipment_id}The shipment

Breaking: fulfillment transitions name every action's time occurred_at. complete takes occurred_at instead of completed_at, and cancel accepts it too. hold and mark_no_show accept reason_message beside reason, shown as active_hold.reason_notes and outcome.notes. When you leave out expected_version and another change lands first, FULFILLMENT_CHANGED, SHIPMENT_CHANGED, and PACKAGE_CHANGED no longer name expected_version in param.

Breaking: GET /v1/fulfillment-events filters event_type by the values events report: status_changed and the carrier and tracking event types.

Breaking: delivery profile, zone, location set, method, and rate callback lists leave archived resources out unless you send status=archived or include_archived=true. A DELETE on an archived resource returns 200 with the resource, and any other change returns 409 DELIVERY_STATE_CONFLICT with current_status. Profiles, zones, and location sets publish active and archived as their statuses; methods and rate callbacks add inactive. revoked is no longer listed, because no configuration resource reaches it.

Breaking: POST /v1/delivery-rate-callbacks/{delivery_rate_callback_id}/rotate-secret and /check-connection return 200 instead of 201. Delivery revocations name signing-key targets delivery_rate_callback_signing_key and take expected_version at the top level of the request. Delivery previews drop selection_authority, always include merchant_diagnostics for your API key, and reject a currency that isn't an uppercase ISO code. Delivery methods always include display_position and type.

GET /v1/delivery-quotes/{delivery_quote_id} reads one issued quote. GET /v1/delivery-quotes validates checkout_session_id and order_id and parses created_after and created_before as RFC 3339 timestamps.

  • Breaking change
  • API
  • Gift-cards
  • Customers

Gift card command responses, funding limit errors, and customer null handling#

Superseded by Gift card lifecycle verbs and shared status words.

Breaking: these gift card and customer changes rename fields and change response shapes.

  • Gift card writes return the resource they created or changed in data instead of a command wrapper. Card updates and transitions return the gift card. Issuance and code rotation return the gift card with code and secret_recovery_expires_at. Loads and redemptions return the load or redemption with the updated card in gift_card, and capture and cancel return the redemption the same way. Adjustments and cash-outs return the gift card with gift_card_transaction_ids, now with status 200. Notification create and cancel return the notification. See what each command returns.
  • The funding source field reference_id is now external_reference_id, on requests, loads, refund provenance, and webhooks.
  • GET /v1/gift-card-loads filters with funding_source_type instead of source_type and source_external_reference_id instead of source_id. GET /v1/gift-card-transactions rejects unknown source_type values.
  • POST /v1/orders/{order_id}/gift-cards takes the gift card code as code instead of gift_card_code, matching POST /v1/gift-cards/lookup.
  • Redemptions include source_type, and automatic redemptions return expires_at: null.
  • A load, import, or adjustment over a funding limit returns 409 GIFT_CARD_FUNDING_LIMIT_EXCEEDED with the limit in reason and maximum_money, instead of GIFT_CARD_STATE_CONFLICT.
  • A stale expected_version on a gift card command returns 409 GIFT_CARD_VERSION_CONFLICT with current_version. Other gift card state conflicts include current_status.
  • An unexpected gift card failure returns 500 INTERNAL_ERROR instead of 503 GIFT_CARDS_UNAVAILABLE.
  • Replaying an issuance or code rotation after the code was replaced omits code, because the old code no longer works.
  • On PATCH /v1/customers/{customer_id}, null clears name, phone, internal_note, external_reference_id, and group_id, and returns 400 NULL_NOT_ALLOWED on tax_exempt and is_verified. Previously, null was ignored.
  • Customer deletion requests return 409 for state conflicts, with the request's current_status: CUSTOMER_DELETION_REQUEST_NOT_PENDING, CUSTOMER_DELETION_ALREADY_APPROVED, and CUSTOMER_DELETION_STATE_CHANGED. These were 400 INVALID_CUSTOMER_ACCOUNT_REQUEST. The status filter and decision must match their values exactly; values with other letter case or surrounding spaces, such as Approve, now return 400.

These changes need no action unless you use one of them:

  • GET /v1/gift-card-funding-dispositions/{gift_card_funding_disposition_id} and GET /v1/gift-card-funding-dispositions retrieve and list funding dispositions, which now include idempotency_key.
  • Gift card validation errors name the field in param. External references count characters, not bytes, and are stored exactly as sent.
  • Capturing or canceling a redemption and canceling a notification accept an empty body.
  • POST /v1/email-preference-links/lookup is a read: it no longer stores or replays results by Idempotency-Key.
  • Breaking change
  • API
  • Inventory

Inventory errors name the field, and every inventory resource reads by ID#

Breaking: several inventory errors change code or status so the error names what went wrong.

  • A command that references a missing resource returns that resource's not-found code with the field in param. Creating a transfer with an unknown item returns 404 INVENTORY_ITEM_NOT_FOUND for lines[0].inventory_item_id instead of INVENTORY_TRANSFER_NOT_FOUND. An unknown Location returns 404 LOCATION_NOT_FOUND instead of 409 INVENTORY_LOCATION_NOT_CONFIGURED, and an inactive or archived Location returns 409 LOCATION_NOT_ACTIVE. Reservation and transfer lines that aren't on the resource return 404 INVENTORY_RESERVATION_LINE_NOT_FOUND or 404 INVENTORY_TRANSFER_LINE_NOT_FOUND, and an unknown policy version returns 404 INVENTORY_POLICY_VERSION_NOT_FOUND.
  • An inactive or archived allocation policy returns 409 INVENTORY_POLICY_UNAVAILABLE with its current_status, instead of INVENTORY_ITEM_UNAVAILABLE.
  • Validation errors carry param and a message that names the field. Request shape problems that previously returned a resource code because of the route, such as an invalid ID on a transfer route, return 400 VALIDATION_ERROR. INVENTORY_POLICY_INVALID, INVENTORY_TRANSFER_INVALID, and INVENTORY_RECEIPT_INVALID cover only the policy configuration, transfer body, and receipt line problems they describe.
  • Conflicts with current state return 409 instead of 400: an adjustment that would take stock below zero returns INVENTORY_INSUFFICIENT (previously 400 INVENTORY_CONDITION_INVALID), applying a count with unobserved lines returns INVENTORY_COUNT_INCOMPLETE, a transfer edit that changes a departed line, removes a line with canceled quantity, or sets requested_quantity below the canceled quantity returns INVENTORY_TRANSFER_LINE_CONFLICT, transfer targets the line can't accept return INVENTORY_QUANTITY_CONFLICT, and a receipt above the consumed quantity returns INVENTORY_RECEIPT_CONFLICT.
  • A transition on a closed reservation returns 409 INVENTORY_RESERVATION_CLOSED with closed_reason, instead of INVENTORY_RESERVATION_EXPIRED. commit after owner.expires_at returns 409 INVENTORY_RESERVATION_EXPIRED.
  • Reservation transition lines accept only their action's target fields, and null on a field that can't be cleared, such as an item's name, returns 400 NULL_NOT_ALLOWED instead of being ignored.

Breaking: has_available_quantity, has_unavailable_condition, has_shortage, and has_at_risk_quantity set to false now select the resources without that condition. Previously false was ignored. The movement list's type and reason filters reject values a movement can't carry.

Resending targets that are already applied now succeeds on a closed reservation or a fully departed or closed transfer. A receive without a condition split keeps the split recorded earlier and adds the new quantity to the line's condition. Scalar list filters that hold free-form identifiers, such as sku, barcode, and external_reference_id, accept values containing commas. Item and policy metadata limits apply to the merged result of a PATCH. A lock timeout no longer returns a 409; Flint retries it, and a failure that remains returns 500. A 409 or 404 from an inventory PATCH or DELETE no longer locks its Idempotency-Key, so a retry runs once the state changes. The OpenAPI description now lists provenance as optional on reservation consume and transfer transitions, as Flint already accepted; without it, movements record the time Flint received the request and a null source_system.

New routes read one inventory resource by ID: GET /v1/inventory-levels/{inventory_level_id}, GET /v1/inventory-movements/{inventory_movement_id}, GET /v1/inventory-adjustments/{inventory_adjustment_id}, GET /v1/inventory-reservations/{inventory_reservation_id}, GET /v1/inventory-receipts/{inventory_receipt_id}, GET /v1/inventory-counts/{inventory_count_id}, and GET /v1/inventory-transfers/{inventory_transfer_id}. The reservation route also reads reservations Flint holds for orders and checkout, which are read-only.

  • Breaking change
  • API
  • Locations

Location errors name the field, and country codes must be uppercase#

LOCATION_INVALID and LOCATION_GEOGRAPHY_INVALID errors now set param to the field at fault, such as address.country, timezone, or metadata, and the message says what to send. Before, most of them said only that the request was invalid.

Breaking: address.country must be an uppercase ISO 3166-1 alpha-2 code, such as US. A lowercase code or one with surrounding spaces returns 400 LOCATION_GEOGRAPHY_INVALID instead of being corrected.

Breaking: Location metadata uses the same limits as other resources, checked after a PATCH is merged into the stored keys. A violation returns 400 LOCATION_INVALID with param: metadata.

coordinate.latitude and coordinate.longitude are always returned, including when the value is 0.

  • Breaking change
  • API
  • Orders
  • Invoices

Manual discount scope must match discount_class#

Breaking: manual discounts that explicitly send scope: order with discount_class: line_item, or scope: line_item with discount_class: order, now return 400 INVALID_DISCOUNT_SCOPE. Previously, Flint accepted these conflicting pairs and let discount_class win.

This applies when creating an order, applying a discount, previewing a discount, or creating an invoice with quick_pay.discounts. The error's param identifies the manual discount's scope field in the request. Omit scope and send discount_class.

Matching pairs, requests that send only one field, and scope: order with discount_class: service_charge keep their existing behavior. scope: line_item with discount_class: service_charge still returns SERVICE_CHARGE_DISCOUNT_SCOPE_INVALID.

  • Breaking change
  • API
  • Payouts
  • Webhooks

Analytics stays in one currency, and payouts and balances match their webhooks#

Breaking: these analytics, money movement, report, and Flint billing changes apply now.

Analytics#

  • Overview and payment volume amounts are always in one currency, returned as currency. Omit the currency query parameter to get your account's default currency. Before, an omitted currency added every currency together.
  • active_subscriptions on the overview is replaced by new_subscriptions: subscriptions created in the window that are now trialing, active, paused, or past_due.
  • Payment volume buckets rename period_start and period_end to period_start_at and period_end_at.
  • An invalid timezone returns 400 INVALID_TIMEZONE, and an unsupported query parameter returns 400 UNSUPPORTED_QUERY_PARAM. range accepts and returns last_90_days.
  • currencies and the subscription analytics money lists are [] when empty instead of missing.

Payouts and balances#

  • Payout.arrival_at is now arrival_date, a calendar date such as 2026-10-17, on REST responses, expanded payouts, and payout webhooks.
  • Payout entries rename amount_money to net_money, the entry's effect after fees.
  • Payout webhooks and the API share one set of values. fee_amount_status is estimated, final, or not_applicable, never unknown. method can be standard, instant, or other. initiated_by, payout settings interval, payout destination type, and balance transaction type can be other for a value Flint doesn't map.
  • balance.updated carries the same Balance object as GET /v1/balances and no longer includes instant payout fields. Balances add observed_at, and the list response documents next_page_token.
  • POST /v1/payouts/{payout_id}/cancel for a payout that doesn't exist returns 404 PAYOUT_NOT_FOUND instead of 409. PAYOUT_NOT_CANCELABLE includes error.current_status.
  • Payout settings created_at and updated_at are null when Flint has no stored settings, instead of the request time. payout_settings_id differs between environments.
  • available_by_source_type now adds up to available_money after active payout holds.

Reports and Flint billing#

  • gift_card_liability_v1 with a currency other than USD returns 400 REPORT_CURRENCY_NOT_SUPPORTED instead of INVALID_CURRENCY. Malformed report request bodies return the standard JSON body errors.
  • Merchant subscription invoices rename period_start and period_end to period_start_at and period_end_at, including in invoice webhooks.
  • A malformed or unknown ID returns 404 MERCHANT_SUBSCRIPTION_INVOICE_NOT_FOUND or 404 MERCHANT_BILLING_BALANCE_NOT_FOUND, instead of 400 INVALID_RESOURCE_ID or 404 RESOURCE_NOT_FOUND.
  • Breaking change
  • API
  • Orders

Order field renames, revision checks, and null handling#

Superseded by Create order payments through the payment intents collection.

Breaking: these order changes rename fields and tighten validation.

  • The order's close note is now closed_reason_message, matching the reason_message you send to POST /v1/orders/{order_id}/close. closed_reason is no longer returned on orders.
  • GET /v1/orders/{order_id}/activities filters with activity_type instead of type, matching the field on each activity. An empty entry such as activity_type=payment,,refund returns 400 INVALID_ACTIVITY_TYPE.
  • GET /v1/orders sorts by order total with sort_by=total_money instead of sort_by=total. The status filter accepts repeated or comma-separated values, like the other status filters.
  • DELETE /v1/orders/{order_id}/gift-cards/{gift_card_id} takes order_revision as a required query parameter and no longer accepts a body.
  • On PATCH /v1/orders/{order_id}, null clears buyer_note, internal_note, and external_reference_id, and returns 400 NULL_NOT_ALLOWED on fields that can't be cleared, such as customer_id. Line item and charge updates follow the same rule: null clears description and metadata and is rejected on other fields. Previously, null on these fields was ignored.
  • An order's payment_status now follows the same rule as the payment_status filter: an order is paid once its collection completes.
  • reason_message on close is limited to 500 characters (400 INVALID_ORDER_CLOSE_REASON), and buyer_note and internal_note count their 1,000-character limit in characters.
  • Writing or deleting a metadata key Flint reserves for order bookkeeping returns 400 RESERVED_METADATA_KEY, which names the key. metadata: null now clears your keys and keeps Flint's instead of failing.
  • Order responses always include their arrays, as [] when empty, and gift_card_tender_enabled as false.

These changes need no action unless you use one of them:

  • A request that changes only metadata, buyer_note, internal_note, or external_reference_id now works on closed and paid orders, and on orders with an invoice, and no longer ends an open checkout session. It still returns 409 while a payment is in progress.
  • order_revision is accepted on line item adds and removals, charge writes, discount apply, remove, and reprice, and close, in the body or as a query parameter on DELETE. A stale revision returns 409 ORDER_CHANGED_REFRESH_REQUIRED. It is now optional when selecting a gift card.
  • POST /v1/orders/{order_id}/close accepts an empty body.
  • ORDER_CLOSED errors include the order's current_status.
  • Sending both payment_source_selection and payment_options to POST /v1/orders/{order_id}/payment-intents returns 400 PAYMENT_SOURCE_SELECTION_CONFLICT, as documented.
  • Breaking change
  • API
  • Payments
  • Refunds

Payment intent, payment method, and refund request fixes#

Superseded by Create order payments through the payment intents collection.

Breaking: payment intents no longer include settlement_status. Read refund_status and dispute_status instead.

Breaking: DELETE /v1/payment-methods/{payment_method_id} returns the removed payment method, with status: "removed", instead of {"success": true}. Removing a payment method that is already removed returns it again.

Breaking: an explicit empty string is rejected for capture_method when creating a payment intent with POST /v1/payment-intents or POST /v1/orders/{order_id}/payment-intents, refund_method when creating a refund, and type when saving a payment method. Leave the field out to use its default. capture_method is no longer trimmed on either route, so " manual " returns INVALID_CAPTURE_METHOD.

PATCH /v1/payment-intents/{payment_intent_id} accepts null to clear tip_money, external_reference_id, and receipt_email. customer_id and amount_money can't be cleared and return NULL_NOT_ALLOWED.

receipt_email must be a valid email address on create and update, or the request returns INVALID_EMAIL_FORMAT.

Metadata limits on payment intent and refund updates are checked against the metadata after the update, not only the keys you send.

POST /v1/payment-intents/{payment_intent_id}/confirm accepts an empty body, or {}, to continue with the payment source already attached. An empty string in payment_source_token, payment_method_id, or confirmation_token returns 400. null in any of those fields, or a null body, returns NULL_NOT_ALLOWED.

If a payment needs buyer authentication but Flint can't produce its client action yet, confirm and GET now return the payment intent with current_payment_action: null instead of 500 PAYMENT_CLIENT_ACTION_UNAVAILABLE. Retrieve the payment intent again to get the action.

GET /v1/refunds rejects empty and unknown values in reason, like other multi-value filters.

  • Breaking change
  • API
  • Promotions

Promotion updates change only the subfields you send#

Superseded by Promotion codes, gift card loads, and buyer transactions use top-level routes.

Breaking: PATCH /v1/promotions/{promotion_id} now updates application_method, schedule, and exclusivity by subfield. Subfields you leave out keep their current value. Before, sending any of these objects replaced it, so sending only amount_off_money reset allocation to the class default, and sending only schedule.ends_at removed starts_at and started a scheduled promotion early.

  • To change a promotion's effect, send application_method.type with the new effect's fields. discounted_item_rules carries over unless you send new rules or null. Sending another effect's field without type returns 400 INVALID_APPLICATION_METHOD.
  • null clears optional subfields, such as schedule.starts_at, exclusivity.priority, and application_method.discounted_item_rules. null on a required field returns 400 NULL_NOT_ALLOWED, and an empty application_method, schedule, or exclusivity object returns 400 FIELD_REQUIRED.
  • PATCH on an archived promotion returns 409 PROMOTION_ARCHIVED with current_status: archived. Before, it returned 404.

GET /v1/promotions/{promotion_id}/codes/{promotion_code_id} returns one promotion code. A deleted code, including the codes of an archived promotion, returns 404.

See updating a promotion for the full rules.

  • API
  • Orders
  • Promotions

Promotion removal warnings reflect the returned order#

Applying a manual discount or promotion with POST /v1/orders/{order_id}/discounts no longer returns a promotion_removed warning for an automatic promotion that is still pending on the returned order.

  • Breaking change
  • API
  • Returns
  • Credit-notes

Returns and credit note errors, fences, and a preview rename#

Breaking: these Returns and credit note changes rename a field and change error codes and statuses.

  • Return resolution previews return based_on_return_version instead of based_on_return_revision.
  • A buyer request on a customer session that sets a field only you can set, such as external_reference_id, metadata, or a preview's pricing_basis, returns 400 RETURN_FIELD_NOT_ALLOWED_FOR_BUYER with param naming the field. A request the return policy doesn't open to self-service returns 409 RETURN_SELF_SERVICE_NOT_ALLOWED. Both replace 403 RETURN_DECISION_SCOPE_REQUIRED.
  • Returns validation errors carry param with the field path, such as line_items[0].requested_quantity, and messages no longer start with "return request validation failed" or "return request conflicts with current state". null on a field that can't be cleared returns NULL_NOT_ALLOWED, an unknown field returns UNKNOWN_FIELD, an unsupported enum value returns INVALID_ENUM_VALUE with the accepted values, a bad expected_version returns INVALID_EXPECTED_VERSION, and a bad timestamp filter returns INVALID_TIMESTAMP.
  • PATCH /v1/return-policies/{return_policy_id} and PATCH /v1/return-reasons/{return_reason_id} on an archived policy or reason return 409 RETURN_ACTION_NOT_ALLOWED with current_status: archived. Previously a name or metadata change was applied.
  • Retrying a resolution whose Return line was canceled or is otherwise no longer approved returns 409 RETURN_ACTION_NOT_ALLOWED with the line's current_status. An approved line without enough quantity left still returns 409 RETURN_VALUE_EXCEEDED.
  • POST /v1/return-resolutions/{return_resolution_id}/checkout-session and its /v1/me route return 200 when they return the open checkout session again (reused_existing: true), and 201 only when they create one.
  • Credit note reason and the status filter match exactly: Goodwill or goodwill returns INVALID_CREDIT_NOTE_REASON. reason: null returns 400 NULL_NOT_ALLOWED.
  • Credit note line errors are specific: CREDIT_NOTE_INVOICE_LINE_NOT_FOUND for a line that isn't on the invoice, CREDIT_NOTE_CURRENCY_MISMATCH for an amount in another currency, and CREDIT_NOTE_LINE_EXCEEDS_INVOICE_LINE for a correction above the source line, each with param naming the field.

These changes need no action unless you use one of them:

  • PATCH /v1/returns/{return_id} accepts expected_version, and DELETE /v1/returns/{return_id}/line-items/{return_line_item_id} accepts it as a query parameter. Receipt line verification and inspection line decisions compare expected_version with the parent Return's version, and their 409 RETURN_VERSION_CONFLICT includes the Return's current version.
  • RETURN_ACTION_NOT_ALLOWED, CREDIT_NOTE_NOT_DRAFT, and CREDIT_NOTE_NOT_ISSUED include the blocking resource's current_status, and the credit note messages say which operation the status blocks.
  • Return policy supported_actions now lists activate, deactivate, and archive, and Return reason supported_actions lists archive, when your key can take them. Every Returns supported_actions array publishes its values in the OpenAPI spec.
  • Each Returns operation's x-flint-error-codes lists the codes it can return, including RETURN_NOT_FOUND in place of RESOURCE_NOT_FOUND.
  • Breaking change
  • API
  • Orders
  • Promotions

Archived promotions use the disabled decline reason#

Breaking: applying an archived promotion with POST /v1/orders/{order_id}/discounts, or sending one in discounts on POST /v1/orders or in quick_pay.discounts on POST /v1/invoices, now returns 409 PROMOTION_DECLINED with reason: disabled and current_status: archived. Before, these requests returned PROMOTION_NOT_REDEEMABLE.

PROMOTION_NO_ACTIVE_CODES is retired; no request returns it.

Money thresholds now decline with structured reasons on every money attribute. An unmet order.merchandise_subtotal_before_discounts minimum returns minimum_not_met with required_money, current_money, and gap_money, the same as order.subtotal. A money threshold with no amount for the order's currency returns currency_mismatch for every money attribute. Before, both returned not_eligible.

  • Breaking change
  • API
  • Catalog
  • Checkout
  • Subscriptions

Catalog, checkout, subscription, and account state conflicts return 409#

Requests that are valid on their own but blocked by current catalog, payment link, checkout, subscription, or account state return 409 conflict_error. Lifecycle conflicts include error.current_status when the blocking resource has a public status, using that status value. Request shape and immutable reference mismatches continue to return 400 validation_error.

The following codes move their remaining 400 responses to 409:

  • ACTIVE_BUNDLE_COMPONENTS_IMMUTABLE
  • ACTIVE_OPTION_SELECTOR_COLLAPSE
  • ACTIVE_VARIANTS_REQUIRE_OPTION_BACKFILL
  • AMOUNT_NOT_ADJUSTABLE
  • API_KEY_ALREADY_REVOKED
  • BUNDLE_COMPONENT_PRODUCT_NOT_ACTIVE
  • BUNDLE_COMPONENT_VARIANT_NOT_ACTIVE
  • BUNDLE_IN_ACTIVE_PAYMENT_LINK
  • BUNDLE_IN_ACTIVE_SUBSCRIPTION
  • BUNDLE_IN_ACTIVE_SUBSCRIPTION_PLAN
  • BUNDLE_IN_OPEN_CHECKOUT_SESSION
  • BUNDLE_IN_OPEN_INVOICE_PAYMENT_ATTEMPT
  • BUNDLE_IN_OPEN_ORDER
  • BUNDLE_NOT_SELLABLE
  • CAPABILITIES_IMMUTABLE
  • CATALOG_INVENTORY_RELATIONSHIP_INVALID
  • CHECKOUT_CREDENTIAL_CHANGED
  • CHECKOUT_CUSTOMER_NOT_SET_ON_ORDER
  • CHECKOUT_SESSION_NOT_OPEN
  • COUNTRY_IMMUTABLE
  • CUSTOMER_VERIFICATION_NOT_CONFIRMED
  • CUSTOMER_VERIFICATION_NOT_OFFERED
  • CUSTOM_DOMAIN_NOT_VERIFIED
  • DEFAULT_ENVIRONMENT_REQUIRED
  • IMAGE_ASSET_NOT_ATTACHABLE
  • INVENTORY_ITEM_INACTIVE
  • MERCHANT_ACCOUNT_DOMAIN_NOT_VERIFIED
  • MERCHANT_ACCOUNT_SESSION_TARGETED_REMEDIATION_UNAVAILABLE
  • MERCHANT_ACCOUNT_SESSION_UNMAPPABLE_REQUIREMENT_ID
  • ORGANIZATION_CYCLE
  • PAYMENT_METHOD_NOT_READY
  • PLAN_NOT_ACTIVE
  • QUANTITY_NOT_ADJUSTABLE
  • RULE_LIMIT_EXCEEDED
  • SUBSCRIPTION_DELIVERY_LINES_NOT_COMBINABLE
  • SUBSCRIPTION_DELIVERY_PROFILE_ACTION_REQUIRED
  • SUBSCRIPTION_DELIVERY_PROFILE_MISSING
  • SUBSCRIPTION_DELIVERY_UNAVAILABLE
  • SUBSCRIPTION_NEXT_BILLING_AT_BEFORE_PERIOD_START
  • SUBSCRIPTION_NEXT_BILLING_AT_TOO_FAR
  • SUBSCRIPTION_OFFER_PROMOTION_UNAVAILABLE
  • VARIANT_IN_ACTIVE_BUNDLE
  • VARIANT_IN_ACTIVE_PAYMENT_LINK
  • VARIANT_IN_ACTIVE_SUBSCRIPTION
  • VARIANT_IN_ACTIVE_SUBSCRIPTION_PLAN
  • VARIANT_IN_OPEN_CHECKOUT_SESSION
  • VARIANT_IN_OPEN_INVOICE_PAYMENT_ATTEMPT
  • VARIANT_IN_OPEN_ORDER
  • VARIANT_NOT_SELLABLE

Deleted organization references now return 409 ORGANIZATION_NOT_ACTIVE with current_status: deleted. Updating a revoked API key returns 409 API_KEY_ALREADY_REVOKED with current_status: revoked; authentication continues to return 401 API_KEY_REVOKED.

Risk predicates exceeding 100 nodes or 10 nesting levels return 400 INVALID_PREDICATE; exceeding the enabled rule count remains 409 RULE_LIMIT_EXCEEDED. Blank targeted requirement IDs return 400 VALUE_REQUIRED with the indexed targeted_requirement_ids parameter. A merchant with no default live environment returns 409 DEFAULT_ENVIRONMENT_REQUIRED.

  • Breaking change
  • API
  • Orders
  • Tax

A charge's tax category decides its automatic tax#

Automatic tax now decides whether it can calculate a taxable order charge from the charge's tax.charge_tax_category, not its type. Charges in shipping or delivery are taxed at the general rate where the order goes, whatever their type, so an other charge or a paid pickup in the delivery category is taxed. type still describes what the fee is for.

A charge that leaves out charge_tax_category takes it from type: delivery_fee is delivery, shipping_fee is shipping, service_fee is service_fee, and handling_fee is handling. Other types take no category. The default isn't stored, so responses still omit the field and the category follows a later change to type. Existing shipping and delivery fees without a category keep their tax.

Breaking: a taxable charge whose category is not shipping or delivery, such as a delivery_fee with charge_tax_category: "service_fee" or a shipping_fee in handling, now fails with 400 AUTOMATIC_TAX_CHARGE_UNSUPPORTED instead of 400 INVALID_TAX_CATEGORY. When the order's tax location is known, the request that adds or changes the charge fails. param, or remediation.missing_or_invalid_fields for a charge already on the order, names tax.charge_tax_category when you set the category or the charge has none, and type when the category came from the type. Changing charge_tax_category, or changing type on a charge without one, recalculates the charge's tax.

  • API
  • Orders
  • Promotions

Merchant credentials can apply code-gated promotions by ID#

Merchant credentials can now use promotion_id to apply a code-gated promotion through POST /v1/orders, POST /v1/orders/{id}/discounts, and POST /v1/discount-previews. Promotions with active or no_active_codes status are accepted.

An applied discount records promotion_id, omits promotion_code and promotion_code_id, and counts only toward the promotion's max_uses. Promotion availability and the merchant's codes_enabled setting continue to apply. Checkout credentials must use promotion_code.

  • API
  • Discounts

Discount errors name the field you sent#

  • Apply a discount. POST /v1/orders/{id}/discounts returns param such as promotion.promotion_code, promotion.promotion_id, promotion, or manual.amount_money.currency.
  • Preview a discount. POST /v1/discount-previews keeps the discount wrapper: discount.promotion.promotion_code, discount.promotion.promotion_id, discount.promotion, and discount.manual.
  • Create an order. POST /v1/orders includes the discount's array index, such as discounts[1].promotion.promotion_code, discounts[1].promotion.promotion_id, or discounts[0].promotion.
  • Invoice discount validation. POST /v1/invoices includes the array index for quick-pay discount validation, such as quick_pay.discounts[1].promotion.promotion_id or quick_pay.discounts[1].promotion.
  • Policy errors keep their existing params, such as promotion_config.codes_enabled.
  • Promotion warnings. A promotion applied by ID that was accepted but did not apply returns the message Promotion was accepted but did not apply. Promotions applied by code keep Promotion code was accepted but did not apply.
  • API
  • Orders
  • Promotions
  • Checkout

Exhausted promotions are removed before payment#

Promotions and promotion codes that reach their max_uses are now removed from unpaid orders when the order changes, is repriced, or starts payment. When POST /v1/orders/{order_id}/pay removes a discount, it saves the updated order and returns 409 ORDER_CHANGED_REFRESH_REQUIRED with param: applied_discounts and the new outstanding amount. No payment starts. Read the order and review the updated total before paying with a new idempotency key.

Partly paid orders, invoice orders, subscription renewals, and resumed or retried payment attempts keep their discounts. A discount also keeps its use when this order already has a reserved or redeemed redemption for it.

If another buyer takes the last use while payment is starting, pay still returns 409 PROMOTION_NOT_REDEEMABLE with current_status and keeps the discount. The error includes reason: exhausted. Retry with a new idempotency key to remove the discount and receive ORDER_CHANGED_REFRESH_REQUIRED.

PROMOTION_NOT_REDEEMABLE is retryable only with reason exhausted; invoice, partly paid, and renewal payments honor discounts at max_uses.

  • Breaking change
  • API
  • Webhooks

Idempotency replays include metadata and keys come from callers#

Every successful idempotency replay sets Idempotency-Replayed: true and meta.idempotency_replayed: true. The Idempotency-Key response header only echoes a key you sent. A webhook's request.idempotency_key is present only when the originating request sent a key. Send your own key before the first attempt to retry a write safely.

Flint trims surrounding whitespace from keys on every route. A key longer than 255 characters or containing null characters or line breaks returns 400 INVALID_IDEMPOTENCY_KEY with param: Idempotency-Key. Routes that require a key continue to return 400 IDEMPOTENCY_KEY_REQUIRED when it is missing.

Breaking: payment link resolution and report creation previously returned IDEMPOTENCY_KEY_TOO_LONG for oversized keys. Key validation errors now name the Idempotency-Key header in param. Responses no longer return a generated key when you omit one, and request.idempotency_key is optional in webhook envelopes.

  • Breaking change
  • API
  • Invoices
  • Payments

Invoice installments carry the tip first#

An invoice collection smaller than the invoice's balance, such as a scheduled installment, now carries the order's unpaid tip first, up to its amount, and puts the rest toward items and charges. A 250 deposit on an invoice with a 300 tip carries 250 of the tip in its payment intent's tip_money, and the next installment carries the other 50. A collection of the whole balance still carries the whole unpaid tip. Schedule entry amounts and the invoice total are unchanged. Partial payments of an order, outside an invoice, still pay for items and charges first.

Previously the first installment had to carry the whole tip, and collecting a deposit smaller than the tip failed with 400 TIP_ALLOCATION_CAPACITY_EXCEEDED.

A credit note allocation must now leave the order's unpaid tip outstanding on the invoice, because a credit lowers the balance but not the tip. Otherwise it returns 409 CREDIT_NOTE_ALLOCATION_EXCEEDS_BALANCE with the tip in required_money, what the allocation would leave in current_money, and the difference in gap_money. Allocate up to that limit, collect the remaining balance, which carries the tip, then refund the rest of the credit note once the invoice is paid.

TIP_ALLOCATION_CAPACITY_EXCEEDED is now a 409 conflict_error with retryable: false, declared on POST /v1/orders/{order_id}/pay and POST /v1/invoices/{invoice_id}/collect. It means the balance left to collect is smaller than the unpaid tip, which happens when a manual payment covered part of the tip without recording it. submitted_money is the unpaid tip and tip_capable_money is the balance left to collect. Contact support with the request ID.

Breaking: handlers that matched 400 TIP_ALLOCATION_CAPACITY_EXCEEDED should match 409, and credit allocations that leave less than the unpaid tip now fail.

  • Breaking change
  • API
  • Invoices

Invoice lists use cursor page tokens#

GET /v1/invoices, GET /v1/me/invoices, and GET /v1/invoices/{invoice_id}/delivery-attempts now return opaque cursor page tokens. Each token records the last row's sort value and ID, so inserting newer rows, changing the last row, or deleting it does not move the next page's starting position.

Breaking: numeric offset tokens no longer work. Invalid tokens, including tokens reused with different filters or ordering, return 400 INVALID_PAGE_TOKEN with param: "page_token". Restart from the first page without page_token, then pass each next_page_token back unchanged.

Invoices without an invoice number now sort last when sort_by=invoice_number&sort_direction=asc; they also sort last descending. Invoices without a due date continue to sort last in both directions. Invoice IDs break ties in the selected sort direction. Delivery attempts sort by created_at descending, then delivery attempt ID descending.

Rows whose sort values change during traversal may appear again on a later page or be missed. See Pagination for traversal and restart guidance.

  • API
  • Orders
  • Promotions

Order create resolves requested promotions together#

POST /v1/orders ranks all requested promotion codes together with the order's automatic promotions. The result no longer depends on the order of discounts[].

A code whose discountable balance another requested code fully consumed now returns a promotion_declined warning in meta.warnings[] on the 201 response instead of a 400 error.

A manual discount in the same request is no longer reduced by promotion codes. Manual discounts apply first, in request order. A code with no balance left after the request's manual discounts returns 400 with reason no_discountable_balance, wherever it appears in discounts[].

  • Breaking change
  • API
  • Orders

Orders report the requested tip only in tips#

Orders in API responses, including order payment results and checkout delivery selection results, no longer include requested_tip. Order webhooks never carried it. It repeated the entry in tips[] whose status is requested, which carries the same percent or amount_money, name, description, and metadata, plus its order_tip_id and resolved effective_amount_money.

Breaking: read the requested tip from the tips[] entry with status: "requested". requested_tip stays a request field on POST /v1/orders, PATCH /v1/orders/{order_id}, and invoice quick pay, and invoice snapshots keep their own requested_tip.

  • Breaking change
  • API
  • Orders

Order totals failures return 500 ORDER_TOTALS_UNAVAILABLE#

Order writes no longer return 400 INVALID_TOTALS or 400 INVALID_LINE_ITEMS with internal calculation text in message. A totals calculation failure indicates a Flint bug, not amounts you can change, so it returns 500 ORDER_TOTALS_UNAVAILABLE with retryable: false. Contact support with the request ID.

Removing the last taxable line item or charge from an external-tax order with an order-level flat fee, such as retail_delivery_fee, now succeeds and drops the fee. It previously failed with 400 INVALID_TOTALS when only gift card lines remained.

Breaking: these failures previously returned 400 validation_error. Update handlers that match INVALID_TOTALS or INVALID_LINE_ITEMS.

  • Breaking change
  • API
  • Orders
  • Delivery
  • Returns
  • Promotions

Order, delivery, and promotion state conflicts return 409#

Valid requests blocked by mutable order, delivery, or promotion state now return 409 conflict_error. Lifecycle conflicts include error.current_status with the public resource status. Retry guidance remains unchanged.

The following codes move from 400 to 409:

  • DEVICE_DELETED
  • ORDER_ALREADY_CLOSED
  • ORDER_HAS_NO_LINE_ITEMS
  • ORDER_INVENTORY_EXCEPTION_NOT_RESOLVABLE
  • ORDER_INVENTORY_EXCEPTION_UNRESOLVED
  • ORDER_PAYMENT_AUTHORIZATION_NOT_FOUND
  • ORDER_RECEIPT_NOT_AVAILABLE
  • ORDER_STATUS_NOT_CLOSABLE
  • NO_PAYMENTS_FOR_ORDER
  • SETUP_SOURCE_NON_ZERO_ORDER
  • LOCATION_UNAVAILABLE
  • PROMOTION_NO_ACTIVE_CODES
  • PROMOTION_NOT_REDEEMABLE
  • EXTERNAL_PAID_ORDER_ALLOWANCE_EXHAUSTED
  • GIFT_CARD_CHALLENGE_REQUIRED
  • GIFT_CARD_PURCHASE_LIMIT_EXCEEDED
  • NO_DISCOUNTABLE_BALANCE
  • ORDER_RECEIPT_RECIPIENT_LIMIT_REACHED
  • ORDER_TOTAL_BELOW_NET_COLLECTED
  • INVENTORY_RESERVATION_EXISTS
  • ORDER_CUSTOMER_ALREADY_SET
  • ORDER_CUSTOMER_NOT_UPDATABLE_AFTER_PAYMENT
  • ORDER_RECEIPT_EMAIL_ON_FILE
  • ORDER_TAX_NOT_UPDATABLE_AFTER_PAYMENT
  • PAID_LINE_ITEM_MODIFIER_CHANGE_FORBIDDEN
  • PAID_LINE_ITEM_PRICE_CHANGE_FORBIDDEN
  • PAID_LINE_ITEM_QUANTITY_CHANGE_FORBIDDEN
  • PAID_LINE_ITEM_QUANTITY_DECREASE_FORBIDDEN
  • PAID_LINE_ITEM_REMOVAL_FORBIDDEN
  • PAID_LINE_ITEM_TAX_CHANGE_FORBIDDEN
  • AUTOMATIC_PROMOTIONS_DISABLED
  • PROMOTION_CODES_DISABLED
  • AUTOMATIC_TAX_CONNECTION_REQUIRED
  • AUTOMATIC_TAX_ORIGIN_ADDRESS_REQUIRED
  • CATALOG_LINE_ITEM_CURRENCY_CHANGED
  • CATALOG_LINE_ITEM_SOURCE_CHANGED
  • DEVICE_LOCATION_MISMATCH
  • ORDER_RECEIPT_EMAIL_UNAVAILABLE
  • ORDER_RECEIPT_MERCHANT_MANAGED
  • FULFILLMENT_APPROVAL_REQUIRED
  • FULFILLMENT_COMPLETION_TIMESTAMP_REQUIRES_COMPLETE
  • FULFILLMENT_INACTIVE
  • FULFILLMENT_METHOD_UNAVAILABLE
  • FULFILLMENT_PROFILE_UNAVAILABLE
  • FULFILLMENT_SELECTION_REQUIRED
  • FULFILLMENT_SHIPMENT_NOT_MUTABLE
  • FULFILLMENT_SHIPMENT_NOT_VOIDABLE
  • FULFILLMENT_SHIPMENT_TERMINAL
  • FULFILLMENT_TERMINAL
  • ORDER_NOT_FULFILLABLE
  • SHIPMENT_PACKAGE_NOT_MUTABLE
  • SHIPMENT_PACKAGE_NOT_VOIDABLE
  • SHIPMENT_PACKAGE_TERMINAL
  • FULFILLMENT_QUANTITY_EXCEEDS_AVAILABLE
  • SHIPMENT_PACKAGE_ITEM_QUANTITY_EXCEEDS_FULFILLMENT
  • FULFILLMENT_ACTIVE_SHIPMENT_EXECUTION
  • FULFILLMENT_QUANTITY_EXCEEDS_LINE_ITEM
  • FULFILLMENT_COMPLETED
  • FULFILLMENT_COMPLETED_DETAILS_REPLACEMENT
  • FULFILLMENT_CONFIGURATION_ACTION_REQUIRED
  • FULFILLMENT_METHOD_ASSIGNMENT_UNSATISFIABLE
  • FULFILLMENT_PROFILE_REVISION_UNUSABLE

NO_DISCOUNTABLE_BALANCE stays 400 when creating an order because the balance comes from the request. Applying a discount to an existing order returns 409.

Return shipment requests now distinguish their failures:

  • Invalid line allocations return 400 RETURN_SHIPMENT_INVALID.
  • An undecided, canceled, or completed return returns 409 RETURN_ACTION_NOT_ALLOWED, with the return's current_status and param: return_id.
  • Exhausted shipment quantity returns the new 409 RETURN_SHIPMENT_QUANTITY_EXCEEDS_AVAILABLE.
  • A missing return returns 404 RETURN_NOT_FOUND.
  • An unexpected validation failure returns 500.

Requesting refund line items on an empty order now returns 400 LINE_ITEM_NOT_ON_ORDER. A missing delivery profile returns 404 RESOURCE_NOT_FOUND; an inactive profile or one without a current configuration returns 409 FULFILLMENT_PROFILE_UNAVAILABLE. Completion timestamps on fulfillment creation return 400 FULFILLMENT_COMPLETION_TIMESTAMP_NOT_ALLOWED; adding them to an incomplete fulfillment returns 409 FULFILLMENT_COMPLETION_TIMESTAMP_REQUIRES_COMPLETE.

Breaking: these conditions previously returned 400 with type: validation_error, or combined distinct causes under the same error code. Handle the statuses and codes listed above when recovering from a failed request.

  • Breaking change
  • API
  • Payments
  • Orders
  • Checkout
  • Errors

Payments in progress return 409 PAYMENT_IN_PROGRESS#

A request that a payment in flight blocks now returns 409 PAYMENT_IN_PROGRESS with retryable: true, whether a checkout session, an invoice, an order payment attempt, or a linked payment intent holds the order. error.blocking_resources names the blocking resource when Flint knows it and your credential may see it. Wait for it to finish, read the order or checkout session, then retry.

PAYMENT_IN_PROGRESS replaces these codes on every operation that returned them:

  • CHECKOUT_PAYMENT_RESOLVING
  • PAYMENT_ATTEMPT_IN_PROGRESS
  • PAYMENT_ATTEMPT_STILL_PROCESSING
  • PAYMENT_ATTEMPT_FROZEN

PAYMENT_ATTEMPT_REQUIRES_CAPTURE is unchanged and still means an authorized payment waits for you to capture or cancel it.

Breaking: update handlers that match any of the four replaced codes to match PAYMENT_IN_PROGRESS.

  • Breaking change
  • API
  • Payments

Creating a payment intent returns it flat in data#

POST /v1/payment-intents returns the payment intent flat in data, with data.payment_intent_id beside required data.payment_collection guidance. GET uses the same shape with optional collection guidance.

Breaking: standalone create previously nested the intent in data.payment_intent. Order-scoped create continues to return the order payment intent and collection guidance as separate resources.

If Flint can't verify a payment intent's fee, the response succeeds and omits processing_fee_money, add_on_fees, and merchant_net_money. Read the payment intent again later for verified fees.

Confirm and GET return 500 PAYMENT_CLIENT_ACTION_UNAVAILABLE if a payment needs buyer authentication but Flint cannot produce its client action. Contact support with the request ID. A same-key confirm retry returns the stored error again.

  • Breaking change
  • API
  • Payments

Payment intent tips are validated#

tip_money on a standalone payment intent reports the portion of amount_money that is a tip. It is included in the payment amount. Its amount must be at least 1 minor unit, its currency must exactly match amount_money.currency, and it must not exceed amount_money.amount. A tip equal to the payment amount is allowed. Omit tip_money when there is no tip. Order-linked payment intents do not accept it.

Breaking: creating or updating a payment intent with an invalid tip now returns 400 INVALID_TIP_AMOUNT for amounts below 1, 400 TIP_CURRENCY_MISMATCH for a different currency, or 400 TIP_EXCEEDS_AMOUNT for a tip larger than the payment amount. The error's param is tip_money.amount or tip_money.currency. When only amount_money changes, Flint rechecks the stored tip and sets param to amount_money.amount if the new amount is below that tip. When both fields change, Flint validates the new tip against the new amount.

  • API
  • Payments
  • Webhooks

payment_intent events carry the full payment intent#

payment_intent.canceled, payment_intent.payment_failed, payment_intent.requires_action, payment_intent.requires_capture, payment_intent.processing, and payment_intent.succeeded now carry the full payment intent in data.payment_intent, using the same public fields and values as the REST response. payment_intent.payment_failed includes last_payment_error. Status, amounts, and capture fields come from the transition; risk, fulfillment_hold, and last_payment_error are read once when Flint prepares the event, usually seconds later, and retries resend the same payload.

The snapshot omits current_payment_action, fee fields (processing_fee_money, add_on_fees, and merchant_net_money), and expanded customer, order, and invoice objects. Webhooks carry no client authority. Read fees from GET /v1/payment-intents/{payment_intent_id} or balance_transaction.created. cancellation_reason uses the REST cancellation reason values.

payment_intent.fulfillment_hold.updated keeps its existing payload shape.

  • Breaking change
  • API
  • Payments
  • Refunds
  • Invoices

Payment, refund, and invoice state conflicts return 409#

Requests that fail because of mutable payment or refund state, remaining capacity, or invoice configuration now return 409 conflict_error. Lifecycle conflicts include error.current_status with the blocking resource's public status. Error messages use public names.

The following codes now use 409 on every operation that returns them:

  • PAYMENT_ALREADY_SUCCEEDED
  • PAYMENT_CANCELED
  • PAYMENT_EXPIRED
  • PAYMENT_INTENT_CANNOT_BE_UPDATED
  • INVALID_STATUS_FOR_CAPTURE
  • CANNOT_CANCEL_SUCCEEDED_PAYMENT
  • PAYMENT_ALREADY_CANCELED
  • CANNOT_CANCEL_EXPIRED_PAYMENT
  • ORDER_NOT_PAYABLE
  • CONFIRMATION_TOKEN_EXPIRED
  • PAYMENT_AUTHORIZATION_NOT_CAPTURABLE
  • PAYMENT_AUTHORIZATION_EXPIRED
  • CONFIRMATION_TOKEN_ALREADY_USED
  • CAPTURE_AMOUNT_EXCEEDS_CAPTURABLE
  • PAYMENT_INTENT_LIMIT_REACHED
  • PAYMENT_NOT_REQUIRED
  • PAYMENT_LEG_SELECTION_REQUIRED
  • PAYMENT_SOURCE_NOT_UPDATABLE
  • CUSTOMER_NOT_UPDATABLE
  • RECEIPT_EMAIL_NOT_UPDATABLE
  • AMOUNT_NOT_UPDATABLE
  • ORDER_PAYMENT_CUSTOMER_MISMATCH
  • PAYMENT_OPTION_NOT_READY
  • PAYMENT_METHOD_REQUIRED
  • PROCESSOR_NOT_CONFIGURED
  • TEST_PROCESSOR_NOT_CONFIGURED
  • UNSUPPORTED_PROCESSOR
  • PROCESSING_FEE_PRICING_NOT_AUTHORIZED
  • RISK_ACTION_NOT_SUPPORTED_FOR_PAYMENT_OPTION
  • RISK_ACTION_NOT_SUPPORTED_FOR_PAYMENT_FLOW
  • SAVE_PAYMENT_METHOD_NOT_OFFERED
  • SAVE_PAYMENT_METHOD_VERIFICATION_REQUIRED
  • ACH_TRANSACTION_PURPOSE_UNRESOLVED
  • PAYMENT_INTENT_NOT_REFUNDABLE
  • PAYMENT_INTENT_DISPUTED
  • REFUND_SUBMISSION_DEADLINE_EXPIRED
  • REFUND_ADJUSTMENT_PAYMENT_INTENT_NOT_REFUNDABLE
  • ORDER_HAS_NO_REFUNDABLE_CHARGES
  • ORDER_HAS_NO_REFUNDABLE_LINE_ITEMS
  • AMOUNT_EXCEEDS_REFUNDABLE
  • CHARGE_REFUND_AMOUNT_EXCEEDS_REFUNDABLE
  • LINE_ITEM_REFUND_AMOUNT_EXCEEDS_REFUNDABLE
  • LINE_ITEM_REFUND_QUANTITY_EXCEEDS_REFUNDABLE
  • NOTHING_TO_REFUND
  • NOTHING_TO_REFUND_FOR_CHARGE
  • NOTHING_TO_REFUND_FOR_LINE_ITEM
  • NOTHING_TO_REFUND_FOR_TAX_BREAKDOWN
  • TAX_BREAKDOWN_REFUND_EXCEEDS_REMAINING
  • REFUND_ADJUSTMENT_REFUND_EXCEEDS_REMAINING
  • REFUND_ADJUSTMENT_REFUND_EXCEEDS_PAYMENT_INTENT_REFUNDABLE
  • FLAT_TAX_PAYMENT_ATTRIBUTION_UNAVAILABLE
  • CUSTOMER_PAYMENT_TERM_UNAVAILABLE
  • INVOICE_PAYMENT_TERM_CURRENCY_MISMATCH
  • INVOICE_AUTOPAY_PAYMENT_METHOD_REQUIRED
  • PAYMENT_OPTION_LIMIT_EXCEEDED

Request-shape failures keep 400 under ORDER_LINKED_AMOUNT_NOT_UPDATABLE, PAYMENT_OPTION_SCOPE_UNSUPPORTED, SAVE_PAYMENT_METHOD_REQUIRES_FULL_PAYMENT, and DUPLICATE_PAYMENT_INTENT_ID. DUPLICATE_PAYMENT_INTENT_ID names the repeated payment_intents[i].payment_intent_id in error.param. An explicitly empty subscription payment_method_id uses 400 INVALID_ID. Paying without any payment legs or payment source uses 400 PAYMENT_SOURCE_REQUIRED. Saving a card without a checkout credential uses 403 CHECKOUT_CREDENTIAL_REQUIRED.

Corrupt stored refund lineage returns 500 FLAT_TAX_REFUND_STATE_INVALID with retryable: false. Contact support with the request ID so Flint can repair the order's refund records.

Breaking: the same state conditions previously returned 400 validation_error. Update handlers that match HTTP 400 or the replaced request-shape codes.

  • API

Promotions without eligibility rules omit `eligibility_rules`#

Promotions without eligibility rules now omit eligibility_rules instead of returning {}. This also applies to promotions created with "eligibility_rules": [] and to empty discounted_item_rules and qualifying_item_rules groups in application_method.

The omitted fields match the published rule-group schema and avoid INVALID_RULE_GROUP when sending a response's rule fields back in an update request.

  • Breaking change
  • API
  • Orders
  • Promotions
  • Errors

Promotion write and discount removal errors name the field you sent#

Superseded by Promotion codes, gift card loads, and buyer transactions use top-level routes.

Breaking: param on these promotion and discount errors now gives the path in the request you sent. If you match on param, update these values.

  • POST /v1/orders names manual discount errors by the discount's position, such as discounts[0].manual.scope, discounts[0].manual.discount_class, or discounts[0].manual.order_charge_ids. Before, they used discounts.manual.scope or discount.manual.order_charge_ids.
  • POST /v1/orders/{order_id}/discounts/remove returns DISCOUNT_IDS_REQUIRED with param: order_discount_ids, and CHECKOUT_DISCOUNT_NOT_REMOVABLE with the refused ID's position, such as order_discount_ids[1]. Before, the first had no param and the second used applied_discount_ids.
  • Rule errors on promotion create and update follow the rule group you sent. A rule in an array is eligibility_rules[1].values[0], and a rule object inside all or any is eligibility_rules.all[1].operator. Before, they used eligibility_rules.rules[1].values[0]. INVALID_RULE_VALUE names the value, such as eligibility_rules[1].values[0], instead of values. UNKNOWN_CATEGORY_HANDLE names the line_item.categories value, instead of category_handles.
  • Errors for an entry in codes on POST /v1/promotions include its position, such as codes[1].max_uses, and DUPLICATE_CODE uses codes. POST /v1/promotions/{promotion_id}/codes uses expires_at and metadata instead of code.expires_at and code.metadata.
  • 404 RESOURCE_NOT_FOUND for a missing promotion or code names it, such as Promotion code pcode_01J... not found. Before, it was Promotion not found for both.
  • INVALID_EXPIRES_AT is listed on promotion create and on promotion code create and update.
  • Breaking change
  • API
  • Orders
  • Promotions

Promotion declines use 409 for promotion state, and displaced promotions are reported#

Breaking: applying promotions to orders changed in these ways.

  • PROMOTION_DECLINED returns 409 conflict_error when the promotion's or code's state blocks it: reason is expired, not_yet_started, exhausted, or disabled, and error.current_status gives the promotion's or code's status. automatic_disabled and codes_disabled stay 409, and no_discountable_balance stays 409 on an existing order and 400 on order creation. Before, the four lifecycle reasons returned 400 validation_error. Every other reason still returns 400.
  • Creating an order with more codes than max_promotions_per_order no longer returns 400 PROMOTION_DECLINED with reason: max_promotions_reached. The order is created with its most valuable promotions, and each code that didn't fit comes back in meta.warnings[] as a promotion_declined warning.
  • When the codes on a new order conflict, such as two codes in one exclusivity group, Flint keeps the winner and returns the loser as a promotion_declined warning. Before, both could stay on the order.
  • Two pending promotions in one exclusivity group, or more pending promotions than max_promotions_per_order, are now resolved whenever the order changes or is repriced, even when you have no active automatic promotions.
  • Applying a discount that removes promotions already on the order returns a promotion_removed warning in meta.warnings[] for each one, with the decline reason, resource_id, promotion_code when a code applied it, and would_have_applied_money for the amount it took off. The order's activity records the same reason. Before, the removal was recorded only in the activity, always as superseded by a better offer.
  • POST /v1/orders/{order_id}/discounts/remove returns 409 DISCOUNT_NOT_REMOVABLE for a discount from an automatic promotion, with param naming its position in order_discount_ids, and changes nothing on the order. Before, the request succeeded and the promotion applied again under a new ID. Make the promotion inactive to stop it applying. Manual and code discounts can still be removed.
  • A repeated ID in order_discount_ids returns 400 DUPLICATE_ORDER_DISCOUNT_ID. Before, it returned 404 DISCOUNT_NOT_FOUND.
  • POST /v1/discount-previews lists promotions already on the order that the previewed code would remove in skipped, with their decline reason.
  • POST /v1/discount-previews reports an archived promotion in skipped with disabled. Before, unknown_type.
  • API
  • Orders
  • Promotions

New promotion decline reason `superseded_by_higher_priority`#

Promotions that lose to a higher exclusivity.priority in a highest_priority group now report superseded_by_higher_priority in preview skipped[] and order warnings. Equal-priority ties and best_of groups continue to report superseded_by_better_offer.

  • Breaking change
  • API
  • Promotions

Promotion rules reject unknown enum values#

Promotion rules on charge.type and delivery_choice.type using eq, ne, or in now reject values outside the published lists with 400 validation_error and code UNKNOWN_RULE_VALUE. Values are case-sensitive. The error message lists all allowed values, also published in OpenAPI's x-flint-rule-attributes extension on PromotionRule.

Existing promotions keep working until those rule groups are replaced. Updating eligibility_rules validates the replacement eligibility rules. Updating application_method validates its replacement discounted_item_rules and qualifying_item_rules. Unrelated edits leave stored rule groups unchanged.

  • Breaking change
  • API
  • Orders
  • Promotions

Percent promotions apply to the remaining balance#

This behavior change affects promotion previews, order creation, discount application, and repricing. Percent promotions now take their percent from the amount left after earlier discounts on the same targets, including manual discounts. Line-item discounts are priced first, then order discounts, then service-charge discounts. The standalone amount_money and would_have_applied_money values continue to use the gross basis.

For example, an order with three items at 25 USD each, a buy-two-get-one-free promotion, and an order promotion for 25% off now receives 12.50 USD from the percent promotion. Previously it received 18.75 USD. The percent promotion's amount_money remains 18.75 USD. Fixed amount_off caps and buy_x_get_y reward pricing are unchanged.

A promotion with no matching targets on the order now reports promotion_decline_reason: not_eligible in preview skipped[], or reason: not_eligible in meta.warnings when explicitly applied with a 200 response. Previously it reported no_discountable_balance. A matching target that has already been fully discounted continues to report no_discountable_balance.

  • Breaking change
  • API
  • Promotions

Promotion updates keep omitted combines_with classes#

Superseded by Promotion codes, gift card loads, and buyer transactions use top-level routes.

Breaking: three promotion writes that Flint used to accept now behave differently.

  • PATCH /v1/promotions/{promotion_id} changes only the combines_with classes in the request. Classes you leave out keep their current value. Before, they were reset to true. combines_with: null, combines_with: {}, and null for a class now return 400; before, they reset every class to true. Creating a promotion still defaults missing classes to true.
  • "status": "" on PATCH /v1/promotions/{promotion_id} and PATCH /v1/promotions/{promotion_id}/codes/{promotion_code_id} returns 400 INVALID_STATUS. Before, it set the status to active. Send active or inactive.
  • application_method.max_discounted_quantity on an amount_off or buy_x_get_y promotion returns 400 INVALID_MAX_DISCOUNTED_QUANTITY with param: application_method.max_discounted_quantity. Before, Flint ignored it. It applies only to percent_off.
  • Breaking change
  • API
  • Refunds

Refund amounts default to the sum of named targets#

POST /v1/refunds now refunds the sum of named line_items, charges, and top-level tax_breakdown_refunds when you omit both top-level amount_money and tender_allocations. The total includes resolved line item tax. Unnamed tips and flat taxes remain unrefunded. Mixed targets no longer require amount_money, and AMOUNT_REQUIRED_FOR_MIXED_REFUND_TARGETS is retired.

A fully discounted charge can reverse its discount alongside a positive line item refund. The combined named targets must total greater than zero.

An allocation whose share is fully withheld by a refund adjustment now counts as zero. A request that previously refunded that withheld share now returns REFUND_AMOUNT_NOT_ALLOCATED when its explicit amount_money cannot be fully allocated. Lower the amount to the refundable target total, or name more refundable targets.

Sending amount_money still sets the refund total. Mixed targets that exceed it return REFUND_TARGETS_EXCEED_REFUND_AMOUNT. When you send tender_allocations, their amounts set the refund total. Omitting the amount and all targets still refunds the full remaining balance.

A payment_intent_id refund of a flat tax split across payments returns FLAT_TAX_PAYMENT_ATTRIBUTION_UNAVAILABLE. Refund by order_id instead.

Breaking: remove handlers for AMOUNT_REQUIRED_FOR_MIXED_REFUND_TARGETS and review explicit refund amounts that include shares withheld by adjustments. See Refunds and Sales tax.

  • Breaking change
  • API
  • Errors

Repeated query parameters are validated#

Breaking: sending a query parameter that accepts one value more than once now returns 400 REPEATED_QUERY_PARAM, with param naming the repeated key. Send the parameter once. Documented multi-value filters and expand continue to accept repeated keys and comma-separated values.

  • Breaking change
  • API
  • Errors

Request body field validation#

Superseded by Boolean and currency field renames and integer bounds.

Breaking: request bodies reject duplicate and miscased fields, and null on fields that can't be cleared.

  • Repeating a member name in the same JSON object returns 400 DUPLICATE_FIELD, with param naming the repeated field. This applies at every depth, including inside metadata.
  • Field names are case-sensitive. A wrong-case field returns 400 UNKNOWN_FIELD, with param naming the field as sent and the message giving the correct spelling. Map keys such as metadata keys stay free-form.
  • Payment intent updates, payout settings updates, risk rule updates, and POST /v1/onboarding/advance return 400 NULL_NOT_ALLOWED when a field that cannot be cleared is sent as null. Omit a field to leave its value unchanged. Payout settings still accept null to clear delay_days_override or an individual currency in minimum_balance_by_currency. Sending the whole minimum-balance map as null still returns 400 INVALID_MINIMUM_BALANCE_BY_CURRENCY. Metadata patches still accept null to clear all metadata or delete a key.

When correcting a write, use a new idempotency key. See Error handling.

  • Breaking change
  • API
  • Refunds
  • Gift-cards

Refunds, wallet cards, and gift card refund allocations use consistent response fields#

POST /v1/refunds returns replacement card codes in data.gift_card_codes. Codes remain recoverable for 24 hours by replaying the original request. Refund reads, lists, expansions, and events omit them.

GET /v1/me/flint-wallet/payment-methods returns the full collection in one page and omits has_more.

Gift card purchase refund value_allocations use amount_money, including the parent refund's currency, instead of a bare amount.

Refund requests that require an Idempotency-Key trim surrounding whitespace. Successful replays carry both Idempotency-Replayed: true and meta.idempotency_replayed: true. A refund of a disputed payment retried with the same key returns the recorded error.

  • Subscriptions
  • Refunds

Subscription payments completed after cancellation are refunded#

If a subscription is canceled while its setup fee or recurring payment is processing, Flint automatically refunds payments completed at or after cancellation to the original payment method. Payments completed before cancellation stay owed. An order with a fulfillment that has started and has not been canceled is excluded from the automatic refund.

When a renewal is processing at period-end cancellation, Flint resolves the renewal first. A successful payment keeps the subscription active through the renewed period before cancellation. A failed payment ends it immediately without payment retries. Older subscriptions may instead cancel immediately and receive the automatic refund when the payment completes.

Automatic refunds use the standard refund.created, refund.updated, and refund.failed events and buyer refund receipt. They carry reason: "other" and metadata source: "subscription_canceled_before_payment" and subscription_id.

See Payments still processing.

  • API

Timestamps carry whole seconds#

Timestamps carry whole seconds, and request timestamps with fractional seconds are truncated. Responses use RFC 3339 UTC timestamps with Z, including delivery configuration timestamps, quote expirations, and customer receivables observations.

Report interval timestamps and gift card recipient send_at now accept fractional seconds. For example, 2026-09-01T00:00:00.123Z is stored and returned as 2026-09-01T00:00:00Z. Request timestamps with other RFC 3339 offsets are normalized to UTC.

  • Breaking change
  • API
  • Orders
  • Payments

Partly paid orders keep their unpaid tip payable#

A partial payment of an order pays for its items and charges before its tip; invoice installments, changed separately, carry the tip first. After a partial payment, removing an item, lowering a quantity, adding a discount, or another change could leave the unpaid tip larger than the balance left to pay. No payment could then complete the order, and POST /v1/orders/{order_id}/pay failed with 400 TIP_ALLOCATION_CAPACITY_EXCEEDED.

Those changes now fail when they happen, with 409 ORDER_TOTAL_BELOW_NET_COLLECTED and retryable: false, and the order stays as it was. required_money is the money already collected, current_money is what the change would leave for items and charges, and gap_money is the difference. ORDER_TOTAL_BELOW_NET_COLLECTED also carries these amounts when a change would drop the whole order total below the money collected.

Breaking: a change that previously succeeded and left the order unpayable now returns 409. Use a refund or credit adjustment instead.

  • API
  • Delivery

Delivery rate callbacks receive the quote's expiry#

Every delivery rate callback request now includes delivery_quote_expires_at, the time the quote expires. Return an expires_at no later than it. A quote lasts up to 15 minutes, or just under 5 minutes for a cart with tracked inventory. The value is truncated to whole seconds.

When the quote expires at or before evaluated_at plus the method's minimum_option_lifetime_seconds, Flint no longer calls your endpoint. The method reports option_lifetime_too_short instead of callback_result_invalid.

See Live delivery rates with a callback.

  • Breaking change
  • API
  • Delivery

Delivery rate callback URL errors use INVALID_URL and INVALID_URL_HOST#

POST /v1/delivery-rate-callbacks and PATCH /v1/delivery-rate-callbacks/{delivery_rate_callback_id} validate configuration.url the same way. A malformed URL, such as one that isn't HTTPS or contains credentials or a fragment, returns 400 INVALID_URL. A URL whose host is private or internal returns 400 INVALID_URL_HOST. Both set param to configuration.url.

Breaking: a malformed URL on create or update used to return DELIVERY_REQUEST_INVALID. A private host on create set param to url, and updating a callback's URL didn't check its host until Flint first called it.

  • Breaking change
  • API
  • Checkout
  • Delivery

Checkout sessions reject an empty delivery method list#

POST /v1/checkout-sessions now rejects "delivery_method_ids": [] with 400 INVALID_REQUEST and "delivery_method_ids": null with 400 NULL_NOT_ALLOWED, both with param set to delivery_method_ids. Leave the field out to use settings.checkout.default_delivery_method_ids, or list 1 to 25 methods.

Breaking: until this release, [] skipped the default. For an order with nothing to deliver it did nothing, and for an order with items to deliver it failed with FULFILLMENT_METHOD_ASSIGNMENT_UNSATISFIABLE. Payment links are unchanged: [] on a link clears its own list so it uses the default.

  • API
  • Delivery

Delivery errors name the field to fix#

  • Previews with an unavailable method. POST /v1/delivery-previews returns 400 FULFILLMENT_METHOD_UNAVAILABLE with param set to delivery_method_ids and blocking_resources naming the method, zone, location set, or rate callback, the same as checkout creation. Until this release it returned 503 DELIVERY_PREVIEW_UNAVAILABLE, which said to retry. 503 DELIVERY_PREVIEW_UNAVAILABLE now means only that a service Flint depends on was unavailable.
  • Subscription previews of a method edit. POST /v1/subscription-previews with mode: "delivery_method_update" returns 400 FULFILLMENT_METHOD_UNAVAILABLE when the method, as saved or as edited, uses a zone or location set that is missing or not active. param is delivery_method.configuration when your edit adds it and delivery_method_id when the saved method already uses it, and blocking_resources names it. Until this release it returned 503 DELIVERY_SERVICE_UNAVAILABLE, which said to retry, or 404 DELIVERY_RESOURCE_NOT_FOUND for a missing zone.
  • Payment links with an unavailable method. Creating or updating a payment link with an unavailable method returns reason and blocking_resources with 400 FULFILLMENT_METHOD_UNAVAILABLE, the same as checkout creation. If Flint fails while checking the methods, creating, updating, or reading a public payment link returns 500 INTERNAL_ERROR, which you can retry, instead of 400 FULFILLMENT_METHOD_UNAVAILABLE or 409 PAYMENT_LINK_FULFILLMENT_UNAVAILABLE.
  • Configuration errors. Creating or updating a delivery profile, zone, location set, method, or rate callback returns param and a specific message for every value you can fix, such as a blank name, a missing minimum_option_lifetime_seconds, or "eligibility": null. A create request without configuration returns DELIVERY_FIELD_REQUIRED, and an unknown or mistyped key inside it returns UNKNOWN_FIELD or INVALID_FIELD_TYPE with param such as configuration.foo. List filters such as status and type name the query parameter the same way.
  • Internal field names. Delivery configuration accepts only documented field names. A request that uses an internal name, such as fulfillment_zone_id for delivery_zone_id or tax_category for charge_tax_category, returns 400 UNKNOWN_FIELD with param set to the path you sent. Until this release, delivery methods accepted several of these names as aliases. Requests pinned to API version 2026-02-01 can still send tax_category when creating a method.
  • Revocations. POST /v1/delivery-revocations names the field to fix. A missing reason or target ID returns DELIVERY_FIELD_REQUIRED, a field the target_type doesn't take returns DELIVERY_FIELD_NOT_SUPPORTED, and a missing expected_version returns DELIVERY_EXPECTED_VERSION_REQUIRED, each with param. A stale expected_version returns 409 DELIVERY_RESOURCE_VERSION_CONFLICT with current_version, and estimated_impact.current_selection_count now counts the selections the revocation affects. Until this release these returned DELIVERY_REQUEST_INVALID without param, an unknown target_type returned DELIVERY_CONFIGURATION_INVALID, and fields the target type doesn't take were ignored.
  • Validation messages for delivery fields end without a period.
  • Name and metadata limits count characters, not bytes.

See Delivery options.

  • Breaking change
  • API
  • Delivery

Delivery methods no longer return offer_windows#

Delivery method configuration no longer includes offer_windows, at the top level or inside estimate.schedule_window. A method offers windows when estimate.type is schedule_window.

Breaking: sending offer_windows in a delivery method create or update now returns 400 UNKNOWN_FIELD with param naming the key. Flint already ignored the value and derived it from the estimate, so remove it from your requests.

  • Breaking change
  • API
  • Delivery
  • Fulfillment

Dimensions use millimeter, centimeter, or inch#

unit on package dimensions, delivery profile configuration.dimensions, and line item fulfillment.dimensions is now millimeter, centimeter, or inch, and length, width, and height must be greater than 0.

Breaking: until this release these fields accepted any string, such as in or cm, and profiles and line items accepted lengths of 0 or less. Those requests now return 400 with param naming the field: INVALID_SHIPMENT_DIMENSIONS for packages, INVALID_FULFILLMENT_REQUIREMENT for line items, and DELIVERY_REQUEST_INVALID for profiles. Dimensions saved earlier with mm, cm, or in are returned with the full unit name.

  • API
  • Delivery

Location sets accept stores without inventory allocation#

POST /v1/delivery-location-sets and PATCH /v1/delivery-location-sets/{delivery_location_set_id} now accept any active Location with an address and time zone. Until this release, a set rejected a Location whose inventory.allocation_status wasn't active with 400 DELIVERY_REQUEST_INVALID, while a pickup method that listed the same Location in origin.location_ids accepted it.

Stock is still checked when a buyer chooses a store: a store that can't supply tracked items shows as unavailable for pickup. See Offer pickup at your shops.

  • Breaking change
  • API
  • Delivery

Pickup search distances use meter, kilometer, and mile#

POST /v1/delivery-previews with mode: "pickup_locations" accepts maximum_distance.unit values meter, kilometer, and mile, the units zone radiuses and distance pricing already use.

Breaking: meters, kilometers, and miles now return 400 DELIVERY_PICKUP_AVAILABILITY_INVALID with param set to maximum_distance.unit. Send the singular value instead.

  • API
  • Delivery

State conditions recognize military addresses and can't be passed with an unknown state#

  • Military addresses. A state condition accepts AA, AE, and AP, stored as US-AA, US-AE, and US-AP, and a buyer address with one of these states matches them. To leave military addresses out of a contiguous US zone, list them with Alaska and Hawaii under not.
  • Unrecognized states. When a condition lists states in the buyer's country and the buyer's state names none of that country's subdivisions, the condition can no longer be decided. The method or rate is left out as cannot_calculate with invalid_buyer_input. Until this release, the condition counted as not matching, so a zone defined as "US, not Alaska or Hawaii" matched an address with an unrecognized state.
  • Other countries. A condition that lists no subdivision of the address's country doesn't match it, even when the address has no state. A rate for US states now falls through for a Canadian address without a province instead of leaving the method out.

See Create zones.