Changes to the Flint API, SDKs, and docs

Create and list workload identities at /v1/workload-identities, and retrieve, update, or archive one at /v1/workload-identities/{workload_identity_id}. An identity defines a trusted external OIDC issuer, audience, subject, claim conditions, and scopes. Each identity belongs to one live environment or test sandbox.

Reading requires accounts.workload_identities.read; writes require accounts.workload_identities.write. API keys and CLI OAuth callers can grant only scopes they hold. Dashboard changes that create, reactivate, or widen a live identity require fresh identity verification.

Updates that replace claim_conditions or scopes require expected_version; scalar-only updates can send it to require the version reviewed. Deleting returns the archived resource and frees a place in the merchant's limit of 100 non-archived identities.

See Workload identities for fields, matching rules, and errors.

POST /v1/oauth/token now supports urn:ietf:params:oauth:grant-type:token-exchange. After creating a workload identity, send subject_token, subject_token_type, and workload_identity_id; optional scope narrows the access token to a subset of the identity's scopes. Client credentials and unrecognized fields are rejected.

The response contains an opaque fwat_ access token that lasts up to one hour, bounded by the issuer token's remaining lifetime. No refresh token is issued. The identity fixes the merchant, mode, and sandbox. Deactivation, archive, and scope narrowing take effect on the next API request, including for previously issued tokens.

GET /v1/developer/auth-context returns auth_type: workload_identity, with the identity ID, name, and access token expiry. OAuth discovery advertises the new grant when available. See Workload identity token exchange for fields, errors, and limits.

POST /v1/customer-verifications no longer takes email. Flint sends the code to the customer's current email and returns that address in email. A customer without an email returns 409 ACTION_NOT_ALLOWED, with param: customer_id and reason configuration_required. No verification or email delivery is created for that request.

POST /v1/checkout-sessions/{checkout_session_id}/customer-verifications now returns 200 instead of 201. Its request schema is a closed oneOf on purpose: gift_card_purchase and save_payment_method require email and accept only channel email; use_saved_payment_methods requires email and accepts email, sms, or auto; confirm_saved_payment_method requires channel email or sms and accepts no email input. Existing channel defaults, rate limits, and verification behavior are unchanged.

Customer verifications prove ownership for linking guest purchases through a merchant's backend. Checkout verifications bind a buyer inside one checkout and use only that session's checkout credential.

These changes apply to every supported API version.

GET /v1/categories accepts an exact handle filter. Handles are lowercase and matching is case-sensitive. Category references include the stable category_id; legacy snapshots without an ID are omitted.

Breaking: list modifier groups use min_selected and max_selected; text groups use required. A set override for the other group type returns 400 INVALID_REQUEST with details[0].code: "NOT_ALLOWED". For a list group, the set's min_selected overrides the group's value and defaults to zero when neither is set. For a text group, the set's required overrides text.required.

Breaking: modifier overrides and payment link options no longer include hidden. Send available: false to make a choice unavailable. Previously stored hidden choices remain unavailable. Promotion application methods no longer accept or return applies_to. Sending either removed request field returns 400 INVALID_REQUEST with details[0].code: "UNKNOWN_FIELD".

Breaking: variants and bundle components no longer return current_delivery_profile_revision_id. Read the current revision from the delivery profile.

Catalog request schemas publish string length limits and category handle patterns. Product variant and bundle SKU and barcode fields accept up to 100 characters. Longer values return 400 INVALID_REQUEST with details[0].code: "INVALID_VALUE" before saving.

Missing child IDs now return 404 RESOURCE_NOT_FOUND with param, resource_type, and resource_id. This covers bundle components, product options and values, payment link line items and custom fields, subscription plan line items, order line-item modifiers, order line items, and order charges. A missing default variant, saved payment method, or deleted parent organization also returns 404.

An inactive default variant or saved payment method returns 409 ACTION_NOT_ALLOWED with the resource reference, current status, and reason. A refund for an existing line item or charge with nothing refundable returns 409 AMOUNT_EXCEEDS_REFUNDABLE. A missing fulfillment obligation returns 404; an exhausted obligation returns 409 FULFILLMENT_QUANTITY_EXCEEDS_AVAILABLE.

Gift card code lookups return the same 400 INVALID_REQUEST with detail INVALID_VALUE on code for unknown, other-merchant, and inactive codes. An allocation that is no longer available returns 409 GIFT_CARD_ALLOCATION_CHANGED; refresh the order and review its allocation before paying again.

Order composition that cannot start a subscription returns 400 INVALID_REQUEST with detail NOT_ALLOWED. Malformed payment sources and self-parent organization references use INVALID_VALUE.

Replace branches on the retired validation codes with RESOURCE_NOT_FOUND and its resource facts, or the relevant conflict code. For request-only failures, branch on INVALID_REQUEST and read details[].param and details[].code. Retained failures use the same public rewrites.

Missing configuration on a saved resource now returns 409 ACTION_NOT_ALLOWED with reason configuration_required. Update the resource named by resource_type and resource_id when available, then retry with a new Idempotency-Key. These refusals omit current_status.

This replaces PRODUCT_OPTIONS_REQUIRED, ORDER_CURRENCY_REQUIRED, INVOICE_TIMEZONE_REQUIRED, CHECKOUT_RECOVERY_EMAIL_ADDRESS_REQUIRED, and FULFILLMENT_PROFILE_REQUIRED. The stored-state branches of LINE_ITEM_PRICE_REQUIRED, INVENTORY_ROUTING_SOURCE_REQUIRED, and INVOICE_PAYMENT_OPTIONS_REQUIRED use the same refusal.

DELIVERY_RECIPIENT_REQUIRED also becomes 409 ACTION_NOT_ALLOWED on the delivery_selection. Its update_checkout_session next action lists required_fields. Add the missing recipient details, create a replacement selection, then retry payment. Orders without a currency include the add_line_items next action.

Missing prices, inventory routing sources, or invoice payment options that the request can supply return 400 INVALID_REQUEST with detail REQUIRED. Branch on INVALID_REQUEST, then read details[].param and details[].code to correct the request. Branch on ACTION_NOT_ALLOWED and its reason to handle saved configuration.

Breaking: credit note lines now return correction in the same shape accepted by draft writes. Replace top-level line quantity reads with correction.quantity for quantity corrections. Amount corrections return correction.amount_money, equal to the line's total_money. To update a draft from a read, send each line's credit_note_line_item_id, invoice_line_item_id, and correction, with expected_version set to the credit note's current version.

available_money replaces unallocated_money and reports credit that can still be allocated or refunded. It is zero on draft and void notes. The new allocated_money reports credit applied to the invoice, net of reversed allocations. On issued notes:

total_money = allocated_money + pending_refund_money + refunded_money + available_money

memo and external_reference_id are always present on merchant credit notes and are null when unset. Buyer credit notes also always include memo, with null when unset. Buyer lines use the same correction shape.

POST /v1/credit-notes/{credit_note_id}/issue now returns data.credit_note and data.invoice, plus data.refund when a refund was requested. Read the issued credit note and its version from data.credit_note instead of directly from data. Issuing without a refund still leaves allocation to a separate call.

Breaking: a reservation's hold deadline is now the top-level expires_at, replacing owner.expires_at. It is null once no line holds quantity, such as after a full commit, release, or expiry. Committed and consumed quantity never expire.

When you create a reservation, send expires_at up to 24 hours from now, or omit it for the 15-minute default. A deadline that isn't after now, or is more than 24 hours out, returns 400 INVALID_REQUEST with param expires_at. The deadline used to be limited to 15 minutes, and it moved from owner to the top level for both merchant and order owners.

PATCH /v1/inventory-reservations/{inventory_reservation_id} with a new expires_at extends or shortens a merchant hold before it lapses. It accepts an optional expected_version, increments the reservation's version, and returns the reservation. A lapsed hold can't be extended: the PATCH returns 409 ACTION_NOT_ALLOWED, as it does for a closed reservation or one with nothing held. A reservation Flint holds for an order returns 403 INVENTORY_RESERVATION_OWNER_MISMATCH.

Breaking: the list filters owner_expires_after and owner_expires_before are now expires_after and expires_before. They match only reservations that currently hold quantity, so a reservation that is fully committed no longer appears in an expires_before query for deadlines that have passed.

Breaking: the commit, consume, and release routes for reservations and the apply and cancel routes for counts are removed. Send POST /v1/inventory-reservations/{inventory_reservation_id}/transitions with action set to commit, consume, or release, and POST /v1/inventory-counts/{inventory_count_id}/transitions with action set to apply or cancel. A request that carries another action's fields returns 400 INVALID_REQUEST at that field. Resending reservation targets that are already applied still succeeds in any status.

Reservations and counts now report supported_actions, the actions that can change them right now. An action that isn't available returns 409 ACTION_NOT_ALLOWED with supported_actions in details[0], and applying an incomplete count returns 409 INVENTORY_COUNT_INCOMPLETE with the count's current_status.

Breaking: the OpenAPI document replaces the operations commitInventoryReservation, consumeInventoryReservation, releaseInventoryReservation, applyInventoryCount, and cancelInventoryCount with transitionInventoryReservation and transitionInventoryCount, and adds updateInventoryReservation. The schemas ReservationLine, CountProvenance, InventoryReservationProvenance, and InventoryTransferProvenanceInput are now InventoryReservationLine, InventoryCountObservationProvenance, and one shared InventoryProvenanceInput. Regenerate clients from the updated document.

The Inventory reference covers deadlines, expiry filters, and transitions, and the inventory guide walks through a hold from creation to consumption.

Breaking: inventory_allocation_enabled replaces inventory_allocation_status on Locations and their create and update requests. Send true to enable inventory allocation and false to disable it. The default stays false, including for Locations without an allocation configuration. Setting the field, including false, still requires commerce.inventory_locations.write in addition to the route's scope.

Filter GET /v1/locations with inventory_allocation_enabled=true or inventory_allocation_enabled=false. This filter accepts one boolean value. The false filter includes Locations without an allocation configuration. Replayed Location responses also return the boolean field.

INVENTORY_LOCATION_ALLOCATION_DISABLED replaces INVENTORY_LOCATION_ALLOCATION_INACTIVE. To accept new inventory claims, a Location must be active and have inventory_allocation_enabled: true.

Inactive Locations can still record physical stock changes through adjustments, counts, transfers, receipts, and safety stock updates. Those commands reject archived Locations. Routing rejects both inactive and archived Locations. Updating an address still requires coordinate in the same request; send null to clear it.

Breaking: Packages, delivery profile configuration, and line-item fulfillment inputs now use the same Weight and Dimensions shapes. The separate ShippingWeight, ShippingDimensions, and line-input measurement schemas have been removed.

Weight values must be greater than zero and at most 1,000,000. Each dimension must be greater than zero and at most 100,000. Both accept up to three decimal places. Values with more precision are rejected, not rounded. Supported units are unchanged.

Send every required member when replacing a weight or dimensions object on PATCH. Stored measurements keep the value and unit you send. Regenerate clients from the updated OpenAPI document.

Flint now serves the same discovery document at /.well-known/openid-configuration and /.well-known/oauth-authorization-server on the API host. It advertises the available OAuth endpoints and grants, CLI scopes, and the jwks_uri for Flint's public signing keys.

Retrieve the key set at /.well-known/jwks.json. All three documents allow public browser access and can be cached for 15 minutes. JWKS supports revalidation with ETag and If-None-Match.

See OAuth discovery and signing keys for request examples and verification guidance.

Checkout session and delivery operations now publish one response schema for API keys, dashboard credentials, and checkout credentials. Delivery responses no longer include audience. The separate Buyer* delivery schemas and credential-selected response unions have been removed. Update generated type references when regenerating your SDK.

Fields a credential never receives carry x-flint-omitted-for-auth. These fields are optional in the shared schema, including merchant-only fields on merchant-only routes that reuse it. Request fields and request branches a credential cannot send carry x-flint-rejected-for-auth; sending them still returns the operation's existing error code. Both annotations list the affected authentication schemes. The API reference shows them beside each field and request branch, for example "Not returned with a checkout credential" or "Not accepted with a checkout credential".

Merchant delivery quotes and checkout fulfillment summaries now include buyer_reasons, and their choice groups include address_advisories when available. Checkout credentials keep delivery_method_ids on pickup previews and receive the same field in shared delivery input requirements on quotes, selections, and fulfillment summaries. The checkout session already returns these IDs in CheckoutSession.delivery_method_ids. Other checkout-credential delivery fields remain the same, apart from the removal of audience.

Fulfillment writes return their subject#

Package create, update, transition, and void now return Package directly. Fulfillment transitions return Fulfillment. Fulfillment event creation returns FulfillmentEvent: 201 creates an event, and 200 returns the same provider event without creating another. The replayed and unchanged body flags are removed. Idempotency-Key replays continue to use the response header and meta.idempotency_replayed.

Before, a package command returned:

{"data":{"package":{"package_id":"pkg_123"},"events":[],"fulfillment_notifications":[],"unchanged":false}}

After:

{"data":{"package_id":"pkg_123"}}

These examples abbreviate resource fields. Shipment void still returns a result because it also voids the shipment's packages. Its members are exactly shipment and packages:

{"data":{"shipment":{"shipment_id":"shp_123"},"packages":[]}}

Read events through GET /v1/fulfillment-events, filtered by package_id, shipment_id, or fulfillment_id. Read notifications through GET /v1/fulfillment-notifications, filtered by fulfillment_event_id or fulfillment_id.

Risk list additions use values and outcomes#

POST /v1/risk-lists/{risk_list_id}/items accepts only values, an array of 1 to 500 strings. Each string must contain 1 to 512 characters. A request using value now returns 400 INVALID_REQUEST with an UNKNOWN_FIELD detail naming value.

Before:

{"value":"blocked@example.com"}

After:

{"values":["blocked@example.com"]}

The response changes from items[].status to additions[].outcome. Each addition includes its full risk_list_item. Entries remain in request order; a repeated value reports existing after its first entry.

Before:

{"data":{"items":[{"status":"created","risk_list_item":{"risk_list_item_id":"rli_123"}}]}}

After:

{"data":{"additions":[{"outcome":"created","risk_list_item":{"risk_list_item_id":"rli_123"}}]}}

The status remains 201 when any entry is created, or 200 when every entry already exists.

Command results name their resources#

Order pay, order payment attempt cancellation, and merchant and buyer subscription renewal results rename payment_attempt to order_payment_attempt. Renewal results keep the subscription as their primary resource.

Before:

{"data":{"order":{"order_id":"ord_123"},"payment_attempt":{"order_payment_attempt_id":"opa_123"}}}

After:

{"data":{"order":{"order_id":"ord_123"},"order_payment_attempt":{"order_payment_attempt_id":"opa_123"}}}

Invoice collection and Return processing remove the result-level idempotency_key. Read the Idempotency-Key response header instead. Resource-level idempotency keys are unchanged.

Before:

{"data":{"invoice":{"invoice_id":"inv_123"},"invoice_payment_attempt":null,"idempotency_key":"collect-123"}}

After:

{"data":{"invoice":{"invoice_id":"inv_123"},"invoice_payment_attempt":null}}

Invoice commands return Invoice#

Invoice issue, send-reminder, and regenerate-public-link return Invoice directly. The public payment URL is data.public_url. Delivery attempts remain available through GET /v1/invoices/{invoice_id}/delivery-attempts.

Before:

{"data":{"invoice":{"invoice_id":"inv_123"},"public_url":"https://checkout.example.com/i/token","delivery_attempt":null}}

After:

{"data":{"invoice_id":"inv_123","public_url":"https://checkout.example.com/i/token"}}

The existing 24-hour replay limit for recovering public_url is unchanged.

Eligibility previews now return can_buyer_request instead of self_service_enabled. Use it to decide whether a buyer can request the line through a customer session. It accounts for policy eligibility, remaining quantity, and the store's available reasons. A policy exclusion includes ineligibility_reason and a specific reason_message. Final-sale exclusions take precedence over the policy's return window.

Return reasons support active, inactive, and archived. Set a Flint or merchant reason to inactive with PATCH /v1/return-reasons/{return_reason_id}, then set it back to active to offer it again. Flint reasons accept only status changes and cannot be archived. Existing Returns keep their recorded reason name and handle.

Find a reason with the exact, case-sensitive handle filter on GET /v1/return-reasons. Lists include active and inactive reasons by default; customer sessions see only active reasons. Flint handles and existing merchant handles, including archived reasons, are reserved. Creating a conflicting handle returns 409 ALREADY_EXISTS.

A reason's category_handles are catalog category handles from GET /v1/categories. Customer sessions may select a scoped reason only for matching products. Merchant and integration callers may select any active reason. Every new Return line still requires a reason.

Eligibility selection lines now use ReturnEligibilityLineItemInput: order_line_item_id and requested_quantity are required, return_reason_id is optional, and buyer_note is no longer accepted. Policy automatic_resolution_type accepts only refund and no_monetary_action. A line's requested_resolution_type excludes correction, and Return.initiated_by excludes system; initiation remains determined by the caller's credential.

Resolution previews no longer return the always-empty warnings array. Resolution and disposition failure_code fields publish extensible vocabularies with descriptions. Dispositions use inventory_effect_failed and inventory_item_unmapped. A failed resolution offers retry only when its failure code is retryable, and POST /v1/return-resolutions/{return_resolution_id}/retry on any other code returns 409 ACTION_NOT_ALLOWED. For refund_line_value_unavailable, cancel the resolution and resolve fewer units or choose an outcome without a refund.

When canceling approved line quantity, omit handback_quantity to reduce the expected handback only as far as the canceled quantity requires. An explicit value cannot leave return_required_quantity above the remaining approved quantity.

Breaking: branch on ACTION_NOT_ALLOWED and details[0].reason for Returns state refusals. This 409 response replaces RETURN_ACTION_NOT_ALLOWED. Details identify the resource whose state refuses the action, including a line item when its verification or acceptance status is the cause. Resources that publish supported_actions include them in the refusal.

Returns refusals use already_applied for completed actions, archived for archived reasons and policies, terminal_status for final Returns, status_not_reached when a required lifecycle step is pending, and unsupported_state for other state refusals. A resolution that already created a refund uses refund_created and offers get_refund in next_actions. refund_unavailable identifies the order whose payment cannot be refunded and omits current_status. Every reason has remediation.retry: none. For an unknown reason, fall back to current_status and choose from supported_actions when present.

Breaking: 400 INVALID_REQUEST replaces RETURN_INVALID and RETURN_FIELD_NOT_ALLOWED_FOR_BUYER. Branch on the detail code: REQUIRED for a missing required field, INVALID_VALUE for an invalid value, UNKNOWN_FIELD for a field the request does not accept, and NOT_ALLOWED for a field unavailable to the buyer. Sending a path field in the body returns UNKNOWN_FIELD; omitting a policy revision's expected_version returns REQUIRED.

Idempotency conflicts return IDEMPOTENCY_KEY_REUSED consistently across Returns transports. Missing internal dependencies return 500 INTERNAL_ERROR. Retained idempotency errors replay with the new public codes. Update error handling and regenerate SDKs from the published OpenAPI schema.

Risk previews now check missing, archived, and incompatible lists, return RULE_RESERVED for proposed policy changes to system rules, and warn with risk_rule_limit_reached when a new enabled rule would exceed the limit.

Preview issue codes use lower_snake_case and paths use public field names, such as predicate.all[0].list_alias or action. Call POST /v1/risk-previews for typed issues. For rule writes, branch on INVALID_REQUEST and read details[].param and details[].code.

Archived list references now return 409 ACTION_NOT_ALLOWED with the list ID and reason archived. Missing aliases return 404 RESOURCE_NOT_FOUND with the alias field path and no resource_id. The enabled-rule error is now RISK_RULE_LIMIT_REACHED, replacing RULE_LIMIT_EXCEEDED, and includes details[0].limit.

Flint now mints every request ID: X-Request-Id, request_id, and error.request_id are req_ followed by 26 characters, unique per request. Send your own X-Request-Id (1 to 128 visible ASCII characters, sent once) and Flint stores it on the request log as client_request_id, which the request-log list filters by. A valid W3C traceparent stores its trace ID as client_trace_id.

error.request_log_url is now the log's detail path, and API keys and CLI tokens with developer.request_logs.read or developer.request_logs.self.read receive it when their request will be logged. Flint writes the log just after responding, so this path can briefly return 404.

Breaking: X-Request-Id is now always Flint's ID; your value is stored as client_request_id. Flint no longer echoes a caller's X-Request-Id, and an invalid or repeated one returns 400 INVALID_REQUEST with param: "header.X-Request-Id" and reason INVALID_VALUE. The request_id list filter accepts only Flint request IDs. Webhook events drop correlation_id and its filter; use api_request_log_id. Public requests no longer continue the caller's trace, so meta.trace_id is Flint's own.

Subscription offers now accept external_reference_id on create and update. Use it to link an offer to a selling plan in another system. The value is optional, opaque, and limited to 255 characters. On PATCH, omit it to keep the current value or send null to clear it. An empty string is invalid.

GET /v1/subscription-offers supports an exact, case-sensitive external_reference_id filter. Its query searches name, subscription_offer_id, and external_reference_id. It also supports created_after, created_before, updated_after, and updated_before.

GET /v1/subscription-plans now supports updated_after and updated_before. All these timestamp ranges include the lower bound and exclude the upper bound.

Offers and plans now publish the same SubscriptionIntervalOption schema for billing_interval_options. The shared schema explicitly rejects unknown fields and publishes billing_interval_count as an int32 integer from 1 to 365. Offer update descriptions now name the public VERSION_CONFLICT error for a stale expected_version.

Missing tax input in a request now returns 400 INVALID_REQUEST with detail code REQUIRED and the request path in param.

Missing tax input on a stored order, line item, or charge now returns 409 ACTION_NOT_ALLOWED with reason configuration_required. Read details[].resource_type and resource_id, update that resource as the message describes, then retry. param no longer names tax fields absent from the request. This applies to required taxability, external calculations and components, and the order's tax location or full address.

Replace branches on ORDER_LINE_ITEM_TAX_INPUT_REQUIRED, ORDER_CHARGE_TAX_INPUT_REQUIRED, TAX_CALCULATION_REQUIRED, EXTERNAL_TAX_COMPONENTS_REQUIRED, ORDER_TAX_LOCATION_REQUIRED, and ORDER_TAX_FULL_ADDRESS_REQUIRED with the status, public code, and detail fields above. Retained failures use the same distinction when replayed.

Use GET /v1/orders?has_unassigned_fulfillment_quantity=true to find orders with required fulfillment quantity that no fulfillment owns. The filter uses the sum of each line's fulfillment_quantities.unassigned_quantity, including bundle components in component units.

Set the filter to false to find orders with no unassigned quantity, including orders that need no fulfillment. A failed fulfillment returns its quantity to this queue only when it releases that quantity. Combine the filter with other order filters and keep it unchanged when following page tokens.

This filter is available to merchants on /v1/orders and is not accepted on /v1/me/orders.

Product variants now accept optional unit_weight and unit_dimensions on create, including variants created inline with a product. They use the shared Weight and Dimensions shapes and preserve the value and unit you send.

On variant PATCH, send a complete object to replace a measurement, omit it to leave it unchanged, or send null to clear it. Reads omit measurements that are unset.

Breaking: Delivery quotes now use the variant's unit_weight at the time the order line is created. Bundle lines use each component variant's unit weight and quantity. Later variant edits leave existing order-line measurements unchanged. Subscription delivery previews and renewals use the current variant measurements.

Delivery profile weight and dimensions remain accepted for now, but no longer supply quote weight. Custom lines continue to use their fulfillment.weight and fulfillment.dimensions inputs.

Delivery rate callbacks omit candidates[].pricing.total_weight_grams when any obligation in the group has unknown weight. Handle an absent value separately from zero grams. Methods that require weight remain unavailable for groups with unknown weight.

Breaking: all three /v1/analytics/* routes now require period_start_at and accept an optional period_end_at. The period includes its start and excludes its end. An omitted or future end resolves to the request time, truncated to the second. Periods can span at most 400 days, or 32 days with hourly buckets.

• range and include_previous_period are removed. Request a second period to compare values. Responses no longer contain previous_*, change_percent, has_multiple_currencies, or bucket label fields.
• Payment volume timeseries accepts granularity=hour|day|week|month, defaulting to day. Weeks start Monday. Buckets follow local boundaries in timezone and are clipped to the requested period. Empty buckets are included. A repeated local hour has two buckets; skipped hours and days have none.
• timezone is accepted only by the timeseries route. Sending it to overview or subscriptions returns 400 UNSUPPORTED_QUERY_PARAM.
• Overview returns gross_volume_money, refunded_money, payments_count, and new_customers_count. Metric wrappers, net_volume, average_payment, and new_subscriptions are removed. Derive net volume and average payment from the returned amounts and payment count.
• Subscription window metrics are new_subscriptions_count, canceled_subscriptions_count, and collected_money. Snapshot metrics are mrr_money, arr_money, and status_counts. New subscriptions include only subscriptions created in the period whose current status is trialing, active, paused, or past_due.
• Subscriptions now accepts currency, defaulting to your account's default currency. All routes return currency and currencies. Amounts and payment counts use the selected currency; customer and subscription counts span currencies. Subscription snapshots reflect current state, independently of the requested period.

The /v1/me schemas now describe the resources buyers receive, including subscriptions, shipments, packages, payment methods, Returns, and nested checkout and renewal results. Generated SDK types omit merchant-only and expansion-only fields. Examples and error lists match the buyer operations.

Buyer Return creation accepts order_id and line_items. Resolution previews accept catalog variants or bundles as replacement items, without merchant pricing overrides or adjustments. The buyer resolution preview no longer accepts expected_version. Read based_on_return_version in the result for the evaluated snapshot.

The origin, billing_schedule_owner, needs_attention, and hold_reason filters remain available. Buyer operations continue to reject expand.

Return image objects no longer include an undocumented internal field.

Return bundle components now use the published delivery_configuration_status, delivery_configuration_reason, delivery_profile_id, and current_delivery_profile_revision_id names instead of undocumented fulfillment_* names.

Return modifiers now use the published modifier_group_name instead of the undocumented group_name.

DELETE archives products, variants, bundles, modifier groups, modifier sets, promotions, and promotion codes. The response matches a following GET. Repeating DELETE returns 200 with the archived resource without changing its version or updated_at, checking references, or sending another webhook. When the route accepts expected_version, a stale version still returns 409 VERSION_CONFLICT before the replay.

Writes on an archived resource return 409 ACTION_NOT_ALLOWED. details[0] identifies the resource with resource_type and resource_id, current_status: "archived", and reason: "archived". Creating a variant under an archived product identifies the product; creating a code under an archived promotion identifies the promotion. Updating an archived variant or code identifies that child. remediation.retry is none.

Breaking: these archived writes replace 404, PRODUCT_ARCHIVED, or PROMOTION_ARCHIVED with ACTION_NOT_ALLOWED. Repeated DELETE requests return 200 instead of 404.

Breaking: bundles now default to status: "active", like other catalog resources. Include components when creating an active bundle. To create a draft without components, send status: "inactive". Omitting both returns 400 INVALID_REQUEST with details[0].code: "REQUIRED" and param: "components".

Promotion and promotion code creation now accept status: "active" or "inactive", including codes created in a promotion's codes array. Omission defaults to active. An inactive promotion or code has available: false and cannot apply to a purchase. Catalog create schemas now publish their active status defaults.

You can now replace components on an active bundle using its latest expected_version. Existing orders, checkout sessions, invoices, subscriptions, and plans keep their component snapshots. New orders use the new components, and payment links resolve them on their next read.

When adding or activating a product option, send existing_variant_value on its entry in options[] to give existing active variants a value. It must match one of the option's active values, ignoring case and surrounding whitespace. Flint updates only active variants that lack an active value for that option. The option and variant changes succeed together or fail together. Each changed variant advances its version and sends product_variant.updated, alongside the product's product.updated event.

If active variants need a value and you omit existing_variant_value, the request returns 400 INVALID_REQUEST with detail code REQUIRED and a parameter such as options[0].existing_variant_value. This prevents an option edit from leaving active variants incomplete and causing a later price or name update to fail.

Removing or inactivating a value selected by active variants returns 409 RESOURCE_IN_USE, with up to 10 blocking variant references and a total count. Move those variants to another value or inactivate them before retrying. You can still retire a whole option while variants keep its historical selections.

Open orders no longer block variant or bundle deactivation. Open checkout sessions, invoice payment attempts, active payment links, plans, subscriptions, and active bundles that contain a variant still protect their references. Delete and currency-change guards retain their existing behavior.

ACTIVE_BUNDLE_COMPONENTS_IMMUTABLE, ACTIVE_VARIANTS_REQUIRE_OPTION_BACKFILL, and OPTION_IN_USE_BY_ACTIVE_VARIANTS are removed. The Dashboard supports editing active bundle items and choosing the value existing variants receive when you add an option.

GET /v1/bundles, GET /v1/products/{product_id}/variants, GET /v1/categories, GET /v1/modifier-groups, GET /v1/modifier-sets, and GET /v1/promotion-codes now accept created_after, created_before, updated_after, and updated_before. Lower bounds are inclusive; upper bounds are exclusive. Pass RFC 3339 timestamps. Products and promotions already support these ranges.

Categories add sort_by=handle|created_at|updated_at and sort_direction=asc|desc, keeping handle ascending as the default. Modifier groups, modifier sets, and promotion codes add sort_by=created_at|updated_at and sort_direction=asc|desc, defaulting to created_at descending. Ties use the resource ID in the same direction.

Breaking: modifier group and modifier set lists now default to created_at descending instead of ID descending. Start a fresh pagination sequence after upgrading. Promotion codes keep their existing default order.

To recover catalog changes, list with sort_by=updated_at&sort_direction=asc&updated_after=<last seen minus a few minutes>. Include archived in the status filter for resources that support it, and re-list a changed product's variants. Use an overlap and apply results by resource ID: updated_at does not promise the order in which changes committed. Catalog writes preserve later stored timestamps, including when a variant change touches its product or a promotion or code is archived.

Breaking: the REST contract replaces X-Checkout-Session-ID and X-Checkout-Session-Secret with one bearer token. Send the checkout_auth_token from checkout_access:

GET /v1/checkout-sessions/cs_1kmn0aExample
Authorization: Bearer ckat_1kmn0aExample

The token names its session, so you send no session ID beside it. The OpenAPI spec publishes it as the CheckoutSessionBearer security scheme on the 30 operations that accept a checkout credential, and removes the two header schemes and their parameters from every operation. Update your relay to build one Authorization header. The prefix tells a checkout credential from an API key, but sending it together with X-API-Key returns 400 INVALID_REQUEST with detail code NOT_ALLOWED and conflicting_fields naming Authorization and X-API-Key.

Breaking: a checkout credential used on another session's /v1/checkout-sessions/{checkout_session_id} path now returns 404 RESOURCE_NOT_FOUND. It returned 403.

Breaking: a credential past its own lifetime returns 401 INVALID_CREDENTIAL with details[0].reason expired. It returned unknown, as does a credential Flint doesn't recognize.

The cklt_ launch token in a hosted checkout's url isn't an API credential. Sent as a bearer token, it returns 403 FORBIDDEN with details[0].reason checkout_launch_token_restricted.

Ended sessions#

The checkout credential used to stop working the moment its session closed or expired, which left a buyer's page with a 401 instead of the outcome. Now it keeps reading its own session:

• GET /v1/checkout-sessions/{checkout_session_id} returns 200 with status closed or expired, terminal_reason, and merchant_support, so your page can say what happened and how to reach the merchant. The read leaves out payment_collection and setup_collection, because an ended session can't take a payment.
• Every other call with the credential returns 409 CHECKOUT_SESSION_NOT_OPEN, with details[0].current_status set to closed or expired. These calls returned 401.

To let the buyer try again, create a session with the same order_id while the order is still payable. You can omit replace_checkout_session_id or send the old closed or expired session's ID. If the order has no open session, Flint creates the new session normally. If another session is now open, naming the old one returns 409 CHECKOUT_SESSION_CURRENT_CHANGED with the current session in details[0].current_checkout_session_id and details[0].blocking_resources. The named session must belong to the same merchant, environment, and order. Replacing the current open session still invalidates it and creates the new one in one step.

closed_by_buyer is removed#

A buyer can't close a session, so terminal_reason: "closed_by_buyer" and the matching checkout_session.closed detail never appeared on a stored session. Both are gone from the spec and the webhook catalog. A closed session has terminal_reason: "closed_by_merchant".

See Build your own checkout and When the session ends.

POST /v1/checkout-sessions now requires type. Send order with order_id, quick_pay with quick_pay_item, or subscription_plan with subscription_plan_id. Fields belonging to another type return INVALID_REQUEST with a NOT_ALLOWED detail. Subscription plan sessions require email; explicitly setting buyer_fields.require_email to false is rejected.

customer_id moves to the top level of checkout requests and responses. Create accepts it with quick_pay and subscription_plan. With order, set the customer on the order first; sending customer_id on checkout creation returns INVALID_REQUEST with a NOT_ALLOWED detail. Creation no longer returns CHECKOUT_CUSTOMER_CONFLICT or CHECKOUT_CUSTOMER_NOT_SET_ON_ORDER.

buyer_fields replaces customer_collection for checkout sessions and payment links. Checkout sessions expose merchant-supplied contact and address values in top-level prefill, replacing customer_collection.prefilled_customer_info. customer_prefill still comes from the customer record, and buyer_contact still records what the buyer saved.

Hosted checkout uses redirects.success_url, redirects.cancel_url, and redirects.expired_url. Embedded checkout uses top-level payment_return_url for redirect payments such as Affirm. Redirect URLs accept at most 2,048 characters. Successful hosted redirects append checkout_session_id and order_id, replacing the previous csId and orderId parameters. Confirm payment through the order.paid webhook or by reading the session.

Top-level expires_in_seconds replaces expiration.expires_in_seconds on checkout sessions. Payment links use checkout_session_expires_in_seconds for each session they start. The old expiration objects are removed; expiration-page destinations use redirects.expired_url.

Checkout session responses and webhooks expose type in place of origin: order, quick_pay, subscription_plan, invoice, or payment_link. Lists accept a multi-value type filter; the origin filter is removed. Closing a checkout session now accepts an omitted request body.

Breaking: Settings and UpdateSettingsRequest no longer include catalog. Delivery profiles now return the required, read-only boolean is_default. Find the default with GET /v1/delivery-profiles?is_default=true; use is_default=false to list other profiles.

To change the default, PATCH the selected delivery profile with {"is_default":true,"expected_version":7}, using that profile's current version. You can combine this with other profile edits. Moving the default advances both profiles' versions and emits delivery_profile.updated for each. Selecting the current default alone succeeds without advancing its version or emitting an event. New physical product variants and bundle components that omit delivery_profile_id use the default.

is_default:false returns 400 INVALID_REQUEST. Archiving the default profile returns 409 RESOURCE_IN_USE with your merchant as the blocker; make another active profile the default first.

POST /v1/delivery-profiles/{delivery_profile_id}/assign-to-unconfigured now accepts only the profile's expected_version fence. expected_catalog_default_version is removed. A default change advances the previous default's profile version, so an assignment with its old version returns VERSION_CONFLICT.

The settings routes no longer declare delivery errors or SETTINGS_CONCURRENT_MODIFICATION. Update callers and regenerate SDKs from the published OpenAPI schema.

Use GET /v1/files/{file_id} to read a file's status: awaiting_upload, processing, ready, failed, or expired. Failed files include a failure_code. Reads never return an upload URL. To retry an upload, create a new file.

expires_at now describes when a file expires in its current status. While awaiting_upload, it equals the upload deadline. For a ready, unattached file, it is the last instant you can attach it: 24 hours after processing or 7 days after its last detachment. It is omitted while attached and in every other status. content_type and size_bytes describe the declared upload until the file is ready, then the stored image.

Attach a completed file with images: [{ "file_id": "file_…" }], or use file_id in a payment link's image or a merchant's logo or icon. Each image input accepts exactly one of file_id and source_url. Canonical Flint URLs still work in source_url when copying an image to another resource.

On updates, resending the exact external source_url of an image still attached to the same field reuses that image without downloading it again. To replace bytes behind a stable URL, send a different URL, such as one with a version query parameter, or upload a file. An unchanged gallery keeps its image revision. Owner updates still follow their existing version and event behavior. Flint never returns source_url.

Breaking: Per-image external_reference_id is now source_reference. It accepts 1 to 255 characters, preserves surrounding whitespace, and remains unique within a gallery. Resource-level external_reference_id fields keep their names.

Owned galleries and image slots now return ImageAttachment: url, alt, width, height, optional file_id, and optional source_reference. Snapshot, public, and buyer images use Image, which contains only url, alt, width, and height.

Send an Idempotency-Key when creating a file to recover a lost response. Without one, create another file; the unused upload expires after 15 minutes.

Inventory allocation policies now expose current_inventory_allocation_policy_revision_id. Creating a policy publishes its first revision, and replacing its configuration publishes a new immutable one. Updating its name, metadata, external reference, or status keeps the current revision. A policy's version is still the counter you send as expected_version.

Read a policy's revision history with GET /v1/inventory-allocation-policies/{inventory_allocation_policy_id}/revisions, or retrieve one revision with GET /v1/inventory-allocation-policies/{inventory_allocation_policy_id}/revisions/{inventory_allocation_policy_revision_id}. Both routes require commerce.inventory.read. The list defaults to newest first and supports page_size, page_token, sort_direction, created_after, and created_before. created_after includes its boundary and created_before excludes it.

Breaking: Inventory routing sources use type: policy_revision and inventory_allocation_policy_revision_id in place of policy_version and inventory_allocation_policy_version_id. This applies to reservations, orders, payment links, subscription plans, invoice quick-pay requests, and delivery previews. Send the new names in requests; policy_version is rejected. The invpv_ ID prefix stays the same.

Routing sources in responses name both the policy and the revision, so you can read the configuration that routed the stock. A policy_revision source returns the inventory_allocation_policy_id its revision belongs to wherever it appears, including replayed responses, and a reservation routed by policy returns the inventory_allocation_policy_revision_id it resolved to. Send only the ID that belongs to the source's type in a request.

Reservation webhook snapshots and replayed responses use the revision field names too, including a replayed policy create or update first sent before this change, which now includes current_inventory_allocation_policy_revision_id. Errors name inventory_allocation_policy_revision_id, and resource references use inventory_allocation_policy_revision.

Every inventory movement now uses source_reference to name the resource whose write recorded the change. Adjustments point to the adjustment, receipts to the receipt, reservation changes to the reservation, and safety stock changes to the inventory level. Fulfillment, count, and transfer movements point to the fulfillment, count, and transfer. Read the resource with its GET route, or list a resource's movements with source_reference_type and source_reference_id.

Breaking: source_reference is required in the movement schema. Its resource_type is one of inventory_adjustment, inventory_count, inventory_receipt, inventory_reservation, fulfillment, inventory_transfer, and inventory_level. The source_reference_type list filter accepts those same types; inventory_reservation_line and product_variant are removed. Reservation movements name the reservation, not one of its lines. Match a line by the movement's inventory_item_id and location_id.

Breaking: created_by is a required, nullable ResourceReference instead of a string. It identifies the API key, partner app install, or user that recorded the movement, using resource_type values api_key, partner_app_install, or user. An API key is recorded as the key, not as the user who created it. created_by is null when Flint records a movement on its own, including expired holds, order and payment automation, and fulfillment handoffs.

Breaking: reservation_consumed replaces fulfillment_consumed for both merchant and fulfillment consumption. The movement's source_reference tells them apart: an inventory_reservation for a merchant's consume, and a fulfillment for a handoff. system_correction is removed from the movement type vocabulary.

Breaking: movement reason is now optional and appears only on adjustments, where it uses the adjustment reason vocabulary: received, returned, sold, theft, loss, condition_changed, counted, and correction. The reason list filter accepts only those values and returns adjustment movements. Other movements describe the event in type.

Breaking: every line sent to POST /v1/inventory-receipts requires both inventory_reservation_id and inventory_reservation_line_id. A receipt puts back units that the reservation line consumed, bounded by its consumed quantity minus units already received. A missing ID returns 400 INVALID_REQUEST with detail code REQUIRED at that field. Record new stock with an adjustment using reason: received, or a customer return sold outside Flint with reason: returned. Return dispositions keep their existing receipt rules.

The Inventory reference lists which call records each physical event, and Reading the ledger covers movement sources and created_by. available_quantity is documented as never below 0.

Breaking: PATCH /v1/inventory-transfers/{inventory_transfer_id} now accepts lines instead of line_changes. Send the complete collection and expected_version. Keep inventory_transfer_line_id on existing lines, omit it to add a line, and omit a line from the array to remove it. Every line requires inventory_item_id and requested_quantity; condition defaults to sellable. An existing line must repeat its stored item and condition, so send condition for any line that isn't sellable. A line's item and condition can't change.

Flint validates the full collection before saving it. Lines with departed or canceled quantity must remain. A departed line must keep its requested quantity, and any line must request at least its canceled quantity. Refusals return 409 INVENTORY_TRANSFER_LINE_CONFLICT; an omitted line with history is named in the error details. Duplicate line IDs or item and condition pairs return 400 INVALID_REQUEST.

Transfer lines now use condition instead of physical_condition on create, PATCH, and reads. Transfers use external_reference_id instead of external_reference on create, PATCH, reads, and the list filter. The filter matches exactly and is case-sensitive. On PATCH, omit the reference to keep it or send null to clear it. Empty strings are rejected.

GET /v1/merchant-billing-entries returns merchant billing activity with signed effects on your outstanding balance and available credit. It requires merchant_billing.read and supports API key and Dashboard authentication.

Filter by type, currency, occurrence or recording time, payment_intent_id, dispute_id, merchant_billing_invoice_id, or balance_transaction_id. The list returns newest occurred_at first, then descending causal type rank and entry ID within the same second. Use page_size and page_token to read additional pages.

occurred_at is when the event happened; created_at is when Flint recorded the entry. Events can arrive late. To pick up newly recorded entries after merchant_billing_balance.updated, filter on created_after and deduplicate by merchant_billing_entry_id. Generate a merchant_billing_itemized_v1 report to export an interval. It fails with data_unavailable when billing projections or membership history are inconsistent, collection outcome or balance transaction evidence is missing, or an entry is invalid. See Reporting for retry behavior.

The report and list return the same entries. These report changes apply immediately to every supported API version:

• created_at follows occurred_at in the CSV header.
• merchant_billing_invoice_id replaces merchant_subscription_invoice_id.
• Entry types invoice and custom_domain_collection replace subscription_invoice and software_collection. All 11 types are available in the list's type filter.
• mbe_ IDs use the underlying source identity, so public type renames preserve entry IDs. Existing report entry IDs change once.
• CSV rows use ascending occurrence time, causal type rank, and entry ID. Reversing the list returns the same order.

These changes apply immediately to every supported API version.

• Use /v1/merchant-billing-invoices and /v1/merchant-billing-invoices/{merchant_billing_invoice_id} instead of /v1/merchant-subscription-invoices and its retrieval route. The operations are listMerchantBillingInvoices and getMerchantBillingInvoice.
• Invoice responses use merchant_billing_invoice_id. The schemas are MerchantBillingInvoice, MerchantBillingInvoiceLineItem, MerchantBillingInvoiceResponse, and MerchantBillingInvoiceListResponse. Invoice IDs still start with msinv_, and line item IDs still start with msinvl_.
• Invoice line_items replaces lines. Each item has merchant_billing_invoice_line_item_id, type, name, quantity, unit_price_money, total_money, and created_at. These replace merchant_subscription_invoice_line_id, line_type, description, unit_amount_money, and amount_money. Amounts remain unsigned: subscription totals add to subtotal_money, and credit totals add to credit_money.
• Subscribe to merchant_billing_invoice.issued and merchant_billing_invoice.updated instead of merchant_subscription_invoice.issued and merchant_subscription_invoice.updated. Their resource type is merchant_billing_invoice.
• Balance transaction type values are now merchant_billing_collection and merchant_billing_collection_reversal, replacing merchant_billing_payment and merchant_billing_payment_reversal. Use the new values in filters. Transaction IDs are unchanged.
• Balance transaction related_resource.resource_type and the related_resource_type filter use merchant_billing_invoice instead of merchant_subscription_invoice.
• Merchant billing read failures return INTERNAL_ERROR instead of MERCHANT_FINANCE_READ_FAILED. Missing invoices continue to return RESOURCE_NOT_FOUND, with param: merchant_billing_invoice_id and resource type merchant_billing_invoice.
• Merchant billing balances include currency. /v1/merchant-billing-balances returns all balances on one page, omits next_page_token, and rejects page_size and page_token.

To find unpaid invoices, use GET /v1/merchant-billing-invoices?status=open,collecting,delinquent. The status filter accepts comma-separated or repeated values from draft, open, collecting, paid, delinquent, void, and written_off.

Settings changes apply immediately to every supported API version:

• Each environment keeps its own merchant settings. Settings responses no longer include settings_scope, organization_id, location_id, or device_id. GET /v1/settings/effective rejects the removed location_id and device_id query parameters.
• GET /v1/settings returns stored values. GET /v1/settings/effective fills in Flint's defaults. Send null for a settings section to remove every value you set in it; effective reads then use the defaults.
• PATCH field descriptions now state whether a nested object applies only the fields you send, replaces the whole object, replaces the full map, or merges metadata by key. Present arrays replace the stored array.
• Every tax_identity patch requires expected_version, including a legal_name edit or tax_identity: null. Read the current Settings.version and send it as expected_version.
• Settings no longer declare INHERIT_ONLY_VIOLATION, SUBSET_ONLY_VIOLATION, MIN_BOUND_VIOLATION, or MAX_BOUND_VIOLATION errors.

Partner apps and flint-cli share the OAuth token and revocation endpoints. Discovery metadata is available at https://api.withflintpay.com/.well-known/oauth-authorization-server.

These breaking changes apply to partner OAuth on every supported API version:

• Authorization requires code_challenge and code_challenge_method=S256. Keep the matching code_verifier with your state and send it when exchanging the code. A wrong verifier consumes the code.
• Authorization and preview accept space-separated scope permission IDs in place of permission_ids. Omit scope to request your app's defaults. Required permissions are always granted. Unknown parameters, including the removed permission_ids, are ignored and never forwarded to consent. Recognized parameters may appear only once.
• POST /v1/oauth/token accepts only application/x-www-form-urlencoded bodies. JSON bodies and URL query strings return invalid_request. Authenticate with HTTP Basic or client_id and client_secret form fields, using one method per request.
• Partner token responses return token_type: Bearer, replacing bearer. Their scope lists sorted granted permission IDs, replacing API scope names. Test-mode responses include sandbox_id; live-mode responses omit it. An optional refresh scope must match the full granted permission set.
• Redirect URIs must not contain a fragment, including an empty #.
• The token and revocation operations are named exchangeOAuthToken and revokeOAuthToken, under the oauth tag. They publish OAuthTokenRequest, OAuthTokenResponse, and OAuthRevokeRequest in place of the separate partner and CLI schemas. Regenerate clients that use the old names.

If a partner refresh response is lost, retry the same token within 60 seconds while its replacement is unused. Flint returns a new pair and invalidates the lost replacement. The retry window starts at the original rotation and does not extend. Reusing an old token after that window, after its replacement was rotated, or after it was superseded by a retry revokes its token family and invalidates that environment grant's access tokens. The other mode keeps working, and the install and grant stay active. Authorize that mode again to recover. Reusing a consumed authorization code also revokes the tokens that code issued.

Partner apps can revoke tokens with POST /v1/oauth/revoke. Revoking a refresh token ends its family and invalidates the grant's access tokens. Revoking an access token invalidates the grant's outstanding access tokens while its refresh token keeps working. Unknown, expired, and other clients' tokens return 200. Revocation does not uninstall the app.

CLI OAuth errors now include a fixed error_description. Existing flint-cli form requests, token lifetimes, and refresh-reuse behavior continue to work.

Breaking: order.updated now reports material edits to orders that stay closed, including fulfillment creation, fulfillment progress, and paid subscription destination corrections. order.closed fires only when an order moves from open to closed, with no additional generic order.updated for that transition. Payment/refund-only changes continue to use their dedicated money events.

Breaking: shipment.updated and package.updated now cover resource revisions beyond status changes. Shipment metadata and external-reference edits send an update. Adding a package to an existing shipment sends package.created and shipment.updated with the final package_count. Derived shipment timestamps and other persisted shipment revisions also send updates when status stays the same.

Package updates cover tracking, carrier, service, label, weight, dimensions, external references, metadata, and contents. Creating, editing, or deleting a package item advances the parent package's version and updated_at and sends one package.updated. Its data.object is the package snapshot, without items. Re-list GET /v1/packages/{package_id}/items, paging to completion, to refresh contents. An item edit alone does not update the shipment or order. Initial shipment, package, and item creation together sends creation snapshots without extra updates for the initial contents.

Subscribers to these events or to all events receive more deliveries. Your own API writes produce events too. Distinct committed revisions produce distinct events, including changes within one second or a change back to an earlier value. Deduplicate deliveries by webhook_event_id, expect out-of-order delivery, and compare shipment and package version before replacing a saved snapshot. Retries preserve the original snapshot; fetch the resource for current state.

fulfillment_event.created still reports timeline facts and their typed previous_status and current_status on transitions. Tracking changes keep their existing timeline event. Metadata and contents edits do not create status facts or buyer emails; use actual buyer moments when sending your own mail.

Event names and resource payload shapes stay the same. Past missing updates are not backfilled; read current resources to refresh a mirror. See Webhook event payloads and Staying in sync.

PATCH /v1/orders/{order_id}/line-items/{order_line_item_id} now compares expected_version with the order's version, matching line-item adds and removals. The fence is optional for scalar edits and required when modifiers, gift_card_recipient, or subscription is present. A stale fence returns 409 ORDER_CHANGED_REFRESH_REQUIRED with param: expected_version and the order's current version in details[0].current_version.

Line-item PATCH returns OrderResponse for every credential, including checkout credentials. OrderLineItem.version, CheckoutSessionLineItemModifierUpdate, and CheckoutSessionLineItemModifierUpdateResponse are removed. Read the order's version from data.version before updating a line.

CHECKOUT_SESSION_REVISION_CONFLICT and ORDER_LINE_ITEM_VERSION_CONFLICT are retired. The checkout conflict's modifier choices, selected modifiers, and pricing facts are removed from ErrorDetail. Retained errors with either retired code replay as VERSION_CONFLICT. Refresh the order before rebuilding the change with a new idempotency key.

A retry using the same idempotency key across this change can return a key-reuse conflict. Previously recorded checkout modifier successes can replay their earlier response shape during the 24-hour retention window.

Partner apps can subscribe to all 17 inventory_* events on webhook endpoints with the installed_merchants event source. The installed merchant's grant must include commerce.inventory.read.

These events cover inventory levels, counts, receipts, reservations, and transfers. Reservation events cover merchant-owned reservations; stock changes from checkout and order reservations are reported through inventory_level.updated.

See Inventory events and Partner app installs for event details and endpoint setup.

Breaking: branch on ACTION_NOT_ALLOWED and details[0].reason. Payment intent updates, confirmations, captures, cancellations, receipt requests, refunds, and order mutations now use this shared 409 error for state refusals. details[0] identifies the refusing resource with resource_type and resource_id and reports its current_status. For an unknown reason, fall back to current_status.

The following public codes are retired:

• PAYMENT_INTENT_CANNOT_BE_UPDATED
• PAYMENT_ALREADY_SUCCEEDED, PAYMENT_CANCELED, PAYMENT_EXPIRED
• INVALID_STATUS_FOR_CAPTURE
• PAYMENT_INTENT_NOT_CANCELABLE, CANNOT_CANCEL_SUCCEEDED_PAYMENT, PAYMENT_ALREADY_CANCELED, CANNOT_CANCEL_EXPIRED_PAYMENT
• AMOUNT_NOT_UPDATABLE, CUSTOMER_NOT_UPDATABLE, RECEIPT_EMAIL_NOT_UPDATABLE, PAYMENT_SOURCE_NOT_UPDATABLE
• PAYMENT_INTENT_NOT_REFUNDABLE
• ORDER_CLOSED, ORDER_NOT_PAYABLE

Reasons distinguish the available next step:

Receipt requests and refunds before success use status_not_reached, in_progress, or terminal_status according to the payment intent's status. Merchant-managed receipts continue to use reason merchant_managed_receipts without a lifecycle status. An invoice payment attempt cancellation identifies the refusing payment_intent, even though the route names the invoice attempt.

remediation.retry is none; remediation.next_steps describes the remedy for the reason. A processing cancellation refusal includes a get_payment_intent next action. Canceling a succeeded payment includes create_refund.

Retained idempotency errors replay with the new public codes. Update error handling and regenerate SDKs from the published OpenAPI schema.

POST /v1/payment-intents and GET /v1/payment-intents/{payment_intent_id} now publish PaymentIntentWithCollection, composed from PaymentIntent plus payment_collection. It replaces PaymentIntentResult on GET and the unnamed create schema. Update generated type references when regenerating your SDK.

The JSON responses are unchanged. Create always includes payment_collection. GET includes it while status is requires_payment_method or requires_confirmation, subject to these conditions: a payment intent owned by a checkout session requires that session's checkout credential, and an order-linked payment intent omits it when using a checkout credential.

The composed schema inherits PaymentIntent's field definitions and presence rules. Payment intent webhook schemas reference PaymentIntent and no longer declare payment_collection.

Breaking: POST /v1/orders/{order_id}/payment-intents now returns CreatePaymentIntentResponse, matching standalone creates. Read data.payment_intent_id instead of data.payment_intent.payment_intent_id. The required data.payment_collection remains beside the payment intent's fields and directs order payments to POST /v1/orders/{order_id}/pay. CreateOrderPaymentIntentResponse and CreateOrderPaymentIntentResult are removed.

current_payment_action appears only in PaymentIntentWithAction, returned by POST /v1/payment-intents/{payment_intent_id}/confirm as ConfirmPaymentIntentResponse. It is always present: a typed action when buyer authentication is needed and Flint can provide it, or null otherwise. It is removed from PaymentIntent, PaymentIntentWithCollection, and BuyerPaymentIntent. Reads, lists, other writes, and webhooks omit it. If a confirm response is lost, read the intent; if its status is requires_action, call confirm with an empty body to recover the action. If confirm returns requires_action with a null action, call confirm again with an empty body.

GET /v1/payment-intents/{payment_intent_id} omits payment_collection for order-owned intents. Use Order.payment_collection and its selectable_payment_intents instead.

Standalone capture and cancel accept no body, whitespace, or {}. These changes apply to every supported API version. Regenerate SDKs against the updated OpenAPI specification.

Set default_payment_method_id on PATCH /v1/customers/{customer_id} or PATCH /v1/me to choose an active off_session payment method belonging to that customer. Send null to clear it. The customer response always includes the field, with null when there is no default.

Changing the default, including deleting the default card, advances the customer's version once and sends customer.updated. An unchanged default is a no-op. You can use expected_version on either PATCH route to refuse an update when the customer has changed.

Payment method responses include is_default. Merchant responses and payment method webhook snapshots also include fingerprint once card details are known. Equal fingerprints identify copies of one card number within your merchant and environment. Wallet cards can have a different fingerprint from the same card entered directly. Buyer credentials never receive this field.

The operation IDs savePaymentMethod, removePaymentMethod, saveMePaymentMethod, and removeMePaymentMethod are now createPaymentMethod, deletePaymentMethod, createMePaymentMethod, and deleteMePaymentMethod. Their HTTP paths are unchanged.

Breaking: Payment reviews now use /v1/payment-reviews and payment_review_id. The ID prefix remains rev_. Operations are listPaymentReviews, getPaymentReview, approvePaymentReview, and declinePaymentReview; schemas use PaymentReview names, and resource references use payment_review. Webhook events are payment_review.opened, payment_review.closed, and payment_review.reopened.

Breaking: Payment risk, refunds, and refund creation results use payment_review_id in place of review_id. Buyer refunds omit this merchant-only reference. Payment review closed_by and resolution_started_by are nullable resource references to the acting credential, or null when Flint acted.

Breaking: A decline closes with closed_reason: declined, including when Flint refunded the payment. Read refund_id and refunded_money to see whether it refunded. Conflicting review actions return 409 ACTION_NOT_ALLOWED with resource_type: payment_review: a closed review reports current_status: closed and reason: terminal_status; an action already underway reports current_status: resolving and reason: in_progress.

Breaking: The decline request field add_to_block_list becomes add_to_block_lists. Fraud warnings and their list filter use is_actionable in place of actionable. Fraud warning payment summaries use the FraudWarningPaymentSummary schema.

Risk scores keep their 0-99 range, now published in the reference schema. Higher scores mean higher fraud risk. An absent score means no score is available, not a score of zero. Risk levels remain normal, elevated, highest, and not_assessed, with descriptions of the processor's screening result.

These changes apply immediately to every supported API version.

• stacking_mode is removed from promotions, create and update requests, and discount preview candidates. To prevent a promotion from combining with other promotion discounts, set all three combines_with booleans to false.
• exclusivity.selection is removed. Each group chooses its highest-priority promotion, then the larger standalone discount, then the earlier created_at, then the lower promotion_id. Priority defaults to 0, is always present in responses, and cannot be null in PATCH. Send 0 to reset it. Group names must contain 1 to 100 characters after trimming and match exactly, including case.
• GET /v1/promotions removes the available and unavailable_reason filters. Use the multi-value availability filter, for example ?status=active&availability=available,no_active_codes. Archived promotions still require status=archived.
• GET /v1/promotion-codes replaces the available filter with multi-value availability: available, inactive, expired, exhausted, or promotion_unavailable. Removed query parameters return INVALID_REQUEST with detail code UNKNOWN_FIELD. Response fields available and unavailable_reason are unchanged.
• Rule groups use only objects: {"all": [...]} or {"any": [...]}, each with at least one rule or nested group. Bare arrays, empty groups, and a rules key are rejected with INVALID_REQUEST and detail code INVALID_VALUE. Omit a rule group for no rules, or send null when PATCH allows clearing it. Responses list rules before nested groups. Under any, a nested group containing only one rule reads back as that rule. Under all, nested groups keep their boundaries to preserve matched_items.subtotal scope.
• Creating a promotion requires application_method.type: percent_off, amount_off, or buy_x_get_y. The flat application method accepts only fields for that effect. PATCH remains sparse: omitting type keeps the stored effect; changing type replaces it.
• matched_items.subtotal in an all group now counts only the line items matched by that group's line_item.* rules, including its nested groups. A cart with $30 of hoodies and $40 of hats no longer satisfies a $40 hoodie minimum because the hat amount was included.

Manual discounts stay on the order and do not count toward the promotion cap. Frozen subscription-term promotions remain exempt from exclusivity, combination rules, and the cap.

POST /v1/refunds accepts destinations, with optional payment_intent and gift_card_redemption keys. Each is original or new_gift_card and defaults to original. Use it with refund_type: "full", "targets", or "amount" without tender_allocations. A key for a tender absent from the refund has no effect.

Setting payment_intent to new_gift_card refunds that value as store credit. The payment must have succeeded, belong to an order, use USD, and have been paid by card, Apple Pay, Google Pay, or Link. Affirm, ACH debit, other payment options, non-USD payments, and payments without an order return 400 INVALID_REQUEST with a NOT_ALLOWED detail. Store credit needs a payment that belongs to an order so Flint can issue the gift card to that order's customer. The error's param is destinations.payment_intent or tender_allocations[i].destination. Open chargebacks retain the existing dispute refusal. Refunds to the original payment method still work for standalone payments.

The refund consumes the original payment's refundable value and reverses the order value and tax. Flint makes no processor refund: the merchant keeps the cash, the original processing fee is not returned, and the gift card value becomes a liability. A later dispute on the payment freezes the gift card value. The gift card load reports source.funding_source_type: "store_credit", payment_intent_id, order_id, and refund_id.

For gift card redemption value, new_gift_card issues new cards instead of crediting the original card. This includes refunds whose original gift card is closed or cannot accept the full value. The order requirement for payment intent store credit does not change gift card redemption destinations.

destinations is not allowed with tender_allocations or gift_card_load_id; the error detail names both conflicting_fields. With explicit allocations, set destination on each allocation. Gift card purchase refunds return cash.

New gift card codes are returned in data.gift_card_codes on create and same-key retries for 24 hours, while each code remains current. Ordinary refund reads and webhooks omit the codes. Direct refund creation sends no gift card email; the caller delivers the codes.

Breaking: destination: "replacement" is renamed "new_gift_card" on refund tender allocation inputs and responses. Sending replacement returns INVALID_REQUEST with an INVALID_VALUE detail. Payment intent allocations now accept destination too.

Breaking: refund_method is removed from Refund and BuyerRefund responses, including expansions and webhook payloads. Read tender_allocations[].destination and destination_cards for the result. A store credit refund can succeed with an empty payment_refunds list.

Breaking: CSV columns change in place for balance_transactions_itemized_v1, payouts_itemized_v1, payments_itemized_v1, tax_transactions_itemized_v1, and gift_card_liability_v1. Their report type names stay the same. Update importers that depend on column names, positions, or fee signs before generating new reports.

• Balance transaction fee charges are positive, and returned fees are negative, matching GET /v1/balance-transactions. net_money.amount stays unchanged and equals amount_money.amount - fee_money.amount. The report adds description and order_id. payout_id identifies the paid payout containing the transaction. related_resource.resource_type and related_resource.resource_id replace payment_intent_id, refund_id, dispute_id, and return_id, and identify the source payout for a payout debit. Related resources contain only valid Flint IDs.
• Payout reports contain the full balance transaction columns followed by arrival_date. They remove payout_entry_id. For each payout, net_money.amount sums to the payout's amount_money.amount. A payout matches the interval when the start of its arrival_date in the report's timezone falls within the interval.
• Payment reports rename invoice_fee_money to invoice_collection_fee_money and subscription_fee_money to subscription_collection_fee_money. These fees and automatic_tax_fee_money each include an amount and currency column.
• Tax transaction reports use line1, line2, state, tax_category, price_mode, and jurisdiction.*. Provider columns are removed. Every money value has an amount and currency pair.
• Gift card liability reports replace bare amount columns and the shared currency column with opening_money, loads_money, imports_money, redemptions_money, refunds_money, cash_outs_money, purchase_reversals_money, purchase_refund_recoveries_money, adjustments_money, and closing_money, each with an amount and currency column.
• Text cells that start with =, +, -, or @, after any leading whitespace, get a leading ' so spreadsheets don't run them as formulas. This applies to description on balance transaction and payout reports, jurisdiction.* text on the jurisdiction tax reports, and the text columns on tax transaction reports. Strip the ' if your importer reads these values as data.

developer.request_logs.read reads request summaries and detail for every caller in the credential's environment. developer.request_logs.self.read now reads both summaries and detail for the calling credential. The separate developer.request_logs.self.detail.read scope is retired; stored grants retain access to their own requests. The operations are now listAPIRequestLogs and getAPIRequestLog.

Request logs include a caller resource reference when Flint can identify the caller. Filter lists with caller_id or one or more caller_type values using developer.request_logs.read. Filtering caller_id by an API key ID also includes its older requests within the 90-day summary retention window. Other caller IDs and caller_type match requests recorded after this deployment. Older rows can still show a caller, except for older CLI requests whose user was not recorded. An own-only reader opening another caller's detail receives 403 INSUFFICIENT_SCOPE naming developer.request_logs.read. Other merchants and environments remain inaccessible.

Detail includes ip_address and user_agent for API keys, users and partner app installations. Buyer-side checkout, customer-session and invoice callers never expose these device fields. Headers and captured bodies remain redacted, with detail retained for 14 days.

Breaking: Request summaries and detail replace response_shape_metadata with expand, the normalized expand paths Flint applied, and remove correlation_id. Use api_request_log_id to identify the log. reference_url is now an absolute Flint guide URL. Reproductions remove safe_to_reproduce, reproduction_complete, recommended_environment and warnings. Replaying a non-GET request changes data; replay with a sandbox key.

Resource timelines now return a discriminated union of api_request, webhook_event, webhook_delivery_attempt and image_mutation entries. API request entries follow the same own-only or merchant-wide visibility rule. The default includes all four groups; include=image_mutations selects image changes. Entries no longer repeat the timeline's test, resource_type or resource_id, and no longer include correlation_id. Webhook event entries contain event identity and optional request links; delivery-attempt entries contain attempt results and recovery guidance. Attempt failures use error_category and error_summary, with no duplicate error_code, last_error or diagnostic_category.

Fraud warning IDs now start with frw_ instead of fw_. Gift card purchase refund allocation IDs now start with gcpra_ instead of rta_. Update prefix checks in your integration, including checks for fraud_warning_id, dispute references, and webhook payloads. These changes apply to all supported API versions; the old prefixes are not accepted for these resources.

Refund allocation IDs keep rta_, Flint wallet card handles keep fwc_, and other existing public resource prefixes stay the same.

The OpenAPI specification and webhook examples now use valid Flint ID prefixes and complete uppercase ULIDs. Request ID examples use UUIDs. Repeated example IDs stay consistent across fields and URLs.

Breaking: receipt verification and inspection acceptance decisions now compare expected_version with the receipt or inspection returned in data. They previously compared it with the parent Return. Read the observation's new version and send that value when verifying a receipt line or deciding an inspection line. Each observation also has updated_at. The version advances and the timestamp records the write time when a line changes or the observation is superseded. A new observation starts at version 1.

A stale fence returns 409 VERSION_CONFLICT with param: expected_version. Its detail names return_receipt or return_inspection, the observation's ID, and its current_version. Changes to the parent Return alone no longer invalidate an observation fence. Return state restrictions still apply.

Breaking: resolution create and preview now take expected_return_version. Send the Return's version as expected_return_version on POST /v1/returns/{return_id}/resolutions, or as resolution.expected_return_version on POST /v1/return-previews. The fence remains optional. expected_version is no longer accepted on those inputs. A stale parent fence returns 409 VERSION_CONFLICT naming the field you sent, with the Return's ID and current_version.

To preserve a preview before creating a resolution, send the same expected_return_version on both requests. GET /v1/return-receipts and GET /v1/return-inspections now accept updated_after (inclusive) and updated_before (exclusive).

Cancel actions on Returns, Return resolutions, and Return dispositions now record cancellation_reason, cancellation_reason_message, and canceled_by on the resource. The message and actor are visible only to merchants. A disposition's reason still describes why it was created.

Canceling a Return's last approved line quantity also records that call's reason, message, and actor on the Return.

Manual completion records the supplied completion_reason and completion_reason_message on the Return. Automatic completion leaves these fields absent. Reopening a Return clears its completion reason, message, time, and actor.

Use GET /v1/returns/{return_id}/activities with commerce.returns.read to read the merchant activity history, including reasons for reopen, retry, release, and partial line cancellation. Each activity includes its actor, referenced resource, and resulting return_version. Results are newest first; send sort_direction=asc for chronological order. Use page_size and page_token to paginate.

Activities are merchant-only and have no /v1/me route. Read the referenced resources for their current state. Existing Return, resolution, and disposition webhook events include the new resource fields; no new event types are added.

Breaking: resume applies only to paused subscriptions and returns 202. Both POST /v1/subscriptions/{subscription_id}/resume and its /v1/me equivalent return 202 Accepted with Retry-After: 2. The subscription remains paused with resume_requested_at set until Flint applies the request. Flint then clears the timestamp and sends subscription.resumed as the status becomes active, or past_due while an overdue period is collected. If delivery becomes unavailable before Flint can resume it, the subscription stays paused, the timestamp clears, and Flint sends subscription.updated. Accepting each request also sends subscription.updated and advances the subscription's version.

Breaking: reactivate is the only way to undo a scheduled cancellation. Resume no longer clears a pending cancellation or returns a successful no-op on an active subscription. Resume refusals return 409 ACTION_NOT_ALLOWED with details[0].reason set to cancellation_scheduled, payment_required, or not_paused, plus current_status. For a scheduled cancellation, call reactivate. For past_due, update the payment method and create a payment retry. These reasons replace the former CANNOT_RESUME and payment-related resume error codes.

Breaking: scheduled starts report scheduled. This new closed-enum status appears on subscriptions, expanded subscription summaries, and subscription webhook snapshots. It means the subscription has starts_at and no delivery hold or inventory wait. At starts_at, Flint collects the first period; it becomes active once paid, or past_due if the payment fails. incomplete now describes a first payment being collected or held. Analytics add status_counts.scheduled_count, and incomplete_count excludes scheduled starts. Both list filters accept scheduled.

Breaking: default cancellation honors its scheduled time or returns a conflict. Without cancel_immediately: true, trialing subscriptions continue until trial_end_at, active subscriptions end at current_period_end_at, and past_due subscriptions end at next_retry_at instead of that retry, including when the first period was never paid. An active subscription with an expired renewal delivery hold still ends immediately. For scheduled, incomplete, paused, and past_due without a retry time, send cancel_immediately: true; otherwise Flint returns 409 ACTION_NOT_ALLOWED with reason period_end_unavailable. An existing scheduled cancellation remains unchanged on repeated requests.

Buyer cancellation follows the same timing. Under end_of_period, a trialing buyer can cancel at trial end and is never charged. Immediate cancellation during the trial requires buyer_chooses. When no scheduled cancellation time is available, a buyer can send cancel_immediately: true under either policy.

New: scheduled_cancel_at and resume_requested_at are always present and nullable. scheduled_cancel_at reports the trial end, current period end, or next retry at which a scheduled cancellation takes effect. It is null when no cancellation is scheduled. resume_requested_at is null unless a paused subscription has a pending resume request. Trial-end cancellations now send subscription.cancellation_scheduled.

Attention filtering excludes first payments until they are overdue. A scheduled start or an immediate signup's in-flight first payment does not match needs_attention unless its billing date is more than 24 hours overdue or another existing attention condition, such as a hold, applies.

When updating a subscription plan, leaving out billing_interval_options, quantity_options, or subscription_delivery_method_ids keeps the current values. Each field rejects null with a 400 response.

• Send billing_interval_options: [] to reset the choices to the plan's default billing interval and count.
• Send quantity_options: [] to reset the choices to [1].
• Send subscription_delivery_method_ids: [] to remove all delivery methods.

The field descriptions and error messages now explain these existing behaviors. The update request example omits these arrays when changing only the description and metadata.

The shared PaymentIntent schema now marks risk as optional and omitted with the checkout credential. Merchant credentials always receive the field, with null when no assessment is available. This documents the responses already returned by order payment creation and cancellation.

Breaking: branch on ACTION_NOT_ALLOWED and details[0].reason. Merchant and buyer subscription routes now return this 409 error for state refusals. It replaces CANNOT_PAUSE, CANNOT_RESUME, CANNOT_RESUME_PAST_DUE_PAYMENT_REQUIRED, CANNOT_RESUME_INITIAL_PAYMENT_PENDING, SUBSCRIPTION_ALREADY_PAUSED, SUBSCRIPTION_RENEW_NOT_ALLOWED, SUBSCRIPTION_SCHEDULE_MUTATION_NOT_ALLOWED, SUBSCRIPTION_PAYMENT_RETRY_NOT_ALLOWED, and SUBSCRIPTION_CANCELED.

The single error detail identifies the subscription with resource_type: subscription, resource_id, and its stored current_status. State refusals omit param: subscription_id. Pausing an already paused subscription with a different duration returns reason field_locked and param: pause_duration_cycles; resume before choosing a new duration. When included, current_version is the subscription's version.

Use these reasons to choose the next step:

• terminal_status: create a new subscription if the canceled subscription must be replaced.
• cancellation_scheduled: reactivate the subscription before pausing or renewing.
• trial_in_progress: wait for the trial to finish before renewing.
• external_billing_schedule: use the system that owns the billing schedule.
• delivery_hold: update the delivery preference before choosing another action.
• payment_required: complete the outstanding payment before resuming.
• initial_payment_pending: wait for the initial payment to complete before resuming.
• inventory_wait: wait for inventory or update the subscription items before retrying payment.
• unsupported_state: read the subscription and choose an action its state allows.

The old renewal reasons not_active and renewal_in_progress become terminal_status or unsupported_state, and in_progress, respectively. Every ACTION_NOT_ALLOWED reason uses remediation.retry: none. In particular, wait for an ongoing renewal and read its result; automatically retrying renew-now after it finishes could start another renewal. For an unknown reason, fall back to current_status.

Retained idempotency errors replay with the new public codes and reasons. Older errors that did not store enough facts use unsupported_state.

Breaking: checkout terms that no longer match the frozen subscription lines return ORDER_CHANGED_REFRESH_REQUIRED with no param. Read the current checkout before submitting new terms. A genuine concurrent terms update still returns CONCURRENT_MODIFICATION, without a field pointer, and can be retried with the same idempotency key.

Order responses and webhook payloads replace purchased_event with ticketed_event. Update integrations to read the event's name, starts_at, timezone, and location from ticketed_event. Read ticket numbers from ticketed_event.ticket_numbers and ticket status from ticketed_event.ticket_status: pending, issued, or void. When ticket_status is void, ticket_numbers can be empty if a refund released the tickets before issue.

Every metadata key beginning with flint_ is reserved for Flint and hidden from public responses and webhooks. Other keys belong to the caller, and only caller keys count toward the 50-key limit on order metadata, including charge, fulfillment, and line-item metadata. Move integrations that read ticket metadata to ticketed_event. Buyer order responses now omit metadata entirely.

These are breaking changes to order responses and webhook payloads.

Breaking: the nested deliveries route is removed. GET /v1/webhook-events/{webhook_event_id}/deliveries no longer exists on any API version. Use GET /v1/webhook-deliveries?webhook_event_id=whev_... for the same result.

GET /v1/webhook-deliveries returns deliveries across all of your endpoints, newest first (created_at descending, then webhook_delivery_id). Filter it with:

• webhook_event_id: deliveries of one event.
• webhook_endpoint_id: deliveries to one endpoint.
• status: pending, delivered, failed, or suppressed. Repeat the parameter to match more than one.
• created_after (inclusive) and created_before (exclusive): bounds on created_at.

Page with page_size and page_token. A page token only works with the filters it was issued for. A webhook_event_id or webhook_endpoint_id that doesn't exist, or that your credential can't see, returns 404 RESOURCE_NOT_FOUND. Unlike GET /v1/webhook-events, the list includes deliveries of synthetic test events.

The operation ID listWebhookDeliveries moves to the new route, so regenerate SDKs and update calls that passed a webhook_event_id path parameter to pass it as a query parameter. To find deliveries that need a resend, filter by status=failed, then call POST /v1/webhook-deliveries/{webhook_delivery_id}/resend.

Additional resource versions are being prepared for a later release. Continue using the version and expected_version fields documented for each endpoint. The release that activates additional counters will describe their fields and any required collection fences.

Breaking: branch on ACTION_NOT_ALLOWED and details[0].reason. This 409 response now requires a reason. remediation.retry is always none, and remediation.next_steps explains what to do for that reason. For an unknown reason, fall back to current_status and choose from supported_actions when present.

The shared reasons are already_applied, terminal_status, status_not_reached, in_progress, archived, field_locked, and unsupported_state. Reasons with a specific remedy are merchant_managed_receipts, derived_from_packages, on_hold, refund_unavailable, refund_created, payment_collected, cancellation_scheduled, trial_in_progress, external_billing_schedule, delivery_hold, payment_required, initial_payment_pending, and inventory_wait.

The registry also includes the existing credit_note_tax_reconciliation_required reason and its reconciliation steps.

Fulfillment and package transitions replace FULFILLMENT_ACTION_NOT_ALLOWED and PACKAGE_ACTION_NOT_ALLOWED with ACTION_NOT_ALLOWED, reason unsupported_state. FULFILLMENT_ON_HOLD becomes ACTION_NOT_ALLOWED with reason on_hold. The details identify the refusing resource and its current status. Unsupported transitions also include supported_actions, current_version, current_resource, and param: action.

Existing archived-product, archived-plan, and archived-risk refusals use reason archived. Closed and expired inventory reservation refusals use terminal_status, replacing the old expired reason. Payment receipt requests before success replace reason payment_not_succeeded with status_not_reached. Inventory lifecycle refusals use unsupported_state, and payout entries requested before payment use status_not_reached.

Breaking: live-mode authorization uses 403 FORBIDDEN with reason live_mode_required. This replaces API_VERSION_LIVE_MODE_REQUIRED, PROFILE_WRITE_LIVE_MODE_REQUIRED, and CUSTOM_DOMAIN_LIVE_MODE_REQUIRED. Merchant profile writes previously returned 409; checkout custom domain refusals previously returned 400. Sandbox, partner app, and organization management use the same reason instead of sandbox_management_requires_live_key, partner_app_management_requires_live_key, or organization_live_mode_required.

Send a live-mode API key or use the live dashboard environment. A merchant update with several live-only fields returns one detail per field, in request order; top-level param names the first. An unresolved credential mode also refuses these writes. Custom domain validation names domain_type; a settings update names checkout.custom_domain.

Retained idempotency errors replay with the new public codes and reasons. Update error handling and regenerate SDKs from the published OpenAPI schema. Payment, order, Returns, delivery, and subscription code migrations will follow separately.

Payment intent responses to customer sessions, checkout credentials, and invoice access tokens now omit risk instead of returning risk: null, matching the documented buyer response schema. Merchant responses continue to include risk.

Sign out with POST /v1/me/session/revoke, using the current customer session secret as Authorization: Bearer. The secret stays on your server. Sign-out works after the secret expires and after the session has been revoked. Repeating the call preserves the first revoked_at. A secret replaced by refresh is no longer accepted.

Create and refresh return CustomerSessionWithCredentials: the session resource plus secret and refresh_token. Both single-session revoke routes return CustomerSession with status: revoked and revoked_at, without credentials. The resource includes created_at, expires_at, and refresh_token_expires_at. Revoke-all keeps its customer_id and revoked_count result.

Customer sessions no longer return account_url or account_url_expires_at, and create rejects account_url_expires_in_seconds as an unknown field. For hosted sign-in, use POST /v1/customers/{customer_id}/access-links.

Refresh still requires Idempotency-Key. Use one fixed key per session, such as refresh-cses_...: Flint scopes it to the refresh token, so concurrent requests with the same token and key receive the same rotated credentials. On 409 IDEMPOTENCY_KEY_IN_PROGRESS, retry with the same key and token. Refreshing a used token with a different key revokes the session.

These changes apply to every supported API version.

POST /v1/disputes/{dispute_id}/response-sessions creates a browser session for responding to or viewing a dispute with Stripe Connect. It returns 201 with dispute_id and client_session. Initialize Connect with the returned publishable_key and account session client_secret, then pass components[0].payment to setPayment or the React payment prop. Keep the Flint API key on your server.

The route requires payments.disputes.write, which is now grantable to merchant API keys in live and test mode and included in full_access. An empty body or {} is accepted. A completed retry with the same Idempotency-Key creates a fresh single-use client secret. Sessions can open for closed disputes to show the submitted response. Bank returns return 409 ACTION_NOT_ALLOWED with reason bank_return_not_contestable; an unavailable linked payment returns the same code with reason dispute_payment_unavailable.

Breaking: inquiry statuses have new names. These changes apply to disputes, payment intent dispute statuses, payment intent activity and results, and their status filters:

An unrecognized dispute state now returns other instead of under_review. Treat other as open, do not assume an outcome, and read it again later. You can still open a response session. Refund protection remains in effect.

Breaking: dispute reasons use a smaller vocabulary. product_unacceptable is now product_not_as_described, credit_not_processed is refund_not_processed, incorrect_account_details is bank_account_not_found, and bank_debit_not_authorized is debit_not_authorized. general, customer_initiated, check_returned, and bank_cannot_process become other. bank_account_closed and bank_account_restricted have been removed. Reason filters use the new values too. Unrecognized reasons return other.

Breaking: evidence fields. is_evidence_submission_past_due has been removed. Use is_evidence_deadline_passed for the deadline. has_evidence means evidence is saved, submitted or not; evidence_submission_count tells you whether it was submitted. can_respond_with_evidence means the dispute has an evidence response window and can remain true after the window closes or a decision is made. Use is_action_required to know whether a response is needed now. The response-unavailable reason provider_response_unavailable is now response_window_unavailable.

Breaking: one condition event per change. dispute.closed has been removed, and dispute.warning_closed is now dispute.inquiry_closed. The terminal events are dispute.won, dispute.lost, dispute.prevented, and dispute.inquiry_closed. Update webhook subscriptions to use them. dispute.needs_response also covers an inquiry escalating to a chargeback when the dispute needs a response now. dispute.updated is sent only for another public change when no condition event applies. A first observation sends dispute.created and, when applicable, one condition event, so a new bank return sends dispute.created and dispute.lost.

These error code changes apply immediately to every supported API version, including retained error responses replayed with an idempotency key. HTTP statuses stay the same.

The following throttles now return RATE_LIMIT_EXCEEDED with remediation.retry: same_request:

• CUSTOMER_VERIFICATION_RATE_LIMITED
• PAYMENT_METHOD_SAVE_CODE_LIMIT_REACHED for temporary phone and network throttles
• EMAIL_CHANGE_RATE_LIMITED
• RECEIPT_RATE_LIMITED
• ORDER_RECEIPT_RESEND_RATE_LIMITED
• INVOICE_REMINDER_RATE_LIMITED
• CUSTOM_DOMAIN_VALIDATION_RATE_LIMITED
• PAYMENT_LINK_RESOLUTION_RATE_LIMITED
• TOO_MANY_PENDING_REPORTS
• WEBHOOK_STREAM_CONNECTION_LIMIT
• DAILY_LIMIT_EXCEEDED

Handle RATE_LIMIT_EXCEEDED instead of these names. When a limit belongs to one action, param names it, such as order_id for an order receipt resend or new_email for an email change. Honor Retry-After when present. Flint-Rate-Limited-Reason continues to identify the limiter scope, including demo-session for demo sandbox limits.

The permanent quota of 3 confirmation codes per saved card and channel returns 429 SAVE_PAYMENT_METHOD_CODE_LIMIT_REACHED with remediation.retry: none. Confirm through the other channel; waiting does not reset this quota. Receipt cooldowns and the rolling 24-hour demo-session cap now send the remaining wait in Retry-After.

CHARGE_REFUND_AMOUNT_EXCEEDS_REFUNDABLE and LINE_ITEM_REFUND_AMOUNT_EXCEEDS_REFUNDABLE now return AMOUNT_EXCEEDS_REFUNDABLE. Use param to identify the indexed charge or line item amount to reduce, and details[0].maximum_money for the remaining refundable amount and currency.

Creating another checkout session for an order that already has an open session now returns ALREADY_EXISTS with param: order_id. Read the existing session reference from details[0].current_resource instead of existing_checkout_session_id or blocking_resources. Reuse that session, or send its ID as replace_checkout_session_id to replace it. Flint omits current_resource when the caller can't read checkout sessions, such as a key with no checkout session access or a buyer credential, and on a replayed response whose credential can't read it.

DELIVERY_SELECTION_REPLACEMENT_LIMIT is now DELIVERY_SELECTION_REPLACEMENT_LIMIT_REACHED. For capacity errors, _LIMIT_REACHED means requests of that kind cannot succeed until capacity resets or a count drops. _LIMIT_EXCEEDED means a smaller request can fit within the remaining capacity. For the delivery selection history limit, finish the checkout or start another checkout session.

Breaking: update gift card integrations to use the routes, result objects, and field names below. These changes apply to every supported API version. The removed routes return 404; old request fields and query parameters are rejected.

The result schemas replace their corresponding response wrappers as well. Issuance, loads, balance adjustments, cash-outs, and redemption create, capture, and cancel return data.gift_card and data.gift_card_transactions. Loads also return data.gift_card_load; redemption commands return data.gift_card_redemption. An adjustment that increases value returns its load. Manual redemption creation returns an empty transaction array until capture. Code rotation returns data.gift_card and recoverable code fields, with no transaction array. Issue and load return 201; adjustments, cash-outs, rotation, capture, and cancel return 200.

Transactions appear in posting order. A same-key retry returns the original transaction IDs and balance snapshots without posting again. On card commands, expected_version fences data.gift_card.version; capture and cancel fence data.gift_card_redemption.version. Code and code_recovery_expires_at remain available only during the 24-hour recovery window while that code is current.

idempotency_key is required and nullable on transactions, loads, and redemptions. It contains your key when you supplied one; it is null when Flint created the record or no key was sent. The list filters match only caller keys. Transaction reason is your adjustment reason on adjustments, customer_request on cash-outs, and null on every other transaction type, including funding_loss_accepted. Neither field uses an empty string as a missing value.

Notification retrieval returns up to 20 delivery attempts and 50 delivery events, with has_more_attempts and has_more_events. Attempts no longer include provider_status_code. Event types are accepted, delivered, bounced, and dropped; they replace processed, delivered, bounce, and dropped. accepted means Flint's email service accepted the message for delivery.

Gift card and order webhooks use the same new field names and null rules. sale_reference, reserved_money, and the funding-limit reason buyer_daily keep their names. Update SDKs after regenerating them against the new OpenAPI specification.

GET /v1/oauth/authorize now sends the merchant's browser to Flint's consent screen, and the install completes there. The merchant signs in, chooses a merchant, reviews the permissions and the access each one grants, and chooses Install app or Deny. Flint then redirects to your redirect_uri with code, state, and mode, or with an OAuth error. See Partner app installs.

access_denied means the merchant declined. Flint sends it only when the merchant chooses Deny. Onboarding, admin-access, and sandbox problems stay on Flint instead of redirecting to your app, and the merchant can fix them or choose Deny.

Added: requested_permissions[].required_scopes on GET /v1/oauth/authorize/preview lists the Flint API scopes each permission grants.

Breaking: GET /v1/oauth/authorize no longer accepts a dashboard session bearer, and it no longer creates an install. No external credential could use it.

Invoice line totals now keep inclusive tax inside the subtotal, matching the order total. A line with subtotal 1200 and included tax 200 has total_money 1200. Additive tax continues to be added to the discounted subtotal.

Credit notes also support invoices whose stored inclusive line total previously counted tax twice. Corrections use the original subtotal, discount, and included tax to limit credit to the amount billed. Issued invoice amounts stay unchanged. Existing credit notes with inconsistent tax still require reconciliation before further credit can be issued or spent.

Request validation failures now return 400 INVALID_REQUEST. Branch on INVALID_REQUEST, then read details[].param and details[].code to identify each input to correct. Every detail uses REQUIRED, INVALID_VALUE, UNKNOWN_FIELD, or NOT_ALLOWED. Whole-body failures name body; header failures name the header, such as Idempotency-Key or Flint-Version.

Fields that a checkout or customer credential cannot send now return 400 INVALID_REQUEST with NOT_ALLOWED, including customer_id on /v1/me routes. Conflicting credentials return INVALID_REQUEST with NOT_ALLOWED and conflicting_fields. A present but malformed expected_version uses INVALID_VALUE; an omitted required version uses REQUIRED.

Three domain codes keep their own handling: PAYMENT_OPTION_UNAVAILABLE, PROMOTION_DECLINED, and PAYMENT_PROCESSOR_REJECTED. Payment option amount limits now use PAYMENT_OPTION_UNAVAILABLE with reason amount_out_of_range, the payment option when known, and maximum_money when the amount exceeds the maximum. Payment update refusals use PAYMENT_PROCESSOR_REJECTED.

Inventory routing no longer returns 422. The reservation endpoint continues to reject caller-supplied assignments as UNKNOWN_FIELD. Failed scheduled invoice activities expose public error codes. Retried requests with retained failures use the same public error shapes.

Update code that branches on retired validation codes to use the input path and detail code. Correct each named input, then send the request again with a new Idempotency-Key. State-dependent validation conditions scheduled for separate changes keep their existing codes for now.

Breaking: every count observation requires expected_physical_version. PATCH /v1/inventory-counts/{inventory_count_id} now requires this on each entry in observations: the level's physical_version you read before counting that item. A level that doesn't exist yet reads as 0, and 0 is valid. A missing, null, negative, or fractional value returns 400 INVALID_REQUEST with param set to observations[i].expected_physical_version.

Before this change, a count captured each level's physical version once, when you created it, and nothing could refresh it. A sale, receipt, or correction after you created the count made it impossible to apply, even if you counted again with the correct expected_version. The only way out was to cancel the count and start another. Now each saved observation keeps its own version, and captured_physical_version on a count line means the version of the latest saved observation, not the version when the count was created.

To count again after stock moved, read the level, count the item, and save the complete observation set with a fresh expected_physical_version for that item. Send unchanged items back with their saved quantities and saved captured_physical_version. Reading a newer version without counting again doesn't make an old count current, so recount an item even when the number is the same. Holds and commitments don't move physical_version, so they never invalidate a count. The same count then applies without being canceled or recreated.

Breaking: stale physical counts return VERSION_CONFLICT. INVENTORY_COUNT_PHYSICAL_REVISION_CHANGED is removed. A PATCH whose expected_physical_version is stale, and an apply against a saved observation that has since gone stale, return 409 VERSION_CONFLICT. details has one entry per stale line with resource_type inventory_level, resource_id, inventory_count_line_id, inventory_item_id, location_id, captured_physical_version, and current_physical_version. A PATCH conflict sets param to observations[i].expected_physical_version and saves nothing. An apply conflict has no param, because the apply request has no field for it, and changes nothing. Before this change the apply error named param lines, which the request doesn't contain. A stale count expected_version keeps param expected_version and resource_type inventory_count.

A replayed response for an Idempotency-Key first used before this change returns VERSION_CONFLICT, not the removed code. Send a corrected count with a new key.

A count of items that keep selling can keep going stale. Count fewer items at a time, or pause physical movement for them while you count. See Inventory and the inventory guide.

The Dashboard now reads each counted item's version, marks an item whose stock moved after you counted it, and asks you to count it again instead of telling you to drop the count.

Inventory provenance accepts opaque actor and source identifiers, including picker@dc-3 and secret-garden-pos. Don't put secrets in these fields.

The OpenAPI schemas now publish the existing provenance rules:

• external_actor_id and source_system.external_source_id accept at most 255 Unicode code points.
• Source types pos, wms, erp, and other require external_source_id and occurred_at.
• Source type manual does not allow external_source_id.
• occurred_at can be at most 5 minutes in the future.

Public callers can send source types manual, pos, wms, erp, and other. Flint-authored events can return flint. Return receipt schemas publish their corresponding limits using received_at and source_system.source_system_type.

Breaking: inventory provenance validation returns 400 INVALID_REQUEST instead of INVENTORY_EVENT_PROVENANCE_INVALID. Check details[].code and param: missing fields use REQUIRED, invalid values use INVALID_VALUE, and an external source ID sent with type manual uses NOT_ALLOWED with both fields in conflicting_fields.

Merchant-authenticated checkout delivery quotes accept at most 1,000 inventory_assignments. More entries return 400 INVALID_REQUEST with details[0].code INVALID_VALUE and param inventory_assignments.

Breaking: INVENTORY_ROUTING_TOO_COMPLEX and inventory routing's 422 response are removed. Invalid inventory inputs return 400 INVALID_REQUEST with the affected field in param. Regenerate SDKs and request validators to pick up these published limits and conditions.

Breaking: GET /v1/invoices/{invoice_id}/delivery-attempts no longer returns error_message. Use failure_reason when status is failed:

• rejected: The email service refused the message, for example because of an invalid address.
• delivery_unknown: Flint could not confirm the send. Check with support before resending.
• canceled: The email was canceled before sending, for example because the invoice changed.

When status is suppressed, suppression_reason is merchant_managed_email or recipient_unsubscribed. Each reason field is omitted for other statuses. Legacy failed attempts without a stored reason return rejected.

Handle future values in both reason enums. The invoice.delivery_failed webhook continues to carry the invoice in data.object.

Readiness requirement arrays now publish the Flint requirement codes in OpenAPI. The list can grow. Treat an unknown response code as additional_account_information.

Breaking: Send targeted_requirements when creating a merchant account session. It replaces targeted_requirement_ids in the request and in readiness action recommendations. Values such as business_website are unchanged. An unknown request code returns 400 INVALID_REQUEST with an INVALID_VALUE detail at the array item.

Breaking: Merchant account sessions no longer return requirements. Read Merchant.readiness.requirements with GET /v1/merchant for the current requirements.

Breaking: Merchant and User no longer return banners. Use Merchant.readiness to find blocked capabilities and the actions available to resolve them. Reading a merchant no longer fetches a payment processor account to compute banners.

The OpenAPI descriptions now explain the merchant account statuses and identify 409 VERSION_CONFLICT as the response to a stale expected_version on a merchant update.

Breaking: POST /v1/orders/{order_id}/close on an order that kept money it collected returns 409 ORDER_HAS_COLLECTED_MONEY unless the body sends collected_money_behavior: "keep". The check counts collected money that POST /v1/refunds with the order's order_id can still return, after pending refunds. The error has param collected_money_behavior, details[0].resource_type order, details[0].resource_id, and details[0].collected_money with that amount. remediation.retry is none and a create_refund next action points at the refund. Refund the order first, or send keep to close and keep the money. Keeping changes nothing about the money, and the order stays refundable. keep is also accepted when nothing was collected, and no other value is.

Also breaking:

• Closing an order that is already closed returns 409 ACTION_NOT_ALLOWED with details[0].resource_type order and details[0].current_status closed. ORDER_ALREADY_CLOSED and ORDER_STATUS_NOT_CLOSABLE are removed, and a retained response to an earlier close that used ORDER_ALREADY_CLOSED replays as ACTION_NOT_ALLOWED.
• closed_reason_message holds only the note you sent to POST /v1/orders/{order_id}/close. Closures Flint makes no longer write text into it, so "Checkout expired before payment", "return_resolution_canceled", and "Replaced subscription renewal attempt" are gone. Read closed_reason instead.
• Closing cancels the order's payment intents that never started an attempt and still read requires_payment_method. Each sends payment_intent.canceled with cancellation_reason: "order_closed", shortly after the close commits. Nothing is refunded and the buyer isn't notified. Handle order_closed as a new value of PaymentIntent.cancellation_reason; it is system-only, and a cancel request can't send it.

New:

• Order.closed_reason says why an order closed: paid, closed_by_merchant, checkout_expired, written_off, superseded, return_resolution_canceled, or other. Order.closed_at says when. Both are present only on a closed order, are set once, and never change. ExpandedOrderSummary carries them, so an invoice's expanded order does too, and so does the order.closed payload. Orders closed earlier report the reason Flint can infer from their history. closed_reason is extensible, so treat a value you don't know like other.
• GET /v1/orders and GET /v1/me/orders accept closed_reason as one value, a repeated parameter, or comma-separated values. A value that isn't a reason returns 400 INVALID_REQUEST with details[0].code INVALID_VALUE.
• ErrorDetail.collected_money carries the refundable amount on ORDER_HAS_COLLECTED_MONEY.

An order closed by an invoice write-off keeps a payment_status that reflects what was paid, unpaid or partially_paid, because the written-off balance never arrived. Check for closed_reason: "written_off" to tell it from an order that is still collecting.

See Orders and Statuses & lifecycles.

Order line items now include a read-only fulfillment_quantities array. It has one entry for a single item, or one entry per bundle component that requires fulfillment, with bundle_component_id set on component entries. Each entry reports required_quantity and splits it into unassigned_quantity, assigned_quantity, fulfilled_quantity, canceled_quantity, and failed_quantity. Together the five add up to required_quantity.

Read unassigned_quantity to see how much a new fulfillment can still claim. It includes quantity returned by a fail with release_quantity: true; a fail with release_quantity: false counts in failed_quantity instead. Single items count in line units and bundle components in component units. The array is omitted for a line that needs no fulfillment: when every line on the order has fulfillment, a line without fulfillment_quantities needs none. If any line has no fulfillment, as with a line older than recorded fulfillment requirements, the order's obligations cannot be computed and no line has the array, so treat the order's obligations as unknown.

This change is additive. No existing field changed, and the field also appears on orders in webhook payloads.

This release prepares support for versioned partner app edits, overlapping client secrets during rotation, and identifying who revoked an install.

The public API is unchanged. The new behavior and any required integration changes will be announced when API support ships.

Partner install tokens now return 401 INVALID_CREDENTIAL with reason wrong_credential_type on these routes, on every supported API version:

• POST /v1/webhook-endpoints
• PATCH /v1/webhook-endpoints/{webhook_endpoint_id}
• DELETE /v1/webhook-endpoints/{webhook_endpoint_id}
• POST /v1/webhook-endpoints/{webhook_endpoint_id}/rotate-secret
• POST /v1/webhook-endpoints/{webhook_endpoint_id}/test-events
• POST /v1/webhook-deliveries/{webhook_delivery_id}/resend

Use the endpoint owner's API key with webhooks.write or an authorized Dashboard session. To manage partner-source endpoints, use the app owner's API key. Install tokens retain their existing webhook read access, and installed-merchant deliveries continue to require an active grant with the event's resource-read scope.

Delivery attempt reads, resend responses, and test-event action responses omit response_headers, response_body_excerpt, and response_content_type unless the caller can read the event's resource. A receiver can echo the webhook payload in these fields, so they now require the same access as the event payload. Delivery status, attempt counts, and other diagnostic fields remain available.

Breaking: POST /v1/refunds requires refund_type, which is full, amount, or targets. A body without it returns 400 INVALID_REQUEST with a REQUIRED detail and param: refund_type, and nothing is refunded. Before, a body with no amount and no named targets refunded everything that was still refundable.

Flint checks the type before it looks anything up. An unknown value returns INVALID_VALUE. A field the type doesn't accept returns NOT_ALLOWED for that field, with conflicting_fields naming refund_type and the field. amount without amount_money and targets with none of the three target lists return REQUIRED. The refund resource doesn't echo refund_type.

Breaking: tender_allocations now need refund_type: "amount" with an amount_money that equals their sum. Before, the allocations alone set the total. Named targets plus allocations use amount too. A sum that doesn't match returns INVALID_REFUND_TENDER_ALLOCATION.

Breaking: refund_method is removed from the create request and from the GET /v1/refunds filter. A body that sends it returns INVALID_REQUEST with an UNKNOWN_FIELD detail, and the query parameter returns UNSUPPORTED_QUERY_PARAM. Refunds always return to the tenders that paid, and responses still report refund_method: "original_payment".

Breaking: once Flint has recorded a refund, POST /v1/refunds returns 201 with that refund, whatever state it reached. A 4xx other than 409 IDEMPOTENCY_KEY_IN_PROGRESS now means no refund was created; that code means the first request with the key may still be running, so retry with the same key. These cases returned an error even though a refund existed and its webhooks were sent:

• 409 REFUND_INSUFFICIENT_AVAILABLE_BALANCE is retired. The response is 201 with status: "failed" and failure_reason: "insufficient_available_balance".
• A dispute or bank return found after Flint recorded the refund, which returned 409 PAYMENT_INTENT_DISPUTED or 409 NOTHING_TO_REFUND with reason payment_disputed, is now 201 with status: "failed" and failure_reason: "payment_disputed".

PAYMENT_INTENT_DISPUTED and NOTHING_TO_REFUND still return 409 when Flint refuses the request before it records a refund. A refund on a payment with no order is unchanged: it returns 201 with status: "pending" and fails later with the same reasons.

Retrying a failed refund with the same Idempotency-Key returns the same 201 and the same refund with Idempotency-Replayed: true, and Flint makes no new call to the processor. To try again after you fix the cause, create a new refund with a new key. The refund.updated and refund.failed events are sent as before.

Breaking: refund statuses split into two sets.

• Refund.status is pending, succeeded, partially_succeeded, or failed. This also applies to the buyer refund, to latest_refund_status on credit notes, and to the status filter on GET /v1/refunds and GET /v1/me/refunds. Filtering by in_transit, requires_action, or canceled returns 400 INVALID_REQUEST with an INVALID_VALUE detail, because those values never matched a refund.
• Each payment_refunds and tender_allocations entry is pending, requires_action, succeeded, failed, or canceled. in_transit is reported as pending, and partially_succeeded belongs only to the refund. Refund and Return webhook payloads use these values for payment refunds, and credit note payloads use the four refund values.

Only failed is final. A succeeded refund can become partially_succeeded or failed, and a partially_succeeded refund can become failed, when a bank rejects a credit it accepted. The Refunds guide marked partially_succeeded as final, which was wrong.

PATCH /v1/refunds/{refund_id} accepts external_reference_id as well as metadata. Leave it out to keep it, send null to clear it, and send 1 to 255 characters to set it. An empty string returns INVALID_REQUEST with an INVALID_VALUE detail. A body with neither field returns NO_FIELDS_TO_UPDATE.

Credit note refunds are unchanged: POST /v1/credit-notes/{credit_note_id}/refunds still refunds all available credit when you leave out amount_money.

To migrate:

1. Add refund_type to every POST /v1/refunds body. Use full where you left out the amount and targets, amount where you sent amount_money or tender_allocations, and targets where you named only line items, charges, or tax breakdowns.
2. When you send tender_allocations, send amount_money equal to their sum.
3. Remove refund_method from create bodies and list queries.
4. Read status on every create response. Treat failed as a refund that exists, not as an error, and remove handlers for REFUND_INSUFFICIENT_AVAILABLE_BALANCE.
5. Stop filtering refunds by in_transit, requires_action, or canceled, and treat only failed as final.

See Refunds and Idempotency.

Returns now use release_timing in requests, responses, previews, and webhooks. Replace refund_timing with release_timing; the old request field is rejected. Values are unchanged. The timing gates every resolution type, including exchanges and replacements. manual holds execution until you call POST /v1/return-resolutions/{return_resolution_id}/release.

PATCH /v1/return-resolutions/{return_resolution_id} now accepts adjustments: [...] instead of adjustment_set: { adjustments: [...] }. Each returned adjustment includes return_resolution_adjustment_id. Send that ID to keep and update a member, omit the ID to add one, and omit an existing member to remove it. Send [] to clear the collection. Omitting adjustments leaves it unchanged. An unchanged waived adjustment keeps its waiver attribution.

Replacing line_items, replacement_line_items, or adjustments requires expected_version. Replacing a return reason's category_handles also requires expected_version. A missing fence returns 400 INVALID_REQUEST with detail code REQUIRED and param: expected_version.

Return policies and return reasons no longer include supported_actions. Use policy status with PATCH to switch between active and inactive, and DELETE to retire a policy or a merchant-created reason. Flint-sourced reasons cannot be deleted.

Receipt, inspection, and disposition endpoints now have separate resource tags: return_receipts, return_inspections, and return_dispositions. Nested create descriptions name the top-level read paths. The operation ID for POST /v1/returns/{return_id}/process is now processReturn.

New: review.reopened. When the refund for a declined review fails, the review goes back to open, and Flint sends review.reopened with the review. Before this, nothing told you. The event needs the risk.read scope, like the other review events. See Resolve reviews.

New: Review.last_resolution_failure. It is null or {refund_id, failed_at}: the most recent decline whose refund failed. It stays on the review after a later decision closes it. GET /v1/refunds/{refund_id} shows why the refund failed. Decline again with a new Idempotency-Key to start another refund.

New: updated_at on reviews and fraud warnings.

Breaking: a decline whose refund already failed returns 200. The response is the open review with last_resolution_failure set, not 202. A decline returns 202 only while the review is resolving.

Breaking: a decline's 202 has no Retry-After header. Flint can't tell how long a refund takes to settle. Wait for review.closed or review.reopened, or read the review with backoff.

Breaking: reopened reviews clear refund_id. refund_id is now set only once a refund has closed the review. Before, a reopened review kept the failed refund's ID there.

Breaking: an expiring review is resolving. It had been reported as open. While Flint cancels an authorization nobody resolved in time, the review has status: "resolving", pending_action: "expire", resolution_started_at set to when expiry began, and resolution_started_by: "system". pending_action gains the value expire, and GET /v1/reviews?status=resolving returns expiring reviews instead of status=open. Approve and decline during expiry return 409 REVIEW_RESOLUTION_IN_PROGRESS instead of PAYMENT_OPERATION_IN_PROGRESS.

Breaking: PAYMENT_OPERATION_IN_PROGRESS is declared on approve and decline. It means a capture, cancellation, refund, or payment update is running on the payment. details[0].blocking_resources names the payment intent, and nothing was started, so the same request can be sent again once that operation finishes. A claim that needs recovery returns it too, where it had returned 500 INTERNAL_ERROR.

Breaking: values that were never produced are removed. Review.ip_address_location is gone, because Flint has no IP geolocation. opened_reason is rule only, and closed_reason no longer lists other. manual can return when reviews can be opened by hand.

Breaking: risk.score on a review is omitted when no score is available, as on a payment intent, instead of being null. In the OpenAPI schema, score is optional and not nullable.

Breaking: review and fraud warning webhooks use the REST shape. The data.object of review.opened, review.closed, review.reopened, fraud_warning.created, and fraud_warning.updated matches the GET response. In particular, payment_summary carries only its documented fields, and timestamps are RFC 3339 to the second.

Regenerate SDKs and validators that read the OpenAPI document.

Payments with an email address Flint accepts, such as john..doe@example.com, no longer fail risk evaluation because the address cannot be compared against an email block list. Values that cannot be stored in a risk list count as non-members. The rule still evaluates its other conditions, so an IP address on a block list still blocks the payment.

You can now disable or delete a risk rule whose saved predicate is no longer valid. You can also update its description. Activating the rule or changing its action or predicate still requires a valid predicate.

Resetting a sandbox now returns replaces_sandbox_id, the ID of the sandbox you reset. The archived sandbox exposes replaced_by_sandbox_id, the ID of its replacement, through GET /v1/developer/sandboxes/{sandbox_id} and the sandbox list. Both fields are omitted when there is no corresponding reset.

After multiple resets, each sandbox links to its immediate predecessor and replacement. Follow replaced_by_sandbox_id to recover the latest replacement ID if you lost a reset response. Retrying a reset within the idempotency window with the same Idempotency-Key still returns the original stored response.

The sandbox creation description now states that new sandboxes start empty. Send issue_test_key: true to receive a test key bound to the new sandbox.

Issued credit notes and committed Return lines now share each invoice line's credit limit. A Return request reserves its quantity and value before a resolution moves money. Declining or canceling quantity releases that reservation; voiding an issued credit note releases its correction.

Credit-note corrections beyond the shared remainder return 409 CREDIT_NOTE_AMOUNT_EXCEEDS_CREDITABLE. Creating or editing a Return beyond that remainder returns 409 RETURN_ACTION_NOT_ALLOWED. Partial corrections and Returns remain available within the remaining invoice and paid settlement value.

Existing overlapping commitments also block new Return resolution effects until the overlap is resolved. Issued invoices and historical documents stay unchanged.

Invoice settings now enforce their published limits: 4096 characters for default_memo and default_footer, 12 for invoice_number_prefix and credit_note_number_prefix, and 255 for reply_to_email and timezone. Both prefixes accept only ASCII letters, digits, underscores, and hyphens. These new checks apply to submitted fields, so you can correct older values individually and continue editing other settings.

Feedback text, buyer address fields, delivery recipient fields, risk-list values, merchant business names, payment-method domains, buyer checkout return URLs, and return decline notes now enforce their published limits before normalization. Adding whitespace or line breaks cannot bypass a limit. Selected-option validation also checks the supplied text before trimming. Risk-list values must fit the 512-character limit both before and after normalization.

Character limits count Unicode code points. Order receipt emails now accept up to 254 characters, including multibyte characters. Payment-method hostnames remain ASCII-only, with a 253-character limit.

The schema also reflects existing normalization and reference handling. Buyer address countries are trimmed and uppercased before ISO country validation. Delivery recipient phones are trimmed and accept + followed by 7 to 15 digits, with a nonzero first digit. Modifier IDs retain their existing resource validation without an uppercase-only schema pattern. Category handles retain their existing length checks and lookup errors.

POST /v1/subscriptions and create-mode POST /v1/subscription-previews now require terms. Move subscription_plan_id, quantity, billing_interval, and billing_interval_count into that object for plan subscriptions:

{
  "customer_id": "cus_123",
  "terms": {
    "type": "subscription_plan",
    "subscription_plan_id": "plan_123",
    "quantity": 1
  },
  "billing_start": { "type": "immediate" }
}

To create an offer subscription, use terms.type: "subscription_offer", an explicit billing_interval and billing_interval_count, and line_items with variant_id, subscription_offer_id, and optional quantity. Lines can come from several active offers when they share the selected interval, currency, and required delivery method.

Offer discounts are frozen when you create the subscription and apply from the first charge under the promotion's conditions. Creating or importing an offer subscription does not consume a promotion use. An unavailable promotion still blocks creation. Previews create no subscription and attach no discounts.

For subscribers who already paid elsewhere, use billing_start.type: "imported" and provide period_started_at and optional completed_cycles. Imports skip the initial charge. With a Flint-owned schedule, the next charge is at the end of the imported period. An external schedule waits for you to supply the next billing date. Using immediate collects the first payment now.

Every subscription response and subscription webhook object now includes terms_type: subscription_plan or subscription_offer. Offer subscriptions omit subscription_plan_id. Merchant subscription lists accept the terms_type filter, including repeated or comma-separated values.

Breaking: initiated_by is removed from PATCH /v1/subscriptions/{subscription_id}/billing-schedule. It never changed what Flint did, so both owner shapes (flint and external) stop accepting it, and a request that sends it returns 400 INVALID_REQUEST with an UNKNOWN_FIELD detail and param initiated_by. Remove it from your requests. The skip route keeps initiated_by, which now has a documented effect: Flint's skip email to the buyer says the buyer skipped for buyer, and that the store skipped otherwise.

Breaking: subscription.activated follows the first paid period. It used to be sent when a trial ended, before the first charge, and never for a subscription created already paid. Now it is sent once per subscription, in the same commit as its first paid period:

• A subscription that starts incomplete sends it with the first subscription.payment_succeeded, whether the start is immediate or scheduled.
• A subscription created already paid, such as from a checkout session, a payment link, or an order with subscribed lines, or one imported with billing_start.imported, sends it right after subscription.created.
• A trial that converts sends it with the first charge. When the trial ends the status becomes active while Flint charges, and Flint sends subscription.updated. A failed charge moves the subscription to past_due, and subscription.activated is sent when a later payment succeeds.

Provision on subscription.activated. trialing subscriptions also have access. Before, checkout signups had to wait for the first renewal's subscription.payment_succeeded.

Breaking: subscription.cycle_skipped is sent alone. A skip no longer sends subscription.updated beside it.

New: subscription.updated covers every change with no more specific event. Flint now sends it for changes to metadata, external_reference_id, quantity, billing interval, payment method, and line items, for a delivery hold cleared without a charge, and for the end of a trial, along with the schedule and attention changes it already covered. A change that sends a more specific subscription event, such as subscription.delivery_updated or subscription.reactivated, sends only that event. Flint sends at most one subscription.updated per change.

New: Subscription.cancellation_reason. It is buyer or merchant when that side asked to cancel, payment_failed for a canceled subscription with no recorded request, and other for a scheduled cancellation with no recorded requester. It is present while cancel_at_period_end is true or the status is canceled, and absent otherwise. The set of values can grow.

New: Subscription.delivery.updated_by. It is buyer, merchant, or migration, and says who last changed the delivery preference. It is absent until the preference changes after creation. The set of values can grow.

Docs corrected. Subscription events carry the subscription in data.object and no event-only fields. Earlier guides listed reason, initiated_by, changed_by, and cancel_at on some events, and those never arrived. Read cancellation_reason, delivery.updated_by, and current_period_end_at on the subscription instead. Flint does not record who undid a scheduled cancellation.

See Subscription billing and the webhook event catalog.

Response warnings now always include code, severity, and message. Severity is warning or critical. Accept new warning codes as they are added.

Update code that matches these renamed warnings:

The promotion_declined and promotion_removed codes keep their names.

Warnings no longer include context or resource. Read resource_type with resource_id when a warning identifies a resource. Read capability and current_deadline_at directly on merchant readiness warnings, previous_stage and stage on risk rule stage warnings, and removed_scopes on API key scope warnings. These fields are included when they apply to the warning.

Risk previews return the same warning shape in data.warnings that successful requests use in meta.warnings. The separate RiskRuleWarning schema has been removed. Regenerate clients from the updated OpenAPI document and replace reads of the removed fields with the typed fields above.

Breaking: stale versions are VERSION_CONFLICT. When the expected_version you send no longer matches, these writes return 409 VERSION_CONFLICT instead of 409 CONCURRENT_MODIFICATION:

• PATCH and DELETE on products, product variants, and bundles, including updates that replace images.
• Every subscription write that takes expected_version: PATCH, line items, Order now, pause, resume, cancel, reactivate, the payment method change, the billing schedule update, and skip, on merchant routes and on the buyer routes under /v1/me.
• PATCH and DELETE on subscription plans. A plan DELETE now compares expected_version before it archives, so a stale value no longer depends on a race.
• PATCH and DELETE on risk rules.

param is expected_version. details[0] carries resource_type (product, product_variant, bundle, subscription, subscription_plan, or risk_rule), resource_id, and current_version, the version Flint saw. Read the resource, rebuild the change, and send it with a new Idempotency-Key. Modifier group and modifier set conflicts now carry current_version too.

Breaking: CONCURRENT_MODIFICATION means a lost race, not a stale version. Flint returns it when another write landed while your request ran and your basis was still current: you sent no expected_version, or the one you sent still matches. It has no param, details[0] names the resource_type and resource_id, and nothing was applied. Retry the same request with the same Idempotency-Key. Updates that replace images on products, variants, bundles, and plans are the exception: a lost race there returns VERSION_CONFLICT, even when current_version equals the version you sent, so read the resource again and send the rebuilt request with a new Idempotency-Key. Before this change, subscription and plan writes stored this error against the key, so the same-key retry replayed the conflict for 24 hours. It now runs again.

Breaking: schedule changes and skips. A billing schedule update or skip that loses the race twice without an expected_version returns 409 CONCURRENT_MODIFICATION instead of SUBSCRIPTION_SCHEDULE_MUTATION_NOT_ALLOWED. When SUBSCRIPTION_SCHEDULE_MUTATION_NOT_ALLOWED is returned for a status, details[0].current_version is now the subscription's version, not the billing schedule revision.

Breaking: RISK_CONTROL_CONFLICT is removed. It covered a stale rule version, an archived rule or list, and internal races. They now return:

Breaking: published fence requirements. The OpenAPI schemas now publish "required when this field is present" fences, such as expected_version with images or options, as dependentRequired instead of anyOf with not. Regenerate SDKs and validators that read the old construct. PATCH /v1/inventory-counts/{inventory_count_id} now lists expected_version as required, and a request without it returns 400 INVALID_REQUEST with details[0].code REQUIRED and param expected_version.

A response replayed for an Idempotency-Key first used before this change returns the new code. A replayed stale-version conflict is VERSION_CONFLICT without current_version when the original didn't record it, and a replayed RISK_CONTROL_CONFLICT is VERSION_CONFLICT. Read the resource, then retry with a new key.

Orders, order line items, and delivery selections keep their current conflict codes for now. See Error handling.

This continues the stale version rollout for the remaining writes that take an expected_version or expected_api_version.

Breaking: INVOICE_PAYMENT_TERM_CHANGED is removed. PATCH and DELETE /v1/invoice-payment-terms/{invoice_payment_term_id} now return 409 VERSION_CONFLICT when expected_version is stale. param is expected_version, and details[0] carries resource_type invoice_payment_term, resource_id, and current_version, the term's version. DELETE now compares expected_version before it archives the term. Read the term and retry with its version and a new Idempotency-Key. A write that loses a race while your version still matches, or with no version sent, returns 409 CONCURRENT_MODIFICATION.

Breaking: customer and settings races are classified by your version. A stale expected_version on PATCH /v1/customers/{customer_id} or PATCH /v1/settings returns 409 VERSION_CONFLICT with param expected_version, the resource reference, and current_version. Customers use resource_type customer. Settings use resource_type settings and the settings ID as resource_id, and a stale catalog.expected_version is reported the same way with that param. When another write lands while the request runs and your version, if you sent one, still matches, the response is 409 CONCURRENT_MODIFICATION without param. Customer writes without a version used to return VERSION_CONFLICT for this race. Nothing changed. Retry the same request with the same Idempotency-Key.

Conflicts that lacked a current version now carry it. When another write wins after Flint compares your expected_version, the 409 VERSION_CONFLICT includes the resource reference and details[0].current_version:

• Invoice updates, issue, void, mark uncollectible, reminders_paused, public link regeneration, and recording or reversing a manual payment, with resource_type invoice. If the race leaves your version current, these return 409 CONCURRENT_MODIFICATION without param, except issue, which returns 409 INVOICE_ISSUE_IN_PROGRESS. Retry either with the same request and Idempotency-Key.
• Credit note updates, issue, allocations, allocation reversals, voids, and refunds, with resource_type credit_note.
• Merchant profile and payment link updates, which return 409 CONCURRENT_MODIFICATION instead when your version is still current.
• Modifier group and modifier set updates.

Breaking: credit note refunds retry payment changes. A refund, or an issue with a refund, that finds the invoice's payments changed while the credit note's version still matches your expected_version used to return VERSION_CONFLICT at once. Flint now retries for up to three attempts in total, as it already did without a version, and then returns 409 CONCURRENT_MODIFICATION with reason credit_note_refund_retry_exhausted. A version that moved still returns VERSION_CONFLICT with the new current_version.

Breaking: invoice void contention has no param. When a dependent resource changes while a void runs and your version, if any, still matches, void returns 409 CONCURRENT_MODIFICATION without param: invoice_id. details[0] names the invoice. Nothing is voided. Retry the same request with the same Idempotency-Key. A stale expected_version returns VERSION_CONFLICT with current_version.

New fact: current_api_version. A stale expected_api_version on a webhook endpoint or partner app update returns 409 VERSION_CONFLICT with param expected_api_version and details[0].current_api_version, the API version the resource is pinned to now. The October 18 entry promised this fact, but Flint never returned it. These conflicts have no current_version. They carry resource_type webhook_endpoint or partner_app and the resource's resource_id.

Gift card redemption create names the gift card. A stale expected_version on POST /v1/gift-card-redemptions now includes resource_type gift_card and the card's resource_id. Previously resource_id was missing because the path has no gift card ID.

Delivery configuration conflicts name the target.

• A stale expected_version on POST /v1/delivery-revocations includes resource_type (delivery_method or delivery_rate_callback) and the target's resource_id.
• A stale expected_catalog_default_version on POST /v1/delivery-profiles/{delivery_profile_id}/assign-to-unconfigured returns VERSION_CONFLICT with resource_type settings and current_version, the catalog version. resource_id is the settings ID and is omitted when the environment has no settings record yet.

A response replayed for an Idempotency-Key first used before this change returns the new code. A replayed INVOICE_PAYMENT_TERM_CHANGED is VERSION_CONFLICT. Read the resource, then retry with a new key.

Orders, order line items, and delivery selections keep their current conflict codes for now. See Error handling.