Skip to content
Changelog

Week of October 19, 2026

174 changes to the Flint API, SDKs, and docs, newest first, from October 19, 2026 to October 25, 2026. The newest changes are on the changelog.
  • Breaking change
  • API
  • Developers

API scope names and catalog metadata#

Four scope names have changed. Their permissions stay the same, and stored grants use the new names automatically:

Previous nameCurrent name
commerce.return_policies.writecommerce.returns.policies.write
commerce.return_reasons.writecommerce.returns.reasons.write
commerce.inventory_policies.writecommerce.inventory.policies.write
commerce.inventory_locations.writecommerce.inventory.allocation.write

Breaking: Send the current names when creating or updating grants. The unused payments.payment_options.read scope is retired. Stored grants drop it, and new grants reject it.

OpenAPI publishes scope descriptions in every scope enum and a root x-flint-scopes catalog with access, allowed key modes, partner-install eligibility, and scopes that imply each permission. Operations publish input-dependent permissions in x-flint-conditional-scopes.

  • API
  • Customers
  • Subscriptions
  • Returns

Read buyer resources and the choices their actions accept#

Customer sessions can now retrieve a buyer's referenced resources:

  • GET /v1/me/payments/{payment_intent_id}
  • GET /v1/me/refunds/{refund_id}
  • GET /v1/me/fulfillments/{fulfillment_id}
  • GET /v1/me/shipments/{shipment_id}
  • GET /v1/me/packages/{package_id}
  • GET /v1/me/return-resolutions/{return_resolution_id}

These reads accept no query parameters and require a full customer session. Missing resources, another buyer's resources and resources in another environment return 404 RESOURCE_NOT_FOUND naming the requested resource. Shipment and package errors do not reveal the parent order. Payment reads omit processor client secrets, collection details and the current payment action.

Available subscription actions now include their accepted choices. cancel carries cancellation_reasons, timing and an optional retention_offer; pause carries an optional max_pause_duration_cycles. Sending a cancellation reason remains optional. A pause with a maximum requires a duration from 1 to that maximum; without one, omitting the duration pauses until the buyer resumes.

Cancellation follows the subscription's existing lifecycle rules. end_of_period uses its next cancellation boundary, including trial end or a scheduled retry. buyer_chooses also accepts immediate cancellation. For immediately, send cancel_immediately: true; states without a boundary require it. An expired delivery hold ends immediately even when the flag is omitted.

Available return pay_balance actions now include return_resolution_ids in creation order. Payable completion blockers keep their existing resolution_pending or resolution_requires_action code. Retrieve each resolution to read its buyer_payment_amount_money, then create a checkout session for each resolution the buyer wants to pay.

Options appear only on the matching available action. Merchant reads and webhooks continue to carry an empty buyer_actions array.

  • API

Catalog field descriptions#

Product, variant, bundle, category, modifier, promotion, and promotion code schemas now describe every field, including shared response fields. Modifier fields explain how set overrides apply and how to read groups owned by a set. Product list results explain which variant appears in matched_variant.

Product update documentation now names category_handles as the category replacement field. Product, variant, and bundle update schemas also describe the public INVALID_REQUEST response with an INVALID_VALUE detail when a field that cannot be cleared receives null. Promotion schedule updates clarify that timezone is display metadata and can be cleared with null.

  • Breaking change
  • API
  • Promotions
  • Api-keys
  • Webhooks

Configuration versions and conditional write fences#

Promotions, promotion codes, categories, webhook endpoints, API keys, devices, organizations, and risk lists now return a positive version. Partner apps retain their existing counter. Send that value as expected_version when changing the resource to detect edits made since your read. A stale assertion returns 409 VERSION_CONFLICT with the current version and after_refresh retry guidance. Keep your draft, read the resource again, and reconcile the change before submitting it.

Breaking: partner app versions and assertions now use positive uint64 values. Promotion PATCH requests must include expected_version whenever they supply eligibility_rules or application_method. API key PATCH requests must include it with scopes. Webhook endpoint PATCH requests must include it with enabled_events, event_sources, or installed_merchant_modes. An empty collection still requires the fence. Existing null-clearing rules continue to apply.

Optional fences on scalar updates and supported lifecycle commands are additions. DELETE requests accept one expected_version query parameter. API version pin assertions remain independent: when supplied, both assertions must pass. Organization ownership transfer continues to return the membership defined by its existing contract.

A version orders committed changes to that resource's owned state, including persisted promotion usage, category counts, and risk list item counts. Expanded children carry their own versions. A schedule boundary, webhook delivery health observation, or API key last-used timestamp does not advance a configuration counter.

Retained responses recorded before activation use baseline version 1; resources already present at activation start above that baseline. Distinct historical snapshots can share version 1, so it does not order those historical snapshots against each other. New resources start at version 1.

  • Breaking change
  • API
  • Settings
  • Webhooks

Custom domains have their own resource#

Manage hostnames through /v1/custom-domains. Each domain has a custom_domain_id beginning with cdom_. List domains, create one with {type, hostname}, read it by ID, start DNS and provider checks with POST /v1/custom-domains/{custom_domain_id}/validate, or archive it with DELETE /v1/custom-domains/{custom_domain_id}.

These changes apply to every supported API version:

  • Settings no longer accepts or returns checkout.custom_domain, customer_account.presentation.custom_domain, checkout_domain_status, or customer_account_domain_status. The settings domain-validation route is removed.
  • To replace a hostname, archive its domain and create a new one. Archived domains remain readable with their DNS records and redirect expiry. List responses exclude them unless the status filter includes archived.
  • Remove the customer account domain before switching to merchant_hosted mode or clearing the customer account settings section. Those settings changes return RESOURCE_IN_USE with the blocking domain ID until you do.
  • The custom_domain.status_changed webhook now contains the same CustomDomain resource as GET, including its ID. Use type, status, and DNS record type in place of domain_type, domain_status, and dns_record_type. The removal status is archived, and its status_reason is null.
  • Validating an archived domain returns ACTION_NOT_ALLOWED with reason: archived. A customer account mode conflict returns ACTION_NOT_ALLOWED with reason: customer_account_mode_conflict. Checkout domains require a live credential; FORBIDDEN includes reason: live_mode_required. Repeated validation within 60 seconds returns RATE_LIMIT_EXCEEDED with Retry-After.
  • Breaking change
  • API
  • Errors
  • Sandboxes
  • Api-keys
  • Webhooks

Developer platform errors use shared codes and reasons#

Superseded by Payment method domain changes recover after interrupted requests, Webhook refusals name the recovery action.

These changes apply to every supported API version, including retained idempotency failures and request-log reads. Replace branches on the retired codes with the codes and details[0].reason values below. Validation failures use details[].code instead of a reason.

Retired codeReplacement
ACTIVE_DEMO_SESSION_EXISTS409 ALREADY_EXISTS
API_KEY_ALREADY_REVOKED409 ACTION_NOT_ALLOWED with reason already_applied
API_KEY_CHANGED409 VERSION_CONFLICT
CUSTOM_DOMAIN_NOT_CONFIGURED409 ACTION_NOT_ALLOWED with reason configuration_required
CUSTOM_DOMAIN_NOT_VERIFIED409 ACTION_NOT_ALLOWED with reason status_not_reached
CUSTOM_DOMAIN_SUBSCRIPTION_REQUIRED409 ACTION_NOT_ALLOWED with reason configuration_required
CUSTOM_DOMAIN_UNAVAILABLE409 ALREADY_EXISTS
DEFAULT_SANDBOX_CANNOT_BE_ARCHIVED409 ACTION_NOT_ALLOWED with reason unsupported_state
DEFAULT_SANDBOX_CANNOT_BE_RESET409 ACTION_NOT_ALLOWED with reason unsupported_state
DEMO_SESSION_NOT_CURRENT409 VERSION_CONFLICT
DEMO_SESSION_SECRET_REPLAY_EXPIRED409 ALREADY_EXISTS
DEVICE_ARCHIVED409 ACTION_NOT_ALLOWED with reason archived
DEVICE_LOCATION_MISMATCH400 INVALID_REQUEST with detail code NOT_ALLOWED
FILE_NOT_UPLOADED409 ACTION_NOT_ALLOWED with reason status_not_reached
IMAGE_ASSET_NOT_ATTACHABLE409 ACTION_NOT_ALLOWED with reason terminal_status
IMAGE_INGESTION_EXPIRED409 ACTION_NOT_ALLOWED with reason image_ingestion_restart_required
IMAGE_INGESTION_IN_PROGRESS409 IDEMPOTENCY_KEY_IN_PROGRESS
IMAGE_INGESTION_RESTART_REQUIRED409 ACTION_NOT_ALLOWED with reason image_ingestion_restart_required
IMAGE_NOT_ATTACHABLE409 ACTION_NOT_ALLOWED with reason unsupported_state
IMAGE_OWNER_NOT_MUTABLE409 ACTION_NOT_ALLOWED with reason unsupported_state
IMAGE_PROCESSING_CAPACITY_EXCEEDED503 SERVICE_UNAVAILABLE; reason image_ingestion_restart_required only when a new ingestion is required
IMAGE_PROCESSING_FAILED500 INTERNAL_ERROR or 503 SERVICE_UNAVAILABLE; reason image_ingestion_restart_required only when a new ingestion is required
IMAGE_PROCESSING_TIMEOUT504 REQUEST_TIMEOUT; reason image_ingestion_restart_required only when a new ingestion is required
IMAGE_REVISION_MISMATCH409 VERSION_CONFLICT
IMAGE_SOURCE_TIMEOUT504 REQUEST_TIMEOUT; reason image_ingestion_restart_required only when a new ingestion is required
IMAGE_SOURCE_UNAVAILABLE502 EXTERNAL_SERVICE_ERROR; reason image_ingestion_restart_required only when a new ingestion is required
IMAGE_STORAGE_QUOTA_EXCEEDED409 LIMIT_REACHED with reason image_storage
LIST_RESERVED409 ACTION_NOT_ALLOWED with reason managed_externally
ORGANIZATION_CYCLE400 INVALID_REQUEST with detail code INVALID_VALUE
ORGANIZATION_NOT_ACTIVE409 ACTION_NOT_ALLOWED with reason terminal_status
PAYMENT_METHOD_DOMAIN_OPERATION_IN_PROGRESS409 OPERATION_IN_PROGRESS while another registration change is running
PROFILE_UPDATE_STATUS_UNKNOWN502 EXTERNAL_SERVICE_ERROR with reason outcome_unknown
REPORT_DOWNLOAD_EXPIRED410 ACTION_NOT_ALLOWED with reason terminal_status
RISK_RULE_LIMIT_REACHED409 LIMIT_REACHED with reason enabled_risk_rules
RULE_RESERVED409 ACTION_NOT_ALLOWED with reason managed_externally
SANDBOX_ARCHIVED409 ACTION_NOT_ALLOWED with reason archived
SANDBOX_INACTIVE409 ACTION_NOT_ALLOWED with reason unsupported_state
SENSITIVE_IDEMPOTENCY_RESULT_INVALID500 IDEMPOTENCY_RECOVERY_REQUIRED
WEBHOOK_DELIVERY_IN_FLIGHT409 ACTION_NOT_ALLOWED with reason in_progress
WEBHOOK_ENDPOINT_NOT_ACTIVE409 ACTION_NOT_ALLOWED with reason unsupported_state
WEBHOOK_ENDPOINT_NOT_SUBSCRIBED409 ACTION_NOT_ALLOWED with reason configuration_required
WEBHOOK_EVENT_PAYLOAD_EXPIRED409 ACTION_NOT_ALLOWED with reason terminal_status
WORKLOAD_IDENTITY_LIMIT_REACHED409 LIMIT_REACHED with reason workload_identities

For the unsupported_state replacements above, retained errors without the required state return ACTION_NOT_ALLOWED with reason not_offered, retry none, and their recorded param. Current errors keep unsupported_state with the actual current_status.

Most HTTP statuses and retry modes stay the same. The exceptions are:

  • DEVICE_LOCATION_MISMATCH moves from 409 to 400 INVALID_REQUEST, with detail code NOT_ALLOWED on device_id.
  • ORGANIZATION_CYCLE moves from 409 to 400 INVALID_REQUEST, with detail code INVALID_VALUE on parent_organization_id.
  • IMAGE_STORAGE_QUOTA_EXCEEDED moves from 429 to 409 LIMIT_REACHED, with reason image_storage and retry none. Read details[0].quota for used and reserved storage, and next_expiration_at when available. Remove unused images or wait for storage to expire; a throttle retry loop will not clear the quota.
  • WEBHOOK_DELIVERY_IN_FLIGHT moves from retry same_request to none and no longer sends Retry-After. The key retains the refusal. Wait for the running attempt, read its result, and use a new key only if another resend is needed.
  • A stale demo-session reset now has retry after_refresh. Read the current session and rebuild the reset with a new key. An existing-session conflict names the session in details[0].current_resource, replacing demo_session_id.

Image failures keep the retry guidance for each ingestion attempt. With reason image_ingestion_restart_required, retry is none: correct the cause if needed, then start a new ingestion with a new Idempotency-Key. Without that reason, the 5xx image failures above keep retry same_request. IDEMPOTENCY_KEY_IN_PROGRESS also uses same_request.

If image validation failures and a source timeout occur together, the response stays 400 INVALID_REQUEST with one INVALID_VALUE detail per failed image. The timeout detail also has retry none. Correct the invalid images and send the request with a new key, rather than resending the whole invalid request unchanged.

EXTERNAL_SERVICE_ERROR with reason outcome_unknown keeps the profile update's runtime status 502 and retry none; its old API declaration incorrectly listed 503. Read the profile to learn whether the update took effect before sending another update.

A refused webhook resend uses ACTION_NOT_ALLOWED with reason in_progress and retry none. Wait for the running attempt and read its result before deciding whether another resend is needed. An expired report download keeps status 410 under ACTION_NOT_ALLOWED with reason terminal_status.

A custom-domain collision uses ALREADY_EXISTS with param set to the submitted field: checkout.custom_domain or customer_account.presentation.custom_domain. Flint does not expose another account's resource in current_resource.

Checking a custom domain validates the hostname already stored in settings; the route accepts only domain_type in the path. A missing configured hostname returns ACTION_NOT_ALLOWED with reason configuration_required and no param.

Attaching a missing image, or one outside the request's merchant or environment, now returns 404 RESOURCE_NOT_FOUND with resource_type: image and no resource_id. An image or receiving resource whose state blocks attachment returns 409 ACTION_NOT_ALLOWED with reason unsupported_state and its actual current_status.

  • Breaking change
  • API
  • Devices

Device registration reports duplicate fingerprints as conflicts#

POST /v1/devices now returns 201 with a plain Device in data. The already_existed field has been removed, and duplicate registrations no longer return 200.

Creating a device with a hardware_fingerprint held by an active device returns 409 ALREADY_EXISTS, with param: "hardware_fingerprint" and reason: "hardware_fingerprint_already_exists" in details[0]. The current_resource detail names the existing device. The request changes nothing, including the existing device's name, location, and metadata. To re-register hardware, look it up with GET /v1/devices?hardware_fingerprint=..., then PATCH it, or create a device if none is found. Use Idempotency-Key for network retries.

Fingerprints must contain 1 to 255 characters with no leading or trailing whitespace. They match exactly, including case and accents. The list filter uses the same comparison and finds at most the one active device holding the fingerprint. Archived devices release their fingerprints for new registrations.

Device lists now use page tokens bound to the sort order and filters, so subsequent pages continue in the requested order without repeating earlier devices. Earlier page tokens are rejected with 400 INVALID_REQUEST on page_token; restart the list without a token.

  • Breaking change
  • API
  • Errors
  • Invoices
  • Credit-notes

Invoice errors use shared codes and reasons#

Invoice and credit note errors now use the codes below. HTTP statuses and retries stay the same except the payment-term currency mismatch, which is 400 INVALID_REQUEST with a NOT_ALLOWED detail. param names the request field to change. Stored-state refusals omit resource selector parameters that the caller cannot correct in that request. A rotated invoice access token names the Authorization header. When an older stored refusal would require unsupported_state but did not retain its lifecycle status, it uses not_offered and omits current_status.

Previous codeCodeReason or detail
AMOUNT_EXCEEDS_BALANCELIMIT_EXCEEDED
CREDIT_NOTE_ALLOCATION_ALREADY_REVERSEDACTION_NOT_ALLOWEDalready_applied
CREDIT_NOTE_ALLOCATION_EXCEEDS_BALANCELIMIT_EXCEEDED
CREDIT_NOTE_AMOUNT_EXCEEDS_CREDITABLELIMIT_EXCEEDED when creating or replacing lines; ACTION_NOT_ALLOWED at issuenot_offered at issue
CREDIT_NOTE_ISSUE_IN_PROGRESSOPERATION_IN_PROGRESS
CREDIT_NOTE_NOT_DRAFTACTION_NOT_ALLOWEDterminal_status for a void note; otherwise unsupported_state
CREDIT_NOTE_NOT_ISSUEDACTION_NOT_ALLOWEDterminal_status for a void note; otherwise status_not_reached
CREDIT_NOTE_REFUND_EXCEEDS_BALANCELIMIT_EXCEEDED
CUSTOMER_PAYMENT_TERM_UNAVAILABLEACTION_NOT_ALLOWEDconfiguration_required
INVALID_INVOICE_LATE_FEE_AMOUNTACTION_NOT_ALLOWEDnot_offered
INVOICE_AUTOPAY_PAYMENT_METHOD_REQUIREDACTION_NOT_ALLOWEDconfiguration_required
INVOICE_BALANCE_CHANGEDVERSION_CONFLICT
INVOICE_CHECKOUT_REPLACEMENT_NOT_ALLOWEDACTION_NOT_ALLOWEDmanaged_by_owner
INVOICE_COLLECTION_BLOCKEDACTION_NOT_ALLOWEDinventory_wait
INVOICE_COLLECTION_CHANGEDVERSION_CONFLICT
INVOICE_COLLECTION_MODE_UNSUPPORTEDACTION_NOT_ALLOWEDnot_offered
INVOICE_ISSUE_IN_PROGRESSOPERATION_IN_PROGRESS
INVOICE_LATE_FEE_NOT_COLLECTIBLEACTION_NOT_ALLOWEDnot_offered when no eligible balance or late fee remains; otherwise unsupported_state
INVOICE_LATE_FEE_NOT_DUEACTION_NOT_ALLOWEDstatus_not_reached
INVOICE_LATE_FEE_POLICY_REQUIREDACTION_NOT_ALLOWEDnot_offered
INVOICE_LINK_UNAVAILABLEACTION_NOT_ALLOWEDterminal_status for a rotated token; configuration_required for a merchant link to regenerate
INVOICE_NOT_COLLECTIBLEACTION_NOT_ALLOWEDfield_locked for reminder controls; not_offered when an open invoice has no collectible balance; otherwise unsupported_state
INVOICE_NOT_CREDITABLEACTION_NOT_ALLOWEDstatus_not_reached for draft; terminal_status for void
INVOICE_NOT_DRAFTACTION_NOT_ALLOWEDunsupported_state
INVOICE_NOT_ISSUEDACTION_NOT_ALLOWEDstatus_not_reached
INVOICE_NOT_MARKABLE_UNCOLLECTIBLEACTION_NOT_ALLOWEDunsupported_state
INVOICE_NOT_REVERSIBLEACTION_NOT_ALLOWEDunsupported_state
INVOICE_NOT_VOIDABLEACTION_NOT_ALLOWEDunsupported_state
INVOICE_PAYMENT_ALREADY_SETTLEDACTION_NOT_ALLOWEDalready_applied
INVOICE_PAYMENT_ATTEMPT_ACTIVEPAYMENT_ATTEMPT_ACTIVE
INVOICE_PAYMENT_NOT_APPLIEDACTION_NOT_ALLOWEDin_progress
INVOICE_PAYMENT_PROCESSINGOPERATION_IN_PROGRESS
INVOICE_PAYMENT_RESOLVINGOPERATION_IN_PROGRESS
INVOICE_PAYMENT_TERM_CURRENCY_MISMATCHINVALID_REQUESTNOT_ALLOWED
INVOICE_PAYMENT_TERM_UNAVAILABLEACTION_NOT_ALLOWEDnot_offered
INVOICE_REMINDER_CHANGEDVERSION_CONFLICT
INVOICE_SCHEDULE_ENTRY_NOT_COLLECTIBLEACTION_NOT_ALLOWEDstatus_not_reached
INVOICE_TAX_SNAPSHOT_MISSINGACTION_NOT_ALLOWEDinvoice_finalized
INVOICE_TAX_SNAPSHOT_STALEACTION_NOT_ALLOWEDinvoice_finalized
ORDER_ALREADY_HAS_ACTIVE_INVOICEALREADY_EXISTS
ORDER_ALREADY_HAS_PAYMENTSACTION_NOT_ALLOWEDpayment_collected
ORDER_ALREADY_HAS_REFUNDSACTION_NOT_ALLOWEDpayment_collected
ORDER_HAS_ACTIVE_PAYMENT_INTENTRESOURCE_IN_USE
ORDER_HAS_MANUAL_PAYMENTSRESOURCE_IN_USE
ORDER_HAS_NO_LINE_ITEMSACTION_NOT_ALLOWEDconfiguration_required
ORDER_HAS_OPEN_CHECKOUTRESOURCE_IN_USE

ORDER_ALREADY_HAS_ACTIVE_INVOICE now identifies the active invoice in current_resource, without a blocker list or count. Invoice checkout ownership refusals use the same reference. Invoice payment conflicts identify their attempt with resource_type, resource_id, and current_status; invoice_payment_attempt_id, payment_attempt_status, and is_resumable are omitted. Processing waits omit the blocker count. Never start another payment while the existing attempt may still succeed.

The credit allocation constraint that preserves an unpaid tip now reports maximum_money for the submitted amount_money, replacing required_money, current_money, and gap_money. Stored older refusals omit those estimates because the submitted allocation was not retained with them. The amount-only manual reversal code was already retired when reversals became payment resources.

  • Breaking change
  • API
  • SDK

Consistent operation names and reference pages#

These operation IDs change across all supported API versions. Update generated SDK method references and any CLI bindings that use the old IDs. HTTP methods, paths, request bodies, and response bodies stay the same.

Previous operation IDCurrent operation ID
addOrderLineItemscreateOrderLineItems
addOrderChargecreateOrderCharge
addReturnLineItemcreateReturnLineItem
addRiskListItemscreateRiskListItems
assessInvoiceLateFeecreateInvoiceLateFee
publishReturnPolicyRevisioncreateReturnPolicyRevision
waiveReturnLineInspectionwaiveReturnLineItemInspection
getRiskRuleAttributeRegistrygetRiskRuleAttributes
revokeOrganizationMembershipremoveOrganizationMembership
rotateWebhookSecretrotateWebhookEndpointSecret

Buyer subscription operations use the customer_account tag. Email preference link lookup and unsubscribe use customers. The current order delivery selection uses delivery_selections. Merchant account session creation and refresh use merchant_account_sessions. Authentication context uses api_keys.

Response header documentation now includes WWW-Authenticate on Bearer-authenticated operations' 401 responses and Retry-After on retryable responses that send it. Retry-After uses one integer schema with a minimum of one second. The OpenAPI document no longer lists 499, which is recorded only in request logs when a caller disconnects.

  • Breaking change
  • API
  • Partners

Partner apps can be edited, deleted, and removed by merchants#

Partner apps now have a version. Use PATCH /v1/developer/partner/apps/{partner_app_id} to change the name, redirect URIs, permission manifest, default requested permissions, or API version. Replacing permission_manifest requires expected_version. An existing permission can drop scopes but cannot gain them. Removing or narrowing a permission narrows existing environment grants immediately, so tokens with removed scopes stop working. Adding a permission leaves existing grants unchanged until the merchant authorizes again.

DELETE /v1/developer/partner/apps/{partner_app_id} archives an app. Revoke its active installs first. Archived apps remain readable, but cannot be installed, exchange tokens, or receive events. Delete their webhook endpoints separately.

Client secret rotation keeps the previous secret valid for 24 hours by default. Set expire_previous_secret_at to choose an expiry up to seven days ahead, or a time at or before now to stop the previous secret immediately. The response includes the app, its new client_secret, and previous_secret_expires_at while the overlap is active. A second rotation ends the oldest secret immediately.

Merchants can list apps installed on their account with GET /v1/partner-app-installs and disconnect one with POST /v1/partner-app-installs/{partner_app_install_id}/revoke. A merchant revocation sends partner_app_install.revoked with revoked_by: merchant. These routes span live and test mode and require a live API key or an authorized dashboard session.

Partner-side install lists accept merchant_id and status filters. Merchant-side lists accept partner_app_id and status. Installs include partner_app_id, the current partner_app_name, and revoked_by when known. Each environment grant includes granted_permissions from the app's current manifest. App lists exclude archived apps unless requested with the status filter.

Breaking changes: visibility and app_type are removed. Install-level granted_scopes is removed; read each environment grant's scopes and permissions instead. Install statuses are now pending_exchange, active, and revoked. Secret rotation returns the full PartnerAppWithSecret. Empty PATCH bodies are rejected.

  • Breaking change
  • API
  • Errors
  • Payments
  • Checkout

Payment errors use shared codes and resource facts#

Payment, payment-method, checkout, and gift-card errors now use shared codes with details[0].reason and resource facts. Replace branches on the retired payment codes with the new code and reason, and read param for the request field to change.

  • ORDER_PAYMENT_ATTEMPT_ACTIVE and PAYMENT_ATTEMPT_REQUIRES_CAPTURE become 409 PAYMENT_ATTEMPT_ACTIVE. Read the attempt's resource_type, resource_id, current_status, and supported_actions. An order attempt in requires_capture lists capture and cancel, plus resume only when recorded as resumable. Retained refusals use the recorded status and resumability to list those actions. Resolve the attempt before starting another payment.
  • PAYMENT_IN_PROGRESS and PAYMENT_OPERATION_IN_PROGRESS become 409 OPERATION_IN_PROGRESS. Retry the same request with the same Idempotency-Key after Retry-After when present.
  • A pending saved card returns 409 ACTION_NOT_ALLOWED with reason status_not_reached and retry none. After payment_method.activated, send a new request with a new key. The original key replays the refusal.
  • A missing, inactive, mismatched, or on-session-only card stored on a subscription returns 409 ACTION_NOT_ALLOWED with reason configuration_required and resource_type: payment_method. A stored card also has resource_id. These failures have no param; update the subscription's card before charging again. A missing or mismatched card supplied when creating or updating a subscription returns 400 INVALID_REQUEST, with detail code REQUIRED or NOT_ALLOWED on payment_method_id.
  • PAYMENT_LEG_SELECTION_REQUIRED becomes 400 INVALID_REQUEST, detail code REQUIRED, and param: payment_intents. Select an intent from details[0].selectable_resources. The error no longer includes current_money; each intent includes its amount.
  • Capture limits use 409 LIMIT_EXCEEDED and maximum_money instead of capturable_money. Checkout tax quotas use 409 LIMIT_REACHED with reason checkout_tax_calculations instead of 429.
  • Stale checkout replacement and gift-card allocation assertions, plus payment amount or confirmation state changes, use 409 VERSION_CONFLICT. Refresh the resource and send a reviewed request with a new key. Session and payment references use resource_type/resource_id or current_resource; blocking payment intents use blocking_resources.
  • Gift-card purchase refusals use 409 ACTION_NOT_ALLOWED. A locked recipient uses reason field_locked with param: gift_card_recipient; other immutable purchase terms use not_offered. A refusal because funding has been collected, with no request field to change, uses payment_collected without param.

Other stored-state refusals use ACTION_NOT_ALLOWED with a reason such as terminal_status, already_applied, or unsupported_state. A saved card in use returns RESOURCE_IN_USE. Payment option restrictions use PAYMENT_OPTION_UNAVAILABLE; exhausted promotions use PROMOTION_DECLINED with reason exhausted. Follow remediation.retry and remediation.next_actions rather than retrying every 409.

Retired codes map to the following responses. Reason names details[0].reason; Detail names details[0].code. Branches use facts recorded with the refusal.

<!-- payment-error-migration-inventory:start --> <!-- Generated from the P5 code mapping, payment compatibility rules, retained renderer, and public error registry. -->

Retired codeBranch or recorded factsNew responseReason or detailRetry
ACH_TRANSACTION_PURPOSE_UNRESOLVEDAll occurrences409 PAYMENT_OPTION_UNAVAILABLEReason transaction_purpose_unresolvednone
AMOUNT_MISMATCHAll occurrences409 ACTION_NOT_ALLOWEDReason reconciliation_requirednone
CAPTURE_AMOUNT_EXCEEDS_CAPTURABLEAll occurrences409 LIMIT_EXCEEDEDNonenone
CAPTURE_AMOUNT_MISMATCHAll occurrences409 ACTION_NOT_ALLOWEDReason already_appliednone
CHECKOUT_CREDENTIAL_CHANGEDAll occurrences409 VERSION_CONFLICTNoneafter_refresh
CHECKOUT_CUSTOMER_CHANGEDAll occurrences409 ACTION_NOT_ALLOWEDReason terminal_statusnone
CHECKOUT_CUSTOMER_NOT_SET_ON_ORDERAll occurrences409 ACTION_NOT_ALLOWEDReason configuration_requirednone
CHECKOUT_REPLACEMENT_REQUIRES_ORDERAll occurrences400 INVALID_REQUESTDetail NOT_ALLOWEDnone
CHECKOUT_SESSION_CURRENT_CHANGEDAll occurrences409 VERSION_CONFLICTNoneafter_refresh
CHECKOUT_SESSION_EXPIREDAll occurrences409 ACTION_NOT_ALLOWEDReason terminal_statusnone
CHECKOUT_SESSION_NOT_OPENAll occurrences409 ACTION_NOT_ALLOWEDReason terminal_statusnone
CHECKOUT_SPLIT_PAYMENT_UNSUPPORTEDAll occurrences409 RESOURCE_IN_USENonenone
CHECKOUT_SURFACE_CHANGE_NOT_ALLOWEDAll occurrences409 ACTION_NOT_ALLOWEDReason in_progressnone
CHECKOUT_TAX_CALCULATION_LIMIT_REACHEDAll occurrences409 LIMIT_REACHEDReason checkout_tax_calculationsnone
CONFIRMATION_TOKEN_ALREADY_USEDAll occurrences409 ACTION_NOT_ALLOWEDReason terminal_statusnone
CONFIRMATION_TOKEN_EXPIREDAll occurrences409 ACTION_NOT_ALLOWEDReason terminal_statusnone
DEFAULT_PAYMENT_METHOD_CONFLICTAll occurrences400 INVALID_REQUESTDetail NOT_ALLOWEDnone
EXTERNAL_PAID_ORDER_ALLOWANCE_EXHAUSTEDAll occurrences409 LIMIT_REACHEDReason external_paid_ordersnone
GIFT_CARD_ALLOCATION_CHANGEDAll occurrences409 VERSION_CONFLICTNoneafter_refresh
GIFT_CARD_BUYER_EMAIL_REQUIREDAll occurrences409 ACTION_NOT_ALLOWEDReason configuration_requirednone
GIFT_CARD_FUNDING_LIMIT_EXCEEDEDRecorded reason is buyer_daily409 LIMIT_EXCEEDEDReason buyer_dailynone
GIFT_CARD_FUNDING_LIMIT_EXCEEDEDRecorded reason is card_balance409 LIMIT_EXCEEDEDReason card_balancenone
GIFT_CARD_FUNDING_LIMIT_EXCEEDEDRecorded reason is card_daily409 LIMIT_EXCEEDEDReason card_dailynone
GIFT_CARD_FUNDING_LIMIT_EXCEEDEDRecorded reason is merchant_adjustments_daily409 LIMIT_EXCEEDEDReason merchant_adjustments_dailynone
GIFT_CARD_FUNDING_LIMIT_EXCEEDEDRecorded reason is merchant_imports_daily409 LIMIT_EXCEEDEDReason merchant_imports_dailynone
GIFT_CARD_INSUFFICIENT_VALUEAll occurrences409 LIMIT_EXCEEDEDNonenone
GIFT_CARD_PURCHASE_CONFLICTOld HTTP 409; current_status is present409 ACTION_NOT_ALLOWEDReason unsupported_statenone
GIFT_CARD_PURCHASE_CONFLICTOld HTTP 409; current_status is absent; param is present409 ACTION_NOT_ALLOWEDReason field_lockednone
GIFT_CARD_PURCHASE_CONFLICTOld HTTP 409; current_status is absent; param is absent; message is one of gift card purchase funding has been collected409 ACTION_NOT_ALLOWEDReason payment_collectednone
GIFT_CARD_PURCHASE_CONFLICTOld HTTP 409; current_status is absent; param is absent; message is not one of gift card purchase funding has been collected409 ACTION_NOT_ALLOWEDReason not_offerednone
GIFT_CARD_PURCHASE_LIMIT_EXCEEDEDAll occurrences409 LIMIT_REACHEDReason daily_gift_card_purchasesnone
GIFT_CARD_STATE_CONFLICTcurrent_status is closed or resource_type is gift_card_notification409 ACTION_NOT_ALLOWEDReason terminal_statusnone
GIFT_CARD_STATE_CONFLICTcurrent_status is absent on another resource type409 ACTION_NOT_ALLOWEDReason not_offerednone
GIFT_CARD_STATE_CONFLICTOther recorded lifecycle status409 ACTION_NOT_ALLOWEDReason unsupported_statenone
ORDER_PAYMENT_ATTEMPT_ACTIVEAll occurrences409 PAYMENT_ATTEMPT_ACTIVENonenone
PAYMENT_ACTION_WINDOW_TOO_SHORTAll occurrences409 PAYMENT_OPTION_UNAVAILABLEReason action_window_too_shortnone
PAYMENT_ALREADY_SETTLEDAll occurrences409 ACTION_NOT_ALLOWEDReason already_appliednone
PAYMENT_AMOUNT_CHANGEDAll occurrences409 VERSION_CONFLICTNoneafter_refresh
PAYMENT_ATTEMPT_MISMATCHAll occurrences400 INVALID_REQUESTDetail NOT_ALLOWEDnone
PAYMENT_ATTEMPT_NOT_CANCELABLEAll occurrences409 ACTION_NOT_ALLOWEDReason terminal_statusnone
PAYMENT_ATTEMPT_NOT_RESUMABLEAll occurrences409 ACTION_NOT_ALLOWEDReason unsupported_statenone
PAYMENT_ATTEMPT_REQUIRES_CAPTUREAll occurrences409 PAYMENT_ATTEMPT_ACTIVENonenone
PAYMENT_AUTHORIZATION_EXPIREDOld HTTP 409; reason is present409 ACTION_NOT_ALLOWEDRecorded reasonnone
PAYMENT_AUTHORIZATION_EXPIREDOld HTTP 409; reason is absent; current_status is absent409 ACTION_NOT_ALLOWEDReason reconciliation_requirednone
PAYMENT_AUTHORIZATION_EXPIREDOld HTTP 409; reason is absent; current_status is requires_capture409 ACTION_NOT_ALLOWEDReason authorization_expirednone
PAYMENT_AUTHORIZATION_EXPIREDOld HTTP 409; reason is absent; current_status is one of canceled, expired409 ACTION_NOT_ALLOWEDReason terminal_statusnone
PAYMENT_AUTHORIZATION_EXPIREDOld HTTP 409; reason is absent; current_status is present; current_status is not one of requires_capture, canceled, expired409 ACTION_NOT_ALLOWEDReason unsupported_statenone
PAYMENT_AUTHORIZATION_NOT_CAPTURABLEOld HTTP 409; reason is present409 ACTION_NOT_ALLOWEDRecorded reasonnone
PAYMENT_AUTHORIZATION_NOT_CAPTURABLEOld HTTP 409; reason is absent; current_status is absent409 ACTION_NOT_ALLOWEDReason reconciliation_requirednone
PAYMENT_AUTHORIZATION_NOT_CAPTURABLEOld HTTP 409; reason is absent; current_status is one of requires_payment_method, requires_confirmation, requires_action, requires_capture409 ACTION_NOT_ALLOWEDReason status_not_reachednone
PAYMENT_AUTHORIZATION_NOT_CAPTURABLEOld HTTP 409; reason is absent; current_status is processing409 ACTION_NOT_ALLOWEDReason in_progressnone
PAYMENT_AUTHORIZATION_NOT_CAPTURABLEOld HTTP 409; reason is absent; current_status is succeeded409 ACTION_NOT_ALLOWEDReason already_appliednone
PAYMENT_AUTHORIZATION_NOT_CAPTURABLEOld HTTP 409; reason is absent; current_status is one of canceled, expired409 ACTION_NOT_ALLOWEDReason terminal_statusnone
PAYMENT_AUTHORIZATION_NOT_CAPTURABLEOld HTTP 409; reason is absent; current_status is present; current_status is not one of requires_payment_method, requires_confirmation, requires_action, requires_capture, processing, succeeded, canceled, expired409 ACTION_NOT_ALLOWEDReason unsupported_statenone
PAYMENT_CONFIRMATION_STATE_CHANGEDAll occurrences409 VERSION_CONFLICTNoneafter_refresh
PAYMENT_CONFIRM_IN_PROGRESSAll occurrences409 ACTION_NOT_ALLOWEDReason in_progressnone
PAYMENT_INTENT_LIMIT_REACHEDAll occurrences409 LIMIT_REACHEDReason payment_intents_per_ordernone
PAYMENT_IN_PROGRESSAll occurrences409 OPERATION_IN_PROGRESSNonesame_request
PAYMENT_LEG_SELECTION_REQUIREDAll occurrences400 INVALID_REQUESTDetail REQUIREDnone
PAYMENT_METHOD_CUSTOMER_MISMATCHOld HTTP 400400 INVALID_REQUESTDetail NOT_ALLOWEDnone
PAYMENT_METHOD_CUSTOMER_MISMATCHOld HTTP 409; param is not subscription_id400 INVALID_REQUESTDetail NOT_ALLOWEDnone
PAYMENT_METHOD_CUSTOMER_MISMATCHOld HTTP 409; param is subscription_id409 ACTION_NOT_ALLOWEDReason configuration_requirednone
PAYMENT_METHOD_HAS_ACTIVE_SUBSCRIPTIONSAll occurrences409 RESOURCE_IN_USENonenone
PAYMENT_METHOD_NOT_ACTIVEOld HTTP 409; param is not subscription_id409 ACTION_NOT_ALLOWEDReason unsupported_statenone
PAYMENT_METHOD_NOT_ACTIVEOld HTTP 409; param is subscription_id409 ACTION_NOT_ALLOWEDReason configuration_requirednone
PAYMENT_METHOD_NOT_READYAll occurrences409 ACTION_NOT_ALLOWEDReason status_not_reachednone
PAYMENT_METHOD_ON_SESSION_ONLYOld HTTP 400400 INVALID_REQUESTDetail NOT_ALLOWEDnone
PAYMENT_METHOD_ON_SESSION_ONLYOld HTTP 409; param is not subscription_id400 INVALID_REQUESTDetail NOT_ALLOWEDnone
PAYMENT_METHOD_ON_SESSION_ONLYOld HTTP 409; param is subscription_id409 ACTION_NOT_ALLOWEDReason configuration_requirednone
PAYMENT_METHOD_REQUIREDOld HTTP 409; param is subscription_id409 ACTION_NOT_ALLOWEDReason configuration_requirednone
PAYMENT_METHOD_REQUIREDOld HTTP 409; param is not subscription_id; operation is collectInvoice409 ACTION_NOT_ALLOWEDReason configuration_requirednone
PAYMENT_METHOD_REQUIREDOld HTTP 409; param is not subscription_id; operation is one of createSubscription, updateSubscription400 INVALID_REQUESTDetail REQUIREDnone
PAYMENT_NOT_REQUIREDAll occurrences409 ACTION_NOT_ALLOWEDReason unsupported_statenone
PAYMENT_OPERATION_IN_PROGRESSAll occurrences409 OPERATION_IN_PROGRESSNonesame_request
PAYMENT_OPTION_LIMIT_EXCEEDEDAll occurrences409 PAYMENT_OPTION_UNAVAILABLEReason amount_out_of_rangenone
PAYMENT_OPTION_NOT_READYRecorded reason is capability_blocked409 PAYMENT_OPTION_UNAVAILABLEReason capability_blockednone
PAYMENT_OPTION_NOT_READYRecorded reason is capability_pending409 PAYMENT_OPTION_UNAVAILABLEReason capability_pendingsame_request
PAYMENT_OPTION_NOT_READYRecorded reason is disabled_by_merchant_settings409 PAYMENT_OPTION_UNAVAILABLEReason disabled_by_merchant_settingsnone
PAYMENT_OPTION_NOT_READYRecorded reason is disabled_by_platform_policy409 PAYMENT_OPTION_UNAVAILABLEReason disabled_by_platform_policynone
PAYMENT_OPTION_NOT_READYRecorded reason is merchant_account_action_required409 PAYMENT_OPTION_UNAVAILABLEReason merchant_account_action_requirednone
PAYMENT_OPTION_NOT_READYRecorded reason is merchant_payments_disabled409 PAYMENT_OPTION_UNAVAILABLEReason merchant_payments_disablednone
PAYMENT_OPTION_NOT_READYRecorded reason is payment_account_context_invalid409 PAYMENT_OPTION_UNAVAILABLEReason payment_account_context_invalidnone
PAYMENT_OPTION_NOT_READYRecorded reason is payment_account_setup_incomplete409 PAYMENT_OPTION_UNAVAILABLEReason payment_account_setup_incompletenone
PAYMENT_OPTION_NOT_READYRecorded reason is payment_option_access_not_provisioned409 PAYMENT_OPTION_UNAVAILABLEReason payment_option_access_not_provisionednone
PAYMENT_OPTION_NOT_READYRecorded reason is payment_option_activation_pending409 PAYMENT_OPTION_UNAVAILABLEReason payment_option_activation_pendingnone
PAYMENT_OPTION_NOT_READYRecorded reason is payment_option_not_available409 PAYMENT_OPTION_UNAVAILABLEReason payment_option_not_availablenone
PAYMENT_OPTION_NOT_READYRecorded reason is payment_option_not_in_plan409 PAYMENT_OPTION_UNAVAILABLEReason payment_option_not_in_plannone
PAYMENT_OPTION_NOT_READYRecorded reason is platform_funding_unavailable409 PAYMENT_OPTION_UNAVAILABLEReason platform_funding_unavailablesame_request
PAYMENT_OPTION_NOT_READYRecorded reason is requirements_due409 PAYMENT_OPTION_UNAVAILABLEReason requirements_duenone
PAYMENT_SOURCE_UNAVAILABLEAll occurrences409 ACTION_NOT_ALLOWEDReason terminal_statusnone
PROMOTION_NOT_REDEEMABLEAll occurrences409 PROMOTION_DECLINEDReason exhaustednone
REVIEW_ALREADY_CLOSEDAll occurrences409 ACTION_NOT_ALLOWEDReason terminal_statusnone
REVIEW_RESOLUTION_IN_PROGRESSAll occurrences409 ACTION_NOT_ALLOWEDReason in_progressnone
RISK_ACTION_NOT_SUPPORTED_FOR_PAYMENT_FLOWAll occurrences409 ACTION_NOT_ALLOWEDReason configuration_requirednone
RISK_ACTION_NOT_SUPPORTED_FOR_PAYMENT_OPTIONAll occurrences409 PAYMENT_OPTION_UNAVAILABLEReason risk_action_unsupportednone
SETUP_SOURCE_NON_ZERO_ORDERAll occurrences409 ACTION_NOT_ALLOWEDReason unsupported_statenone
<!-- payment-error-migration-inventory:end -->

Flint has no external API callers yet.

  • Breaking change
  • API
  • Payments
  • Orders

One capture and cancel route for payment intents#

Superseded by Confirm order payments through their payment intents.

Breaking: Use POST /v1/payment-intents/{payment_intent_id}/capture or /cancel for standalone and order-owned payment intents. Both require payments.payment_intents.write and return the payment intent flat in data. Flint derives the owning order payment attempt; order_payment_attempt_id is not accepted. The nested order routes remain available during the deployment transition.

Merchant payment intent responses and webhooks now include required supported_actions, an extensible array of confirm, capture, and cancel. Buyer credentials receive []. Branch on this list. An action the stored state does not allow returns 409 ACTION_NOT_ALLOWED, with the current status and supported actions in the error details. A listed action can still be refused by another condition, such as an open payment review or an active order payment attempt.

Confirming an order-owned intent returns ACTION_NOT_ALLOWED with reason order_owned; follow remediation.next_actions to pay its order. Fresh requests to capture an already captured payment or cancel an already canceled or expired payment return reason already_applied. Same-key retries still replay or recover the original result. Capture refreshes an expired authorization before dispatch and refuses it with terminal_status or authorization_expired.

The refusals previously named ORDER_PAYMENT_FLOW_REQUIRED, PAYMENT_AUTHORIZATION_NOT_CAPTURABLE, PAYMENT_AUTHORIZATION_EXPIRED, and ORDER_PAYMENT_AUTHORIZATION_NOT_FOUND return ACTION_NOT_ALLOWED with a reason instead. ORDER_PAYMENT_AUTHORIZATION_NOT_FOUND uses reason reconciliation_required. An inconsistent capture recovery previously named CAPTURE_AMOUNT_MISMATCH returns INTERNAL_ERROR.

Order-owned intents accept PATCH for metadata and external_reference_id. Updates to their amount_money, tip_money, customer_id, or receipt_email return 400 INVALID_REQUEST, with a NOT_ALLOWED detail for each field. Handle these details instead of ORDER_LINKED_AMOUNT_NOT_UPDATABLE or TIP_NOT_UPDATABLE. An omitted cancellation reason stays absent for both ownership types. A checkout credential can cancel its own order leg through the canonical route, subject to the existing session and reason restrictions.

These changes apply to every supported API version. Regenerate SDKs against the updated OpenAPI specification.

  • Breaking change
  • API
  • Payouts

Payout contents stay available in every status#

GET /v1/balance-transactions?payout_id=... now lists an automatic payout's contents in any payout status once they are prepared, usually minutes after the payout is created. The transactions' net_money still sums to the payout's amount_money. While preparation is pending, the endpoint returns 503 SERVICE_UNAVAILABLE with Retry-After: 60.

A balance transaction gains payout_id once, when its payout's contents are prepared. The value stays set if the payout later fails or is reversed. Prepared contents are never replaced, so another reconciliation no longer invalidates their page tokens.

Breaking: 409 ACTION_NOT_ALLOWED now means the payout does not itemize its contents, with details[0].reason: not_itemized and param: payout_id. This includes manual and Flint-created payouts. The refusal is permanent, with remediation.retry: none. Use the payout's own payout balance transaction, whose related_resource identifies the payout, to account for it. Payouts awaiting preparation return 503, regardless of their payout status.

Imported payouts now report initiated_by: scheduled for automatic payouts and initiated_by: manual for manual payouts, following the processor. Payouts created through Flint keep their recorded origin.

  • API

Find products through variant references and inventory items#

Merchant product lists now accept variant_external_reference_id and inventory_item_id. These match ProductVariant.external_reference_id and ProductVariant.inventory_item_id. Product external_reference_id continues to match the product itself. When you combine these filters with sku, one non-archived variant must satisfy every child filter. Inactive variants remain eligible.

Product list results include one matched_variant for exact child filters: the first matching variant by position, then variant ID. Exact filters take precedence over the free-text query witness. Without exact child filters, the existing query-SKU witness remains. Detail responses do not include a witness.

To enumerate every match, page the product list, then page each /v1/products/{product_id}/variants list with the corresponding filters. Nested variant lists now accept sku and inventory_item_id; their existing external_reference_id selects the variant's reference. External references match the complete value byte for byte, preserving whitespace, casing, and Unicode. SKU filters match the complete catalog SKU case- and accent-insensitively, without trimming.

Several sellable variants can share one inventory item. A variant's SKU and an inventory item's SKU remain separate; these filters search the variant's SKU. All predicates apply before pagination, and a valid lookup with no match returns an empty page.

  • API
  • Returns
  • Refunds
  • Gift-cards

Returns can issue store credit and choose gift card destinations#

Return policies, buyer requests, decisions, and processing accept resolution_type: "store_credit". Store credit uses the refund calculation and release gates, then refunds the returned value onto new gift cards. Card, Apple Pay, Google Pay, Link, and gift card payments qualify. Affirm and ACH debit payments do not. An unavailable store credit request returns 409 ACTION_NOT_ALLOWED with reason store_credit_unavailable.

Refund, exchange, and correction resolutions accept gift_card_refund_destination: "original" | "new_gift_card", defaulting to original, on create, process, PATCH while proposed, and retry. The field applies to gift-card-paid value. Store credit and its corrections always issue new gift cards and reject the field, as do replacement and no-monetary-action resolutions.

When the original gift card cannot accept the refund, the resolution fails immediately with failure_code: "gift_card_refund_destination_required". Retry with gift_card_refund_destination: "new_gift_card" to issue the value on new cards. A store_credit_unavailable failure requires canceling the resolution and creating a refund resolution.

Flint emails each new gift card to the Return's buyer email when customer_email_delivery.returns is flint_sends. With merchant_sends, or without a buyer email, the merchant delivers it using gift card code rotation or gift card notifications. These merchant delivery actions require commerce.gift_cards.secrets.write. The resolution is fulfilled when the value is issued; email delivery does not delay it.

  • Breaking change
  • API
  • Risk

Risk controls use Flint card fingerprints#

  • Breaking: The card_fingerprint risk attribute and risk list values now use PaymentMethod.fingerprint instead of the processor's card fingerprint. The same card has a different fingerprint for each merchant and environment.
  • Card fingerprint list values are lowercased and must contain exactly 32 hexadecimal characters. Predicate literals must use the lowercase value from PaymentMethod.fingerprint. Raw processor fingerprints are rejected with INVALID_REQUEST.
  • Declining a payment review with add_to_block_lists: true adds the Flint fingerprint. Reviews for attempts created before this change skip the card fingerprint when it isn't available; their email and IP address can still be added.
  • Breaking change
  • API
  • Risk

Risk rule status, health, and credential references#

Risk rules now report issues on every read and write response. An active rule with issues is skipped on every payment until you fix it. An inactive rule with issues cannot be activated until you fix it. Archived rules always return an empty issues array. Use POST /v1/risk-previews to check a rule without saving it.

Breaking

  • RiskRule.status is active, inactive, or archived. It replaces enabled on resources and create and update requests. New rules default to active. Set status: inactive to stop a rule and status: active to run it again. Only deletion produces archived.
  • GET /v1/risk-rules?status=active excludes inactive rules. The default includes active and inactive rules; archived rules require an explicit filter. The limit is 100 active rules per environment, including Flint's defaults.
  • Risk rules and lists drop editable. Use origin to identify Flint's defaults. Default rules accept only status changes and cannot be archived. Default lists cannot be renamed or archived; their items can still be added and removed.
  • created_by on risk rules, lists, and list items is a resource reference to the API key, signed-in user, or partner app installation that created it. It is null when Flint created the resource.
  • Risk previews return is_valid in place of valid. Preview issues and rule issues share the RiskRuleIssue schema.
  • The attribute registry drops its constant version and renames nullable and available to is_nullable and is_available. Its schemas are RiskAttribute, RiskAttributeRegistry, and RiskAttributeRegistryResponse. Operators use the risk_predicate_operator vocabulary.

Risk score predicates accept scores from 0 to 99. Payment intent metadata remains readable as payment_intent_metadata.{key}, even though individual metadata keys do not appear in the attribute registry.

  • Breaking change
  • API
  • Fulfillment

Shipment and package queue filters#

Merchant shipment lists now accept status, direction, updated_after, and updated_before. Package lists accept status, updated_after, and updated_before, plus exact tracking_number and carrier filters. Tracking numbers and carrier names match the full value, including case, accents, and whitespace. Combine them to narrow a lookup; tracking numbers can repeat across carriers.

Repeat status or direction, or separate their values with commas, to match any selected value. Different filters combine with AND. Update-time windows include the lower bound and exclude the upper bound.

Shipment.handed_off_at now reports carrier handoff for outbound and return shipments. When a historical shipment has a recorded shipped_at but no separate handoff timestamp, reads and handoff filters use that shipped time. Existing handoff timestamps stay unchanged. This applies to buyer shipment reads, expanded shipments, and shipment webhook representations too. Historical webhook deliveries are not replayed.

Restart shipment and package pagination after deployment. Buyer lists keep their existing filters; the new queue filters are merchant-only.

  • API
  • Subscriptions

Update subscription fields with PATCH#

PATCH /v1/subscriptions/{subscription_id} now accepts payment_method_id, cancel_at_period_end: false, and billing_schedule, alongside its existing update fields. A billing schedule update must be the only mutable field in the request; expected_version can accompany it. Schedule a cancellation through POST /v1/subscriptions/{subscription_id}/cancel.

The new PATCH /v1/me/subscriptions/{subscription_id} accepts payment_method_id, cancel_at_period_end: false, delivery, billing_interval with billing_interval_count, and quantity. Each field follows its existing buyer action rules, and mixed updates commit together. A scoped card-update session can change only payment_method_id, with an optional expected_version. A scoped management session can undo a scheduled cancellation with cancel_at_period_end: false.

Undoing a cancellation when none is scheduled returns the current subscription without changing its version or sending an event, when that is the only field updated. Changing a payment method does not retry an unpaid renewal; create a payment retry separately.

The existing per-field routes remain available while first-party apps move to PATCH. Their removal will be announced separately.

Recorded contract terms do not prevent early cancellation, and Flint never charges the recorded early termination fee. early_termination_fee_money now stays present after contract_end_at when the recorded terms include a fee, including in subscription webhook snapshots.

Subscription schemas now describe the current cadence, quantity, items, and saved payment method. Plan creation requires at least one line_items entry, next_retry_at is required and nullable on subscriptions, and affected request schemas reject unknown properties.

  • Breaking change
  • API
  • Webhooks

Webhook delivery diagnostics#

Superseded by Webhook refusals name the recovery action.

Webhook delivery diagnostics change immediately for every supported API version:

  • Deliveries, attempts, delivery actions, and webhook timeline attempts use error_category, error_summary, retryable, and recommended_action. last_error, error_message, diagnostic_category, and reference_url are removed from webhook diagnostics.
  • error_category distinguishes timeouts, DNS, TLS, connection failures, blocked targets, request construction failures, redirects, and HTTP 4xx or 5xx responses. Payload rendering failures use server_error; unclassifiable legacy failures use webhook_delivery. Internal failure text is no longer returned.
  • Suppressed deliveries return suppression_reason: endpoint_inactive, endpoint_deleted, authorization_revoked, scope_missing, or event_not_allowed. Suppressed and delivered deliveries have no failure explanation. Before any attempt, the failure explanation is absent.
  • retryable says whether sending again without changing your endpoint is likely to succeed. While a delivery is pending, Flint retries automatically either way.
  • Attempt and delivery-action response_headers is an object of strings instead of a JSON-encoded string. Names are lowercase, repeated values are joined with , , and sensitive values stay redacted. Headers are absent when no response was received or after the 14-day response-detail retention.
  • Breaking change
  • API
  • Webhooks

Webhook event records use the delivery envelope#

<!-- Rollout: deploy Dashboard before backend. The Dashboard adapter accepts both legacy payload/request_id responses and the new data/request envelope. -->

Webhook event records change immediately for every supported API version:

  • data replaces payload. It contains the delivered envelope's data, with its original payload-version shape. It is present on detail reads while the payload is retained for 14 days and you can read the attributed resource. List items omit data.
  • request replaces request_id on merchant events. It is an object with id and an optional idempotency_key, or null when no request caused the event. The idempotency key keeps the same access and retention restrictions as the event data.
  • event_origin is removed. Use test to distinguish synthetic test events from business events.
  • Records include api_version and merchant events include mode and merchant_id, including after payload retention ends. Retained events also include payload_version; retained partner events include the delivered source.
  • event_source, resource_type, resource_id, and api_request_log_id are event metadata alongside the envelope fields. event_type uses the current event name, including for stored events with previous names.

Event data keeps the existing API version behavior: Flint can render it for an older caller version, while payload version 1 retains its frozen shape and recorded API version.

  • Breaking change
  • API
  • Payments
  • Checkout
  • Webhooks

Payment, checkout, and refund webhook events#

These webhook changes apply immediately to every supported API version:

  • payment_intent.expired reports authorization expiry. payment_intent.canceled reports cancellation only. cancellation_reason appears only on canceled payment intents; authorization_expired is no longer a public cancellation reason.
  • payment_intent.created reports creation from any origin. payment_intent.updated reports other public changes, including PATCH, when no specific lifecycle event applies. Refund and dispute rollups also send it when the public payment intent changes, as of the November 6 update.
  • checkout_session.paid replaces checkout_session.completed. Each session has its own paid event, including when sessions share an order. checkout_session.partially_paid reports partial payment, and checkout_session.created reports creation from any origin.
  • payment_method.activated replaces payment_method.saved. It means the payment method is active and can be charged.
  • Refund status transitions send one event: refund.succeeded, refund.partially_succeeded, or refund.failed. Other public changes, including PATCH, send refund.updated.
  • order.payment_authorized, order.payment_captured, order.payment_authorization_canceled, and order.payment_authorization_expired are removed. Use payment_intent.requires_capture, payment_intent.succeeded, payment_intent.canceled, and payment_intent.expired; each payment intent identifies its order with order_id.
  • order.partially_refunded and order.refunded report entry into those aggregate refund statuses. A further refund that leaves the order's refund status unchanged sends no order refund event. Use refund lifecycle events for each refund.

Update subscriptions and test-event requests to current names. Stored subscriptions and events map checkout_session.completed to checkout_session.paid and payment_method.saved to payment_method.activated. Removed order event subscriptions are dropped. GET /v1/webhook-event-types lists current names and their previous_names.

  • API

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

706 additions across Customer account, Custom domains, and 56 more areas. These are additions, so nothing you already use needs to change.

Related: API scope names and catalog metadata, Read buyer resources and the choices their actions accept, Catalog field descriptions, Configuration versions and conditional write fences, Custom domains have their own resource, Developer platform errors use shared codes and reasons, Device registration reports duplicate fingerprints as conflicts, Invoice errors use shared codes and reasons, Consistent operation names and reference pages, Partner apps can be edited, deleted, and removed by merchants, Payment errors use shared codes and resource facts, One capture and cancel route for payment intents, Payout contents stay available in every status, Find products through variant references and inventory items, Returns can issue store credit and choose gift card destinations, Risk controls use Flint card fingerprints, Risk rule status, health, and credential references, Shipment and package queue filters, Update subscription fields with PATCH, Webhook delivery diagnostics, Webhook event records use the delivery envelope, Payment, checkout, and refund webhook events, Access errors use shared codes and reasons, API keys identify their creator and revocation time, Keep a subscription before retrying its payment, Catalog and payment link errors use shared codes, Error codes now fold by status, and REQUEST_FAILED is retired, Delivery errors use shared codes, Delivery requotes use one error code, Named API variants for delivery, returns, and subscriptions, Error reference lists statuses, facts, and reasons, Fulfillment and inventory errors use generic codes and reasons, Named fulfillment request variants, One fulfillment status and a release hold action, Named inventory request variants, Inventory commands return resources and changed levels, Invoice reads match draft write shapes, Find invoices and credit notes with additional filters, Invoice manual payments have IDs and full reversals, Merchant readiness errors use MERCHANT_NOT_READY, Named API variants for invoices, gift cards, and feedback, Order errors use shared codes and precise reasons, Named order, payment, refund, and OAuth variants, Ship with tracking and correct delivered packages, Find payments, customers, checkout sessions, and risk list entries, Deleted payment methods report archived, protocol_error replaces invalid_request_error, and request logs use error_type, Refund and payout errors use shared codes, Return processing shares completion mode and reports uncovered quantity, Returns publish status meanings and remove unused values, Save a card when confirming a standalone payment, Ship an order in one call, Subscription links can allow cancel, pause, and keep, See what a past-due subscription owes, Handle subscription and customer errors with shared codes, Webhook event catalog metadata and previous names, Workload identity management, Exchange workload identity tokens for API access, Verification requests use the customer's email and purpose-specific fields, Catalog category filters and modifier rules, Child lookups and resource state use 404 and 409, Configuration prerequisites return ACTION_NOT_ALLOWED, Credit note corrections and available credit, Inventory holds last up to 24 hours, Control Location allocation with a boolean, Weight and dimensions share decimal shapes, OAuth discovery and public signing keys, One response schema per checkout and delivery operation, Rate-limit quota headers, Fulfillment writes and command results use consistent response shapes, Resource responses for deletes, receipts, and checkout launches, Check buyer return eligibility and control reason availability, Returns use generic validation and action refusal codes, Risk previews check list references and rule limits, Flint mints every request ID, Match subscription offers to external systems and filter by update time, Tax errors distinguish request input from stored configuration, Filter orders with unassigned fulfillment quantity, Product variants support unit weight and dimensions, Unit measurements belong to items, Delivery rates use variant unit weight, Accept a dispute, Analytics uses explicit periods and flat metrics, Buyer resource and Return request schemas, Catalog retirement is safe to repeat, Edit active bundles and add options to live products, Filter catalog lists by creation and update time, The checkout credential is one Authorization bearer token, Checkout creation uses an explicit type and shared buyer fields, Default delivery profiles use is_default, Read files and attach images by file ID, Gift card redemption refunds use amount and state errors, Read inventory allocation policy revisions, Inventory movements name their source and recording credential, Inventory transfers replace lines as one collection, Invoice totals and frozen tax breakdowns, List filters and money sorts name their response fields, List merchant billing entries, Merchant billing uses one API vocabulary, Merchant settings and explicit patch rules, Partner OAuth follows the OAuth standards, Webhooks report closed-order edits and shipment and package changes, Line-item writes use the order version, Partner apps can receive inventory events, Payment and order state refusals use ACTION_NOT_ALLOWED, Payment intent responses share one collection schema, Payment intent create and confirm results, Choose a default payment method on the customer, Payment reviews use explicit names and typed actors, Promotion stacking and rule shapes, Refunds can issue store credit on new gift cards, Report CSVs use API money signs, names, and relationships, Read request logs across callers, Fraud warnings and purchase refund allocations have distinct ID prefixes, Return receipts and inspections have their own versions, Read Return reasons and activity history, Subscription resumes, scheduled starts, and cancellation timing are explicit, Change subscription plans and preview the next charge, Subscription plan resets and checkout payment risk, Subscription state refusals use ACTION_NOT_ALLOWED, Order tickets move to ticketed_event, Webhook deliveries are listed at /v1/webhook-deliveries, Resource version rollout preparation, State refusals include required reasons, and live-mode refusals return FORBIDDEN, Buyer payment responses omit risk, Customer sessions return a resource and support sign-out, Customers have a status, deleted customers leave the list, and deletion requests use one path, Embed dispute responses and use Flint dispute statuses, Throttles and duplicate error codes use shared names, Gift card command results and consistent field names, Hosted partner installs show a consent screen, Inclusive invoice line totals, Request validation uses INVALID_REQUEST, Inventory counts recover from stock that moves, Inventory provenance accepts opaque identifiers and publishes validation rules, Invoice delivery attempts return failure and suppression reasons, Merchant requirement codes and account session targeting, Orders say why they closed, and closing asks before keeping collected money, Order line items report fulfillment quantities, Preparation for partner app updates, Webhook mutations require merchant credentials, Refund create names its type, a recorded refund is always 201, and refund statuses split in two, Exchanges and replacements are fulfilled when their Order is, Returns use release timing and stable adjustment IDs, A failed decline refund reopens the review, and expiry shows as resolving, Risk list checks no longer fail on accepted email addresses, Sandbox resets link archived and replacement sandboxes, Shared invoice credit limits for Returns and credit notes, Enforce published text limits before normalization, Create and import subscriptions from offers, Subscription events cover every change, activation follows the first paid period, and billing-schedule initiated_by is removed, Response warnings use typed fields, Stale versions on catalog, subscription, plan, and risk writes return VERSION_CONFLICT, Stale versions on customer, settings, invoice, and other writes return VERSION_CONFLICT with the current value, Resend pending webhook deliveries and create missing ones, Webhook endpoint status and secret rotation, Build invoice pages with the buyer invoice document, Buyer responses omit merchant inventory, tax configuration, and courier operations, Catalog changes send webhook events, and deleted promotion codes read archived, Read checkout branding, subscription choices, and order tax price mode, Credit note tax and remaining value, Fulfillment event types are complete, and checkout surfaces stay consistent, Hosted invoice links use the invoice ID, Invoice webhooks cover every status change, and paid invoices can reopen, Order sort errors and tax and invoice values match responses, Organization membership changes require existing access, Filter payments that need action and send standalone receipts, Required response fields include nullable values, Filter disputes that need a response and choose their order, Gift card restrictions, a default funding disposition, and a customer filter, One code for records in the way and one for a taken key, Packages dispatch and complete shipments, and the buyer gets one email per moment, Retry PAYMENT_METHOD_NOT_READY with the same Idempotency-Key

Customer account
79 additions
Custom domains
5 additions
Workload identities
5 additions
Risk controls
17 additions
Invoices
32 additions
Inventory
25 additions
Customers
12 additions
Files
5 additions
Merchant billing
3 additions
Webhooks
26 additions
Payments
15 additions
Gift cards
10 additions
Partner app installs
5 additions
Returns
39 additions
  • Endpoint
  • Query parameter
    sort_byon GET /v1/returns

    Field to sort by.

  • Query parameter
    sort_directionon GET /v1/returns

    Sort direction.

  • Request field
    expected_return_versionon POST /v1/return-previews

    Optional version of the parent Return.

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

    Optional gate for every resolution type.

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

    Omit to use the mode shared by all pinned policies that set completion_mode, or automatic when no pinned policy sets one.

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

    Where the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards.

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

    Optional gate for every resolution type.

Subscriptions
25 additions
  • Endpoint
  • Query parameter
    terms_typeon GET /v1/subscriptions

    Filter by where the subscription terms come from: a subscription plan or subscription offers.

  • Request field
    billing_scheduleon PATCH /v1/subscriptions/{subscription_id}

    Changes who supplies billing dates and, for a Flint-owned schedule, the next billing date.

  • Request field
    cancel_at_period_endon PATCH /v1/subscriptions/{subscription_id}

    Send `false` to undo a scheduled cancellation.

  • Request field
    payment_method_idon PATCH /v1/subscriptions/{subscription_id}

    ID of the saved payment method to charge for renewals.

  • Request field
    termson POST /v1/subscription-previews

    What the subscription bills for, from a subscription plan or from subscription offers, selected by `type`.

  • Field

    Current API version pin on VERSION_CONFLICT when expected_api_version is stale.

  • Field

    Current effective delivery selection ID on VERSION_CONFLICT when expected_delivery_selection_id is stale.

Disputes
13 additions
Orders
33 additions
Checkout sessions
32 additions
  • Query parameter
    invoice_idon GET /v1/checkout-sessions

    Exact match on the Flint invoice ID.

  • Query parameter
    subscription_plan_idon GET /v1/checkout-sessions

    Exact match on the Flint subscription plan ID.

  • Query parameter
    surfaceon GET /v1/checkout-sessions

    Filter by checkout surface.

  • Query parameter
    typeon GET /v1/checkout-sessions

    Filter by checkout session type.

  • Request field
    buyer_fieldson POST /v1/checkout-sessions

    What checkout asks the buyer for.

  • Request field
    customer_idon POST /v1/checkout-sessions

    Existing customer to link to the order Flint creates.

  • Request field
    expires_in_secondson POST /v1/checkout-sessions

    Seconds the session stays open, from 60 to 86,400.

  • Request field
    payment_return_urlon POST /v1/checkout-sessions

    Headless sessions only.

Analytics
26 additions
  • Query parameter
    period_end_aton GET /v1/analytics/overview

    Exclusive period end as an RFC 3339 instant.

  • Query parameter
    period_start_aton GET /v1/analytics/overview

    Inclusive period start as an RFC 3339 instant.

  • Query parameter
    granularityon GET /v1/analytics/payment-volume-timeseries

    Bucket size: hour, day (default), week starting Monday, or month.

  • Query parameter
    period_end_aton GET /v1/analytics/payment-volume-timeseries

    Exclusive period end as an RFC 3339 instant.

  • Query parameter
    period_start_aton GET /v1/analytics/payment-volume-timeseries

    Inclusive period start as an RFC 3339 instant.

  • Query parameter
    currencyon GET /v1/analytics/subscriptions

    ISO 4217 currency for every amount and payments_count.

  • Query parameter
    period_end_aton GET /v1/analytics/subscriptions

    Exclusive period end as an RFC 3339 instant.

  • Query parameter
    period_start_aton GET /v1/analytics/subscriptions

    Inclusive period start as an RFC 3339 instant.

Products
21 additions
  • Query parameter
    inventory_item_idon GET /v1/products

    Exact match on ProductVariant.inventory_item_id.

  • Query parameter

    Byte-sensitive whole-value match on ProductVariant.external_reference_id, preserving whitespace, casing, and Unicode.

  • Query parameter
    created_afteron GET /v1/products/{product_id}/variants

    Inclusive lower bound on created_at.

  • Query parameter
    created_beforeon GET /v1/products/{product_id}/variants

    Exclusive upper bound on created_at.

  • Query parameter
    inventory_item_idon GET /v1/products/{product_id}/variants

    Exact match on ProductVariant.inventory_item_id.

  • Query parameter
    skuon GET /v1/products/{product_id}/variants

    Full-value match on ProductVariant.sku, case- and accent-insensitive, with no trimming.

  • Query parameter
    updated_afteron GET /v1/products/{product_id}/variants

    Inclusive lower bound on updated_at.

  • Query parameter
    updated_beforeon GET /v1/products/{product_id}/variants

    Exclusive upper bound on updated_at.

Fulfillment records
19 additions
API request logs
18 additions
Promotions
16 additions
  • Query parameter
    availabilityon GET /v1/promotion-codes

    Filter by whether a code can be redeemed now or why it cannot. available matches available: true; every other value matches unavailable_reason.

  • Query parameter
    created_afteron GET /v1/promotion-codes

    Inclusive lower bound on created_at.

  • Query parameter
    created_beforeon GET /v1/promotion-codes

    Exclusive upper bound on created_at.

  • Query parameter
    sort_byon GET /v1/promotion-codes

    Field to sort by.

  • Query parameter
    sort_directionon GET /v1/promotion-codes

    Sort direction.

  • Query parameter
    updated_afteron GET /v1/promotion-codes

    Inclusive lower bound on updated_at.

  • Query parameter
    updated_beforeon GET /v1/promotion-codes

    Exclusive upper bound on updated_at.

  • Query parameter
    availabilityon GET /v1/promotions

    Filter by whether a promotion can apply now or why it cannot. available matches available: true; every other value matches unavailable_reason.

Return resolutions
16 additions
  • Request field
    adjustmentson PATCH /v1/return-resolutions/{return_resolution_id}

    Requires expected_version.

  • Request field
    gift_card_refund_destinationon PATCH /v1/return-resolutions/{return_resolution_id}

    Where the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards.

  • Request field
    expected_return_versionon POST /v1/return-resolutions

    Optional version of the parent Return.

  • Request field
    gift_card_refund_destinationon POST /v1/return-resolutions

    Where the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards.

  • Request field
    gift_card_refund_destinationon POST /v1/return-resolutions

    Where the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards.

  • Request field
    gift_card_refund_destinationon POST /v1/return-resolutions

    Where the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards.

  • Request field
    gift_card_refund_destinationon POST /v1/return-resolutions/{return_resolution_id}/retry

    Where the gift-card-paid portion is refunded. original credits the original gift card; new_gift_card issues new gift cards.

  • Field

    Who canceled the resolution.

Payment links
13 additions
Modifiers
12 additions
  • Query parameter
    created_afteron GET /v1/modifier-groups

    Inclusive lower bound on created_at.

  • Query parameter
    created_beforeon GET /v1/modifier-groups

    Exclusive upper bound on created_at.

  • Query parameter
    sort_byon GET /v1/modifier-groups

    Field to sort by.

  • Query parameter
    sort_directionon GET /v1/modifier-groups

    Sort direction.

  • Query parameter
    updated_afteron GET /v1/modifier-groups

    Inclusive lower bound on updated_at.

  • Query parameter
    updated_beforeon GET /v1/modifier-groups

    Exclusive upper bound on updated_at.

  • Query parameter
    created_afteron GET /v1/modifier-sets

    Inclusive lower bound on created_at.

  • Query parameter
    created_beforeon GET /v1/modifier-sets

    Exclusive upper bound on created_at.

Credit notes
10 additions
  • Query parameter
    created_afteron GET /v1/credit-notes

    Inclusive lower bound on created_at.

  • Query parameter
    created_beforeon GET /v1/credit-notes

    Exclusive upper bound on created_at.

  • Query parameter
    customer_idon GET /v1/credit-notes

    Filter by the source invoice's current customer_id.

  • Query parameter
    expandon GET /v1/credit-notes

    Include related objects in the response.

  • Query parameter
    reasonon GET /v1/credit-notes

    Filter by credit note reason.

  • Query parameter
    expandon GET /v1/credit-notes/{credit_note_id}

    Include related objects in the response.

  • Field

    Credit applied to the invoice, net of reversed allocations.

  • Field

    Credit available to allocate or refund.

Partner OAuth
10 additions
  • Query parameter
    code_challengeon GET /v1/oauth/authorize

    Base64url-encoded SHA-256 hash of your code_verifier, without padding (RFC 7636).

  • Query parameter
    code_challenge_methodon GET /v1/oauth/authorize

    PKCE challenge method.

  • Query parameter
    sandbox_idon GET /v1/oauth/authorize

    Optional active merchant sandbox ID, accepted only with mode=test.

  • Query parameter
    scopeon GET /v1/oauth/authorize

    Space-separated permission IDs from your app's permission manifest.

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

    Base64url-encoded SHA-256 hash of your code_verifier, without padding (RFC 7636).

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

    PKCE challenge method.

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

    Optional active merchant sandbox ID, accepted only with mode=test.

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

    Space-separated permission IDs from your app's permission manifest.

Return policies
9 additions
Partner apps
8 additions
  • Request field
    default_requested_permissionson PATCH /v1/partner-apps/{partner_app_id}

    Replaces the default requested permission IDs.

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

    Apply only if this matches the app’s current version.

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

    The app's name, shown to merchants on the consent screen and in Flint's emails, at most 100 characters, without links or email addresses.

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

    Replaces the whole manifest.

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

    Replaces the entire list of registered redirect URIs.

  • Field
  • Field

    Starts at 1 and increases by 1 each time the app is updated, its client secret is rotated, its platform terms are accepted, Flint decides on its platform review or changes its platform terms, or it is deleted.

  • Value
Payment methods
8 additions
Refunds
8 additions
Subscription offers
8 additions
  • Query parameter
    created_afteron GET /v1/subscription-offers

    Inclusive lower bound on created_at.

  • Query parameter
    created_beforeon GET /v1/subscription-offers

    Exclusive upper bound on created_at.

  • Query parameter
    external_reference_idon GET /v1/subscription-offers

    Exact-match filter on the caller-owned external reference ID.

  • Query parameter
    updated_afteron GET /v1/subscription-offers

    Inclusive lower bound on updated_at.

  • Query parameter
    updated_beforeon GET /v1/subscription-offers

    Exclusive upper bound on updated_at.

  • Request field
    external_reference_idon PATCH /v1/subscription-offers/{subscription_offer_id}

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

  • Request field
    external_reference_idon POST /v1/subscription-offers

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

  • Field

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

Bundles
7 additions
  • Query parameter
    created_afteron GET /v1/bundles

    Inclusive lower bound on created_at.

  • Query parameter
    created_beforeon GET /v1/bundles

    Exclusive upper bound on created_at.

  • Query parameter
    updated_afteron GET /v1/bundles

    Inclusive lower bound on updated_at.

  • Query parameter
    updated_beforeon GET /v1/bundles

    Exclusive upper bound on updated_at.

  • Event

    A bundle was archived.

  • Event

    A bundle was created.

  • Event

    A bundle's own fields, images, categories, modifier set or components changed, or a variant or product change reached its component variant summaries or is_available_for_sale.

Categories
7 additions
  • Query parameter
    created_afteron GET /v1/categories

    Inclusive lower bound on created_at.

  • Query parameter
    created_beforeon GET /v1/categories

    Exclusive upper bound on created_at.

  • Query parameter
    handleon GET /v1/categories

    Exact handle match.

  • Query parameter
    sort_byon GET /v1/categories

    Field to sort by.

  • Query parameter
    sort_directionon GET /v1/categories

    Sort direction.

  • Query parameter
    updated_afteron GET /v1/categories

    Inclusive lower bound on updated_at.

  • Query parameter
    updated_beforeon GET /v1/categories

    Exclusive upper bound on updated_at.

OAuth
7 additions
Money movement
6 additions
Merchants
5 additions
Locations
4 additions
Return dispositions
4 additions
Return inspections
4 additions
Return reasons
4 additions
  • Query parameter
    handleon GET /v1/return-reasons

    Exact, case-sensitive match on the reason's handle, for Flint and merchant reasons.

  • Request field
    statuson PATCH /v1/return-reasons/{return_reason_id}

    Set active to offer the reason or inactive to stop offering it.

  • Value
  • Value
Return receipts
4 additions
API keys
3 additions
  • Values

    accounts.workload_identities.readaccounts.workload_identities.writedeveloper.request_logs.readpayments.disputes.write

  • Values

    accounts.workload_identities.readaccounts.workload_identities.writedeveloper.request_logs.readpayments.disputes.write

  • Values

    accounts.workload_identities.readaccounts.workload_identities.writedeveloper.request_logs.readpayments.disputes.write

Customer sessions
3 additions
Delivery configuration
3 additions
  • Query parameter
    is_defaulton GET /v1/delivery-profiles

    Filter by whether the profile is the current physical catalog default.

  • Request field
    is_defaulton PATCH /v1/delivery-profiles/{delivery_profile_id}

    Send true to make this active profile the physical catalog default.

  • Field

    True only when this profile is the current physical catalog default.

CLI OAuth
2 additions
  • Request field
    modeon POST /v1/oauth/device/authorize

    Environment used for this resource or request.

  • Request field
    modeon POST /v1/oauth/device/reauthorize

    Environment used for this resource or request.

Delivery previews
2 additions
Delivery quotes
2 additions
Merchant account sessions
2 additions
Settings
2 additions
Subscription plans
2 additions
  • Query parameter
    updated_afteron GET /v1/subscription-plans

    Inclusive lower bound on updated_at.

  • Query parameter
    updated_beforeon GET /v1/subscription-plans

    Exclusive upper bound on updated_at.

Demo sessions
1 addition
  • Values

    accounts.workload_identities.readaccounts.workload_identities.writedeveloper.request_logs.readpayments.disputes.write

Devices
1 addition
Payment method domains
1 addition
  • Query parameter
    domain_nameon GET /v1/payment-method-domains

    Exact hostname filter after trimming whitespace and converting to lowercase.

Sandboxes
1 addition
  • Values

    accounts.workload_identities.readaccounts.workload_identities.writedeveloper.request_logs.readpayments.disputes.write

Webhook events
39 additions
  • Field
    FraudWarning.is_actionable

    true until the payment is refunded in full, a dispute opens on it, or the card network marks the warning resolved; after that it stays false.

  • Field
    FraudWarning.updated_at

    RFC3339 timestamp.

  • Field
    GiftCardFundingSource.customer_id

    ID of the customer the funding is attributed to.

  • Field
    GiftCardFundingSource.refund_id

    Refund that issued this value.

  • Field
    InventoryReservation.expires_at

    When held quantity is released if it isn't committed first.

  • Field
    InventoryReservation.supported_actions

    Actions that can change this reservation now.

  • Field
    InventoryTransfer.external_reference_id

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

  • Field
    InventoryTransferLine.condition

    Condition of the units being moved.

Errors
7 additions
  • Breaking change
  • API
  • Errors
  • Onboarding

Access errors use shared codes and reasons#

These changes apply to every supported API version, including retained error responses replayed with an idempotency key and request-log reads. Replace branches on the retired codes with the new code and details[0].reason, or details[].code for validation failures. Every replacement keeps remediation.retry: none.

Retired codeNew responseReason or validation detail
API_KEY_MANAGEMENT_FORBIDDEN403 FORBIDDENreason merchant_role_insufficient
CUSTOMER_SESSION_REFRESH_EXPIRED401 INVALID_CREDENTIALreason expired
CUSTOMER_SESSION_REFRESH_REUSED401 INVALID_CREDENTIALreason revoked
DELIVERY_CALLER_RATES_UNAVAILABLE_TO_BUYER403 FORBIDDENreason merchant_credential_required
EXPANSION_NOT_AUTHORIZED403 FORBIDDENreason expansion_not_permitted
INVALID_SANDBOX_ID403 FORBIDDENreason sandbox_not_accessible
INVALID_VERIFICATION400 INVALID_REQUESTdetail INVALID_VALUE
INVENTORY_RESERVATION_OWNER_MISMATCH403 FORBIDDENreason owner_workflow_required
MEMBERSHIP_REQUIRED403 FORBIDDENreason organization_membership_required
MERCHANT_ACCOUNT_SESSION_LAUNCH_TOKEN_SCOPE_MISMATCH403 FORBIDDENreason environment_mismatch
ONBOARDING_DIRECT_OWNER_REQUIRED403 FORBIDDENreason direct_owner_required
ROLE_ASSIGNMENT_FORBIDDEN403 FORBIDDENreason role_not_assignable
ROLE_MANAGEMENT_FORBIDDEN403 FORBIDDENreason organization_role_insufficient
ROOT_ORGANIZATION_CREATION_FORBIDDEN400 INVALID_REQUESTdetail NOT_ALLOWED
SANDBOX_MANAGEMENT_FORBIDDEN403 FORBIDDENreason merchant_role_insufficient
SELF_ROLE_EDITS_FORBIDDEN403 FORBIDDENreason self_role_edit_forbidden
SETTINGS_WRITE_FORBIDDEN403 INSUFFICIENT_SCOPEscope_requirement and missing_scopes
VERIFICATION_ALREADY_USED400 INVALID_REQUESTdetail INVALID_VALUE
VERIFICATION_ATTEMPTS_EXCEEDED409 LIMIT_REACHEDreason verification_attempts

ROLE_ASSIGNMENT_FORBIDDEN now names role in param; choose a role the acting user can assign. ROOT_ORGANIZATION_CREATION_FORBIDDEN changes from 403 to 400 INVALID_REQUEST, with NOT_ALLOWED at parent_organization_id: public callers must create a child organization under an existing parent. Settings writes require a credential with settings.write; a missing scope returns INSUFFICIENT_SCOPE.

On POST /v1/customer-sessions/refresh, INVALID_CREDENTIAL with reason expired requires a new session. Reason revoked means a rotated refresh token was presented again with a new idempotency key and Flint revoked the whole session family. Re-authenticate the buyer in both cases. Do not retry the refresh.

POST /v1/onboarding/verify-email no longer returns 401 for verification failures. A wrong code returns 400 INVALID_REQUEST with detail INVALID_VALUE at verification_code. An unknown, expired, or used verification token gets the same validation detail at verification_token. After five incorrect codes, further attempts return 409 LIMIT_REACHED with reason verification_attempts and param: "verification_token". Flint checks token state and the attempt limit before comparing the code, so a correct guess after the limit gets the same response as a wrong one. Start again with a new idempotency key to receive a new code and token. The hourly email throttle stays 429 RATE_LIMIT_EXCEEDED with Retry-After.

See Error handling, Customer sessions, and API and agent onboarding for recovery steps.

  • Breaking change
  • API
  • Api-keys

API keys identify their creator and revocation time#

API key responses now include created_by, a resource reference to the API key or user that created the key. An API key creator can belong to another mode: a live management key can create a sandbox key. The field is absent when the creator is unavailable. Revoking a key does not revoke keys it created.

Revoked keys include revoked_at as an RFC 3339 timestamp. Keys revoked before Flint recorded this timestamp use their last update time. Active and expired keys omit the field.

Breaking: key_type is removed from API key responses, including responses that return a secret. Key names now publish maxLength: 100 in OpenAPI, matching the existing validation. This limit also applies to sandbox key names.

You can update an expired key's expires_at to a future time to reactivate it. A revoked key cannot be updated.

  • API
  • Subscriptions

Keep a subscription before retrying its payment#

While a past-due subscription has a scheduled cancellation, its retry_payment buyer action is unavailable with unavailable_reason: "not_in_state". A new retry through POST /v1/me/subscriptions/{subscription_id}/payment-retries returns 409 ACTION_NOT_ALLOWED. Its subscription detail includes reason: "cancellation_scheduled" and current_status: "past_due".

To pay and keep the subscription, first call POST /v1/me/subscriptions/{subscription_id}/reactivate. The subscription stays past_due; retry_payment becomes available again when the other retry conditions allow it. Reactivation itself does not collect payment.

Reusing an accepted retry's idempotency key still returns that retry. Merchant collection and automatic retries keep their existing behavior.

See Recover a past-due subscription.

  • Breaking change
  • API
  • Errors

Error codes now fold by status, and REQUEST_FAILED is retired#

Flint now keeps its error codes in one registry: 39 kept codes, plus REQUIRED, INVALID_VALUE, UNKNOWN_FIELD, and NOT_ALLOWED as detail codes under INVALID_REQUEST. REQUEST_BLOCKED is a temporary extra sent by Flint's edge firewall. It becomes FORBIDDEN with reason request_blocked after an edge change, and this changelog will announce that change.

A condition that needs its own response is a details[0].reason on a kept code, not a new code. Adding a code needs a registry entry and a remedy that no kept code and reason describe. Treat an unfamiliar reason as its code's default: for ACTION_NOT_ALLOWED, read current_status and supported_actions. unsupported_state always carries current_status.

A code Flint has not yet registered is folded by HTTP status and remediation.retry, and the status never changes. Older route-specific domain codes keep publishing as they do today until each area moves, so this entry does not close the full set of published codes. The fold rules for unregistered codes are:

StatusRetryPublic code
409same_requestCONCURRENT_MODIFICATION
409after_refreshVERSION_CONFLICT
409noneACTION_NOT_ALLOWED with reason unsupported_state
429same_requestRATE_LIMIT_EXCEEDED
429noneLIMIT_REACHED

400, 401, 403, 404, and 5xx fold to the generic code for the status, and 410 folds to ACTION_NOT_ALLOWED with reason terminal_status.

REQUEST_FAILED is the only retired code, and it no longer publishes:

BeforeAfter
400 REQUEST_FAILED400 INVALID_REQUEST with detail code INVALID_VALUE
409 REQUEST_FAILED409 ACTION_NOT_ALLOWED with reason configuration_required

These failures carried no lifecycle facts, so the new responses have no current_status. A bare duplicate-resource failure now returns 409 ALREADY_EXISTS.

If you branched on REQUEST_FAILED, branch on INVALID_REQUEST, or on ACTION_NOT_ALLOWED with reason configuration_required. Retry stays none.

The registry adds OPERATION_IN_PROGRESS, LIMIT_EXCEEDED, LIMIT_REACHED, MERCHANT_NOT_READY, PAYMENT_ATTEMPT_ACTIVE, and DELIVERY_REQUOTE_REQUIRED to the public set. Route-specific domain codes, such as MERCHANT_ONBOARDING_REQUIRED and FULFILLMENT_CHANGED, keep publishing until each domain moves into the set. Each move gets its own changelog entry with a table from the retired code to its replacement, so keep your branches on those codes until then.

Retired codes also change in replays and request logs. A retained REQUEST_FAILED failure replays as its new code, and request-log reads show the new code.

The registry also records retry guidance for these codes and reasons. A domain starts returning a registered reason only when it moves, so not every endpoint returns each one yet:

  • OPERATION_IN_PROGRESS is same_request, and sends Retry-After whenever Flint knows the wait.
  • DELIVERY_REQUOTE_REQUIRED is after_refresh: create a new delivery quote, then send the request again with a new Idempotency-Key.
  • INTERNAL_ERROR and SERVICE_UNAVAILABLE with reason repair_required, a 502 or 503 with outcome_unknown, and image failures with image_ingestion_restart_required are registered as none. Resending fails the same way, or hides an outcome you should read first. outcome_unknown is registered on 503 SERVICE_UNAVAILABLE today. The 502 EXTERNAL_SERVICE_ERROR pair arrives with a later release, and no endpoint returns it until then.
  • LIMIT_EXCEEDED and LIMIT_REACHED are none. A quota that only the caller can clear belongs on 409 LIMIT_REACHED, not 429; 429 is for throttles. A few older domain quota codes, such as SAVE_PAYMENT_METHOD_CODE_LIMIT_REACHED and IMAGE_STORAGE_QUOTA_EXCEEDED, still return 429 with retry none until their domain moves.
  • Your retry loop should retry same_request with exponential backoff and jitter, wait for Retry-After, and return the error when the next wait would pass the call's deadline.

See Error handling for the fold rules and how to tell a rate limit from a quota or bound.

  • Breaking change
  • API
  • Errors
  • Delivery

Delivery errors use shared codes#

Delivery errors use shared codes and reasons. Branch on code, then details[0].reason. param names the request field to change. State refusals retry only after the cause changes; VERSION_CONFLICT requires a fresh read and a new Idempotency-Key.

Removed codeNew code and reason
CHECKOUT_SESSION_SCOPE_MISMATCHRESOURCE_NOT_FOUND for another checkout session; INVALID_REQUEST / NOT_ALLOWED for preview mode
DELIVERY_COMMERCE_TREATMENT_UNSUPPORTEDACTION_NOT_ALLOWED / not_offered
DELIVERY_DEPENDENCY_REVOKEDDELIVERY_REQUOTE_REQUIRED / quote_revoked on quote, selection, and pay; ACTION_NOT_ALLOWED / terminal_status on configuration operations
DELIVERY_DESTINATION_CONTROLLED_BY_SELECTIONACTION_NOT_ALLOWED / field_locked
DELIVERY_DESTINATION_FROZENACTION_NOT_ALLOWED / field_locked
DELIVERY_EXTERNAL_REFERENCE_REUSEDALREADY_EXISTS
DELIVERY_GROUPING_UNSUPPORTEDACTION_NOT_ALLOWED / not_offered
DELIVERY_PICKUP_AVAILABILITY_CHANGEDVERSION_CONFLICT for a stale fence or changed basis; ACTION_NOT_ALLOWED for a checkout lifecycle refusal
DELIVERY_PICKUP_LOCATION_UNAVAILABLEINVALID_REQUEST / INVALID_VALUE
DELIVERY_PREVIEW_REQUIRES_CHECKOUTINVALID_REQUEST / NOT_ALLOWED
DELIVERY_RATE_CALLBACK_SECRET_ROTATION_OVERLAP_ACTIVEACTION_NOT_ALLOWED / in_progress
DELIVERY_SELECTION_NOT_MUTABLE_AFTER_PAYMENTACTION_NOT_ALLOWED / payment_collected
DELIVERY_SELECTION_REPLACEMENT_LIMIT_REACHEDLIMIT_REACHED / delivery_selection_replacements
DELIVERY_STATE_CONFLICTACTION_NOT_ALLOWED for lifecycle refusals, VERSION_CONFLICT for store races, ALREADY_EXISTS for an already revoked target
FULFILLMENT_METHOD_ASSIGNMENT_UNSATISFIABLEACTION_NOT_ALLOWED / configuration_required
FULFILLMENT_METHOD_UNAVAILABLEACTION_NOT_ALLOWED / archived, unsupported_state, or method_unavailable, depending on the method and its dependencies
FULFILLMENT_PROFILE_REVISION_UNUSABLEACTION_NOT_ALLOWED / configuration_required
FULFILLMENT_PROFILE_UNAVAILABLEACTION_NOT_ALLOWED / archived or unsupported_state; configuration_required when the active profile has no usable revision
FULFILLMENT_SELECTION_REQUIREDACTION_NOT_ALLOWED / configuration_required
SUBSCRIPTION_DELIVERY_UNAVAILABLEACTION_NOT_ALLOWED / method_unavailable, destination_not_served, or configuration_required; EXTERNAL_SERVICE_ERROR / rate_unavailable when the rate cannot be calculated

Subscription delivery failures include delivery_method_id when one method is known, plus unavailable_reason and failure_category where applicable. A rate calculation failure returns 502 with remediation.retry: same_request; stored input that needs correction returns 409 with configuration_required. Incompatible request lines return 400 with a NOT_ALLOWED detail for each line.

  • Breaking change
  • API
  • Errors
  • Delivery

Delivery requotes use one error code#

Delivery quote expiry, revocation, and stale inputs now return HTTP 409 with DELIVERY_REQUOTE_REQUIRED. Branch on details[0].reason, create a new quote, select an option, and resend with a new Idempotency-Key. remediation.retry is after_refresh, and remediation.next_actions includes recreate_delivery_quote.

Previous codeCurrent codeReason or condition
DELIVERY_CALCULATION_EXPIREDDELIVERY_REQUOTE_REQUIREDcalculation_expired
DELIVERY_ELIGIBILITY_CONTEXT_CHANGEDDELIVERY_REQUOTE_REQUIREDdestination_changed
DELIVERY_OPTION_ALREADY_SELECTEDVERSION_CONFLICT with a selection assertion; ALREADY_EXISTS without oneSee the recovery steps below.
DELIVERY_OPTION_EXPIREDDELIVERY_REQUOTE_REQUIREDoption_expired
DELIVERY_QUOTE_BASIS_INVALIDDELIVERY_REQUOTE_REQUIREDquote_stale
DELIVERY_QUOTE_EXPIREDDELIVERY_REQUOTE_REQUIREDquote_expired
DELIVERY_QUOTE_INCOMPLETEDELIVERY_REQUOTE_REQUIREDcaller_rates_required
DELIVERY_QUOTE_INPUT_CHANGEDDELIVERY_REQUOTE_REQUIREDdestination_changed
DELIVERY_QUOTE_REVOKEDDELIVERY_REQUOTE_REQUIREDquote_revoked
DELIVERY_QUOTE_STALEDELIVERY_REQUOTE_REQUIREDquote_stale
DELIVERY_RESOURCE_VERSION_CONFLICTVERSION_CONFLICTA resource write lost a race after work started.
DELIVERY_SELECTION_CHANGEDVERSION_CONFLICT with a selection assertion; DELIVERY_REQUOTE_REQUIRED with selection_changed without oneSee the recovery steps below.
DELIVERY_SELECTION_EXPIREDDELIVERY_REQUOTE_REQUIREDselection_expired
DELIVERY_WINDOW_EXPIREDDELIVERY_REQUOTE_REQUIREDwindow_expired

A stale expected_delivery_selection_id, including an assertion that no selection exists, returns VERSION_CONFLICT with that param. Read details[0].current_delivery_selection_id, which is null when none is current. current_selection_id also carries the ID when one exists. Re-read the checkout and rebuild the request with a new key.

Without a selection assertion, a consumed option returns ALREADY_EXISTS with resource_type: delivery_selection. When known, param identifies choices[index].delivery_option_id. current_resource identifies the owning selection when your credential can read it. Use that selection or choose another option. Its retry is none.

For caller_rates_required, create a quote with the pending quote as basis_delivery_quote_id and supply its requested method_results. Expiry and stale-input errors that previously used retry none now use after_refresh. Both policies retain the failed idempotency record, so the original key still replays the refusal.

  • API
  • Delivery
  • Returns
  • Subscriptions

Named API variants for delivery, returns, and subscriptions#

The OpenAPI definition now gives delivery, return, and subscription variants named models, titles, and explicit discriminator mappings. SDK generators can use these mappings to select each variant and expose its fields.

Conditional schemas describe delivery pricing requirements, revocation version requirements, and subscription billing anchor rules. Request behavior is unchanged, including existing selectors and optional billing schedules.

See the fulfillment, return resolutions, and subscription billing guides for the request shapes.

  • API

Error reference lists statuses, facts, and reasons#

Each error response in the OpenAPI document now has x-flint-error-codes: the codes that status can return, details[].code values included. The operation-level x-flint-error-codes is unchanged and is still every code the operation can return, so the per-status lists together equal it. A code that can come back at two statuses is listed under both.

The error reference now shows, for each code:

  • The HTTP statuses it can carry, each with its type.
  • The facts its details[] items can carry.
  • Its reasons, with what each means and a retry or fix when it differs from the code's.
  • A note when it appears only in details[].

Codes are grouped by HTTP status, and the #code anchors that doc_url points to are unchanged. The API reference groups each endpoint's error codes by status.

ErrorDetail.reason now describes its values per code, as "When code is X, one of: ...". ErrorObject.code describes where the per-operation and per-response lists are.

FORBIDDEN from POST /v1/customers/{customer_id}/access-links and from file endpoints now carries reason: not_permitted when the credential can't call them. See Error handling for where to read each list.

  • Breaking change
  • API
  • Errors
  • Fulfillment
  • Inventory
  • Returns

Fulfillment and inventory errors use generic codes and reasons#

Breaking: replace branches on the retired codes below with their public replacement and, where present, details[0].reason. Every detail repeats the public code except validation details under INVALID_REQUEST.

ACTION_NOT_ALLOWED remains 409 with retry none. Read the refusing resource in resource_type and resource_id, then branch on reason. Unknown reasons fall back to current_status and supported_actions when present. unsupported_state carries the actual current_status. A retained unsupported_state refusal without recorded or provable status uses not_offered and preserves its recorded param. Fresh bare inventory item and Location refusals without status use not_offered and omit param because they cannot identify a submitted field. configuration_required omits current_status and names the resource to configure. A Location with inventory_allocation_enabled: false uses configuration_required because that setting prevents routing.

LIMIT_EXCEEDED remains 409 with retry none. When the request submits the quantity, param names it, including its array index; available_quantity or minimum_quantity gives the bound. Inventory shortages use 409 INVENTORY_INSUFFICIENT, with routing detail reasons location_ineligible or location_limit when applicable. When receiving a transfer with all four condition quantities, their sum must equal target_received_quantity; a mismatch returns 400 INVALID_REQUEST with detail INVALID_VALUE at lines[i].target_received_quantity.

VERSION_CONFLICT remains 409 with retry after_refresh. A stale caller assertion keeps its request field in param; a persistence race without an assertion omits param. Read the current resource before rebuilding the request with a new Idempotency-Key, because part of the write may have applied. An adjustment using an older inventory observation names lines[i].source_observation_sequence and applies nothing. A count apply checks saved observations and omits param.

Fulfillment approval refusals name action in param. A refused completed-fulfillment correction names the actual request field. Package quantity limits name the submitted quantity; an untyped capacity race returns VERSION_CONFLICT without param.

Return receipt verification and resolution creation return 409 LIMIT_EXCEEDED with retry none when a stored quantity or remaining value exceeds capacity. param is absent because the request supplies no value that can correct this limit. Receipt details identify the receipt and its current status, with the stored requested_quantity and remaining available_quantity; cancel a conflicting receipt or the current receipt before trying again. A stored resolution value limit identifies the parent Return and its current status, with maximum_money floored at zero. Read the resolutions and cancel an eligible conflicting or current resolution before trying again. Submitted resolution quantities above capacity keep param naming line_items[i].quantity.

A resolution retry whose stored reservation has lost its quantity returns 500 INTERNAL_ERROR with reason repair_required and retry none. Supported quantity changes preserve this reservation, so the shortage indicates a broken stored invariant. This error has no resource or quantity facts. Contact Flint support with the request_id. A retained RETURN_VALUE_EXCEEDED with no recorded param uniquely identifies this retry shortage and upgrades to the same 500 response. A retained param: line_items cannot distinguish a submitted bound, a reachable remaining-value limit, or a broken invariant, so it keeps the canonical 409 LIMIT_EXCEEDED fallback.

An ambiguous Return fulfillment choice now returns 400 INVALID_REQUEST with detail REQUIRED, instead of 409. param names line_items[i].fulfillment_id when creating or processing a Return, line_item.fulfillment_id when adding a line, or eligibility.selection.line_items[i].fulfillment_id in an eligibility preview. selectable_resources lists the candidates.

A return checkout refusal names the resolution in details[0].current_resource, replacing return_resolution_id. Use its checkout-session route. A duplicate fulfillment event names the existing event in current_resource, with param: external_event_id.

Retired codePublic codeReason or validation detail
FULFILLMENT_ACTIVE_SHIPMENT_EXECUTIONRESOURCE_IN_USE
FULFILLMENT_APPROVAL_REQUIREDACTION_NOT_ALLOWEDstatus_not_reached
FULFILLMENT_CHANGEDVERSION_CONFLICT
FULFILLMENT_COMPLETEDACTION_NOT_ALLOWEDterminal_status
FULFILLMENT_COMPLETED_DETAILS_REPLACEMENTACTION_NOT_ALLOWEDfield_locked
FULFILLMENT_COMPLETION_TIMESTAMP_REQUIRES_COMPLETEACTION_NOT_ALLOWEDstatus_not_reached
FULFILLMENT_CONFIGURATION_ACTION_REQUIREDACTION_NOT_ALLOWEDconfiguration_required
FULFILLMENT_EVENT_DEDUPE_CONFLICTALREADY_EXISTS
FULFILLMENT_EVENT_SUBJECT_INVALIDINTERNAL_ERRORrepair_required
FULFILLMENT_INACTIVEACTION_NOT_ALLOWEDterminal_status
FULFILLMENT_QUANTITY_EXCEEDS_AVAILABLELIMIT_EXCEEDED
FULFILLMENT_QUANTITY_EXCEEDS_LINE_ITEMLIMIT_EXCEEDED
FULFILLMENT_SHIPMENT_NOT_MUTABLEACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
FULFILLMENT_SHIPMENT_NOT_VOIDABLEACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
FULFILLMENT_SHIPMENT_TERMINALACTION_NOT_ALLOWEDterminal_status
FULFILLMENT_STATUS_CONFLICTVERSION_CONFLICT
FULFILLMENT_TERMINALACTION_NOT_ALLOWEDterminal_status
INVENTORY_COUNT_INCOMPLETEACTION_NOT_ALLOWEDstatus_not_reached
INVENTORY_ITEM_INACTIVEACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
INVENTORY_ITEM_UNAVAILABLEACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
INVENTORY_LOCATION_ALLOCATION_DISABLEDACTION_NOT_ALLOWEDconfiguration_required
INVENTORY_LOCATION_ALLOCATION_INACTIVEACTION_NOT_ALLOWEDconfiguration_required
INVENTORY_LOCATION_INELIGIBLEINVENTORY_INSUFFICIENTlocation_ineligible
INVENTORY_POLICY_UNAVAILABLEACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
INVENTORY_QUANTITY_CONFLICTLIMIT_EXCEEDED
INVENTORY_RECEIPT_CONFLICTLIMIT_EXCEEDED / VERSION_CONFLICTQuantity bound / persistence race
INVENTORY_ROUTING_LOCATION_LIMIT_EXCEEDEDINVENTORY_INSUFFICIENTlocation_limit
INVENTORY_SHORTAGEINVENTORY_INSUFFICIENT
INVENTORY_SOURCE_SEQUENCE_CHANGEDVERSION_CONFLICT
INVENTORY_TRANSFER_LINE_CONFLICTINVALID_REQUEST / ACTION_NOT_ALLOWED / LIMIT_EXCEEDEDNOT_ALLOWED for item or condition changes; field_locked for departed quantities or omitted durable lines; minimum_quantity for a quantity below canceled units
INVENTORY_UNAVAILABLEINVENTORY_INSUFFICIENT
LOCATION_NOT_ACTIVEACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
LOCATION_UNAVAILABLEACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
ORDER_INVENTORY_EXCEPTION_NOT_RESOLVABLEACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
ORDER_INVENTORY_EXCEPTION_UNRESOLVEDACTION_NOT_ALLOWEDunsupported_state with known status; otherwise not_offered
ORDER_NOT_FULFILLABLEACTION_NOT_ALLOWEDstatus_not_reached
PACKAGE_CHANGEDVERSION_CONFLICT
PACKAGE_PARENT_CHANGEDVERSION_CONFLICT
RETURN_CHECKOUT_REQUIREDACTION_NOT_ALLOWEDreturn_checkout
RETURN_COMPLETION_BLOCKEDACTION_NOT_ALLOWEDstatus_not_reached
RETURN_DISPOSITION_QUANTITY_EXCEEDEDLIMIT_EXCEEDED
RETURN_FULFILLMENT_ALLOCATION_AMBIGUOUSINVALID_REQUESTREQUIRED
RETURN_INSPECTION_QUANTITY_EXCEEDEDLIMIT_EXCEEDED
RETURN_LINE_CANCELLATION_CONFLICTLIMIT_EXCEEDED
RETURN_POLICY_CONFLICTACTION_NOT_ALLOWEDconfiguration_required
RETURN_RECEIPT_QUANTITY_EXCEEDEDLIMIT_EXCEEDEDStored receipt quantity exceeds capacity; no param
RETURN_SELF_SERVICE_NOT_ALLOWEDACTION_NOT_ALLOWEDnot_offered
RETURN_SHIPMENT_QUANTITY_EXCEEDS_AVAILABLELIMIT_EXCEEDED
RETURN_VALUE_EXCEEDEDLIMIT_EXCEEDED / INTERNAL_ERRORSubmitted quantity or reachable remaining-value limit: 409 LIMIT_EXCEEDED; historical absent param proves broken retry reservation: 500 INTERNAL_ERROR, repair_required
RETURN_VERSION_CONFLICTVERSION_CONFLICT
SHIPMENT_CHANGEDVERSION_CONFLICT
SHIPMENT_PACKAGE_ITEM_QUANTITY_EXCEEDS_FULFILLMENTLIMIT_EXCEEDED / VERSION_CONFLICTSubmitted quantity bound / persistence race
SHIPMENT_PACKAGE_NOT_MUTABLEACTION_NOT_ALLOWEDunsupported_state with recorded status and recorded or provable supported_actions; otherwise not_offered
SHIPMENT_PACKAGE_NOT_VOIDABLEACTION_NOT_ALLOWEDunsupported_state with recorded status and recorded or provable supported_actions; otherwise not_offered
SHIPMENT_PACKAGE_TERMINALACTION_NOT_ALLOWEDterminal_status

FULFILLMENT_EVENT_SUBJECT_INVALID remains 500, with INTERNAL_ERROR, reason repair_required, and retry none. Contact support with the request_id; resending fails until the stored subject is repaired. Receipt and package store races previously described as quantity limits now use VERSION_CONFLICT with retry after_refresh and no param or quantity bounds. A retained receipt conflict with the old param: lines identifies this race; an indexed lines[i].quantity remains a quantity bound. Read and rebuild instead of changing a quantity without a bound. Retained transfer errors use 400 INVALID_REQUEST with detail NOT_ALLOWED for an indexed inventory_item_id or condition, and 409 ACTION_NOT_ALLOWED with reason field_locked for omitted durable lines identified by param: lines. An old indexed requested_quantity cannot distinguish a departed quantity from a canceled minimum, so it retains LIMIT_EXCEEDED. These failures remain recorded under their Idempotency-Key. Retained failures and request-log reads use the new public codes.

Update error handling and regenerate SDKs from the published OpenAPI schema. See Error handling, Fulfillments, and Inventory.

  • API
  • Fulfillment

Named fulfillment request variants#

Fulfillment creation now publishes five named OpenAPI variants selected by the existing required type: shipment, pickup, local_delivery, digital, and service. Each variant includes the shared request fields and permits its matching details object without requiring it. Details for other types are excluded. SDK generators can use explicit mappings and titles for these models.

Fulfillment updates remain partial and have no type field. Supply at most one details field, matching the stored fulfillment type. A null details field still counts toward that limit. To create a shipment and package with a fulfillment, set shipment.packaging to single_package and supply shipment.package.

See Fulfillment and shipping for creating fulfillments and updating their details.

  • Breaking change
  • API
  • Orders
  • Fulfillment

One fulfillment status and a release hold action#

Superseded by Fulfillment lifecycle verbs.

Breaking: Fulfillment.status now reports all 14 lifecycle values, including accepted, on_hold, and no_show. The separate lifecycle_status, request_status, and quantity_effect fields have been removed. Read each order line's fulfillment_quantities for current quantity ownership; timeline events retain the quantity effect of each transition.

Filter merchant fulfillments with status, including multiple values. The lifecycle_status filter is no longer accepted. Held fulfillments include active_hold.previous_status and allow forward actions from that status or release_hold.

Send POST /v1/fulfillments/{id}/transitions with {"action":"release_hold"} to return to the pre-hold status. The action preserves schedules and progress timestamps and sends no buyer notification. It accepts expected_version, occurred_at, and reason_message; it does not accept buyer_notification_behavior. An active payment hold must lift before work can resume.

Buyers see the pre-hold status and no hold details. The buyer fulfillment list accepts the 13 non-hold status values and includes held work under its pre-hold status. status=on_hold is rejected.

  • API
  • Inventory

Named inventory request variants#

Inventory routing sources, reservation owners, adjustments, and transfer, reservation, and count actions publish named OpenAPI variants with titles and explicit discriminator mappings. Each branch includes its complete fields and constraints so SDK generators can expose it as a standalone model. Existing type, reason, and action values and request bodies stay the same.

Receiving a transfer still accepts either all four condition quantities or none. The schema expresses that rule without presenting the quantities as separate models.

See Inventory for routing, adjustments, and lifecycle actions.

  • Breaking change
  • API
  • Inventory

Inventory commands return resources and changed levels#

Stock commands return their subject and changed levels#

Inventory adjustment, receipt, reservation, transfer transition, and count transition results rename resulting_inventory_levels to inventory_levels. Each result contains its primary resource first and one entry per level the command touched. Count cancellation returns an empty inventory_levels array.

Result objects no longer include idempotency_key or inventory_movement_ids. The Idempotency-Key response header carries the command key. Resources keep their own create-key fields. Read movement IDs from adjustment, receipt, and count lines, or list inventory movements using the source_reference_type and source_reference_id filters.

Before, an adjustment returned:

JSON
{"data":{"inventory_adjustment":{"inventory_adjustment_id":"iadj_123"},"idempotency_key":"adjust-1","inventory_movement_ids":["invm_123"],"resulting_inventory_levels":[{"inventory_level_id":"ilvl_123"}]}}

After:

JSON
{"data":{"inventory_adjustment":{"inventory_adjustment_id":"iadj_123"},"inventory_levels":[{"inventory_level_id":"ilvl_123"}]}}

These examples abbreviate resource fields. Stock-moving reservation, transfer, and count transitions return their named result instead of the resource alone. The primary resource is the expected_version target.

Level updates return InventoryLevel#

PATCH /v1/inventory-levels/{inventory_level_id} returns the updated level directly, using the same schema as its GET response. InventoryLevelUpdateResult is removed.

Before:

JSON
{"data":{"inventory_level":{"inventory_level_id":"ilvl_123","safety_stock_quantity":2},"idempotency_key":"safety-1","inventory_movement_ids":["invm_123"],"resulting_inventory_levels":[{"inventory_level_id":"ilvl_123","safety_stock_quantity":2}]}}

After:

JSON
{"data":{"inventory_level_id":"ilvl_123","safety_stock_quantity":2}}

Idempotency replays keep the original status and expose replay evidence through Idempotency-Replayed and meta.idempotency_replayed. Replayed stock command results contain the levels produced by the original command, even when those levels have since changed.

  • Breaking change
  • API
  • Invoices

Invoice reads match draft write shapes#

Merchant invoice responses now include collection and payment_due objects that you can send back when updating a draft. They replace the top-level collection_mode, payment_method_id, and payment_policy. Defaults resolve when you write; reads return the resolved mode and due type. payment_due.type: date replaces absolute. The top-level due_at remains the effective due instant.

Invoices include a read-only, nullable subscription_id, copied from the backing order when the draft is created. Filter GET /v1/invoices by subscription_id for an exact match. The query search also matches po_number.

Use service_date in YYYY-MM-DD format in place of service_at. Documents display that calendar date without timezone conversion. scheduled_issue_at replaces scheduled_send_at; late fees return waiver_reason_message in place of waiver_reason; activities return rail in place of payment_rail. Payment attempt and activity rails no longer include manual: manual payments are separate resources.

Clearable invoice fields are always present and nullable: recipient_email, reference, po_number, memo, footer, service_date, scheduled_issue_at, and external_reference_id. Empty cc_emails and schedule_entries are arrays. The public snapshot no longer repeats memo, footer, reference, or the service date; read them on the invoice itself. Buyer invoices include subscription_id and service_date and retain their existing collection_mode field, without the merchant's collection or payment_due objects.

Quick-pay invoice creation accepts the same tax and delivery_destination inputs as order creation. Validation errors name the fields under quick_pay.

Payment-term days and late-fee grace periods publish their enforced range of 0 to 365. Payment-term days of the month range from 1 to 31 and clamp to the month's last day. Late-fee percentages are greater than 0 and at most 100 and apply to base_outstanding_money.

These changes apply to all supported API versions.

  • API

Find invoices and credit notes with additional filters#

Merchant invoice lists now accept invoice_number, collection_mode, issued_after, issued_before, updated_after, and updated_before. Invoice numbers match the complete value byte for byte, including casing and whitespace. Collection modes accept repeated keys or comma-separated values: buyer_initiated, automatic, and external.

Merchant credit note lists now accept customer_id to select the source invoice's current customer, and reason to select one or more correction reasons. Request expand=invoice on credit note lists or detail reads to include the invoice summary. Expansion requires invoice read access as well as credit note read access.

All filters apply before pagination. Timestamp windows include the lower bound and exclude the upper bound; unissued invoices do not match issued-time bounds. A valid lookup without a match returns an empty page. Changing an effective filter requires a new pagination sequence; changing expand does not.

  • Breaking change
  • API
  • Invoices

Invoice manual payments have IDs and full reversals#

Each offline invoice payment is now an invoice_manual_payment with a stable invoice_manual_payment_id starting with omp_. POST /v1/invoices/{invoice_id}/manual-payments returns 201 with data.invoice_manual_payment and data.invoice. Send the check, wire, or bank reference as payment_reference; external_reference_id is no longer accepted on this request.

List payments at GET /v1/invoices/{invoice_id}/manual-payments or retrieve one at GET /v1/invoices/{invoice_id}/manual-payments/{invoice_manual_payment_id}. The list includes reversed payments, ordered by newest received_at first, then descending payment ID. Manual payments are separate from invoice payment attempts.

Reverse a specific payment in full with POST /v1/invoices/{invoice_id}/manual-payments/{invoice_manual_payment_id}/reverse. The body accepts expected_version, reversed_at, and reversal_note. Both writes return the invoice so you can use its version for the next expected_version. The amount-only /manual-payments/reverse route has been removed. To correct an amount, reverse the payment and record the correct payment. Reversing restores that payment's amount to the invoice balance. Reversal accepts an optional idempotency key; repeating a successful reversal without a key returns 409 ACTION_NOT_ALLOWED.

Subscribe to invoice_manual_payment.created and invoice_manual_payment.reversed in place of invoice.manual_payment_recorded and invoice.manual_payment_reversed. Their data.object snapshots contain the manual payment resource. Invoice status events continue to carry the invoice. Manual payment activities now include invoice_manual_payment_id.

A gift card load's source.order_manual_payment_id identifies the manual payment that funded it. Reversing one payment reverses its own allocations, including when two payments have the same amount. These changes apply to all supported API versions.

  • Breaking change
  • API
  • Errors
  • Onboarding
  • Merchants

Merchant readiness errors use MERCHANT_NOT_READY#

Merchant readiness errors now return 409 MERCHANT_NOT_READY. Read details[0].reason to distinguish onboarding, billing suspension, review, missing processor configuration, capability requirements, account setup repair, and account-session availability. These failures have remediation.retry: none; follow next_steps before submitting another request with a new idempotency key. Account setup repairs and unavailability identify error_source: flint.

Immutable onboarding fields return 409 ACTION_NOT_ALLOWED with reason field_locked and the actual request field in param. Provider-managed profiles use managed_externally; an unverified merchant-account domain uses status_not_reached. Conflicting signup emails and first API keys use 409 ALREADY_EXISTS. Duplicate identity records use 409 ACTION_NOT_ALLOWED with reason reconciliation_required and error_source: flint.

Missing or invalid merchant selections now return 400 INVALID_REQUEST on merchant_id, with detail code REQUIRED or INVALID_VALUE. details[0].selectable_resources replaces selectable_merchants: merchant choices have resource_type: merchant, resource_id, and an optional display_name instead of merchant_id and business_name. Invalid targeted account-session requirements also return 400 INVALID_REQUEST with INVALID_VALUE details naming the array and offending items.

A readiness failure does not name stored account context as a request param. Capability failures carry a capability fact when known. TAX_CATEGORY_REQUIRED remains a resource blocked reason and is not an error envelope code.

Previous codeNew codeReason or detail code
ACCOUNT_SETUP_CONFIGURATION_CONFLICTMERCHANT_NOT_READYaccount_setup_repair_required
ACCOUNT_SETUP_REPAIR_REQUIREDMERCHANT_NOT_READYaccount_setup_repair_required
ACCOUNT_SETUP_UNAVAILABLEMERCHANT_NOT_READYaccount_setup_unavailable
CAPABILITIES_IMMUTABLEACTION_NOT_ALLOWEDfield_locked
CAPABILITY_NOT_REQUESTEDMERCHANT_NOT_READYcapability_not_requested
COUNTRY_IMMUTABLEACTION_NOT_ALLOWEDfield_locked
DEFAULT_ENVIRONMENT_REQUIREDMERCHANT_NOT_READYdefault_environment_required
EMAIL_ALREADY_LINKEDALREADY_EXISTSNone
INITIAL_API_KEY_ALREADY_CREATEDALREADY_EXISTSNone
INVALID_MERCHANT_SELECTIONINVALID_REQUESTINVALID_VALUE
MERCHANT_ACCOUNT_DOMAIN_NOT_VERIFIEDACTION_NOT_ALLOWEDstatus_not_reached
MERCHANT_ACCOUNT_NOT_READYMERCHANT_NOT_READYonboarding_required
MERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_REPAIR_REQUIREDMERCHANT_NOT_READYaccount_setup_repair_required
MERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_REQUIREDMERCHANT_NOT_READYonboarding_required
MERCHANT_ACCOUNT_SESSION_ACCOUNT_SETUP_UNAVAILABLEMERCHANT_NOT_READYaccount_setup_unavailable
MERCHANT_ACCOUNT_SESSION_CONTROLLER_MISMATCHMERCHANT_NOT_READYaccount_sessions_unavailable
MERCHANT_ACCOUNT_SESSION_INELIGIBLEMERCHANT_NOT_READYaccount_sessions_unavailable
MERCHANT_ACCOUNT_SESSION_PROVIDER_GRANT_MISMATCHMERCHANT_NOT_READYaccount_setup_repair_required
MERCHANT_ACCOUNT_SESSION_TARGETED_REMEDIATION_UNAVAILABLEINVALID_REQUESTINVALID_VALUE
MERCHANT_ACCOUNT_SESSION_UNMAPPABLE_REQUIREMENT_IDINVALID_REQUESTINVALID_VALUE
MERCHANT_BILLING_SUSPENDEDMERCHANT_NOT_READYbilling_suspended
MERCHANT_ONBOARDING_REQUIREDMERCHANT_NOT_READYonboarding_required
MERCHANT_PROCESSING_RESTRICTEDMERCHANT_NOT_READYprocessing_restricted
MERCHANT_SELECTION_REQUIREDINVALID_REQUESTREQUIRED
MERCHANT_UNDER_REVIEWMERCHANT_NOT_READYunder_review
MULTIPLE_IDENTITIES_FOUNDACTION_NOT_ALLOWEDreconciliation_required
ONBOARDING_CONTROLLER_VERSION_UNSUPPORTEDMERCHANT_NOT_READYaccount_setup_repair_required
ONBOARDING_PROFILE_PROVIDER_MANAGEDACTION_NOT_ALLOWEDmanaged_externally
PAYMENT_PROCESSING_NOT_ENABLEDMERCHANT_NOT_READYprocessing_not_enabled
PAYMENT_PROCESSOR_UNAVAILABLEMERCHANT_NOT_READYprocessor_not_configured
PROCESSING_FEE_PRICING_NOT_AUTHORIZEDMERCHANT_NOT_READYpricing_not_authorized
PROCESSOR_NOT_CONFIGUREDMERCHANT_NOT_READYprocessor_not_configured
PROVIDER_ACCOUNT_CLEANUP_REQUIREDMERCHANT_NOT_READYaccount_setup_repair_required
TAX_CATEGORY_REQUIREDResource blocked reason onlytax_category_required on retained envelope inputs
TEST_PROCESSOR_NOT_CONFIGUREDMERCHANT_NOT_READYprocessor_not_configured
UNSUPPORTED_PROCESSORMERCHANT_NOT_READYprocessor_not_configured
  • API
  • Invoices
  • Gift-cards
  • Feedback
  • Reports
  • Promotions

Named API variants for invoices, gift cards, and feedback#

The OpenAPI contract publishes complete, named models for the existing variants in invoice collection, payment terms, schedules, credit note corrections, gift card funding and redemption, feedback reports, report statuses, tax breakdowns, and promotion recurrence. Each variant has a title and an explicit discriminator mapping so SDK generators can expose its fields and selection rules.

Existing selectors and request behavior stay the same. Gift card funding requirements are expressed as conditions on the funding source. Feedback fields describe the discussed product, the submitting client, and when sentiment or a summary is required.

See the invoicing, reporting, and promotions guides and the gift cards reference for the existing request shapes.

  • Breaking change
  • API
  • Errors
  • Orders

Order errors use shared codes and precise reasons#

Superseded by Confirm order payments through their payment intents.

The order errors below now use the shared public vocabulary, including order reconciliation. Branch on code, then details[0].reason where present. Messages remain human-readable and can change.

Retired codePublic response
AUTOMATIC_TAX_CONNECTION_REQUIRED409 ACTION_NOT_ALLOWED, reason configuration_required
AUTOMATIC_TAX_ORIGIN_ADDRESS_REQUIRED409 ACTION_NOT_ALLOWED, reason configuration_required
AUTOMATIC_TAX_UNAVAILABLE409 LIMIT_REACHED, reason monthly_tax_calculations, for the monthly budget; 503 SERVICE_UNAVAILABLE, reason repair_required, for provider or setup failures
CATALOG_LINE_ITEM_CURRENCY_CHANGED409 ACTION_NOT_ALLOWED, reason not_offered
CATALOG_LINE_ITEM_SOURCE_CHANGED409 ACTION_NOT_ALLOWED, reason not_offered
DISCOUNT_NOT_REMOVABLE409 ACTION_NOT_ALLOWED, reason unsupported_state for its current status or not_offered for an automatic promotion
INVALID_ORDER_STATUS409 ACTION_NOT_ALLOWED, reason unsupported_state
INVALID_STATUS_TRANSITION409 ACTION_NOT_ALLOWED, reason unsupported_state, for checkout state; 400 INVALID_REQUEST, detail INVALID_VALUE, for an invalid product status
INVOICE_LOCKED_ORDER_FINANCIALS409 RESOURCE_IN_USE
NO_DISCOUNTABLE_BALANCE409 PROMOTION_DECLINED, reason no_discountable_balance; request validation uses 400 INVALID_REQUEST, detail NOT_ALLOWED
ORDER_ALREADY_PAID409 ACTION_NOT_ALLOWED, reason payment_collected
ORDER_CHANGED_REFRESH_REQUIRED409 VERSION_CONFLICT for stale assertions and changes requiring review; 409 LIMIT_EXCEEDED for payment capacity; 400 INVALID_REQUEST with detail NOT_ALLOWED for amount_money.currency
ORDER_CHECKOUT_SESSION_CHANGED409 VERSION_CONFLICT
ORDER_COLLECTION_ALREADY_ACTIVE409 RESOURCE_IN_USE
ORDER_COLLECTION_IN_PROGRESS409 RESOURCE_IN_USE
ORDER_CONFLICT409 VERSION_CONFLICT
ORDER_CUSTOMER_ALREADY_SET409 ACTION_NOT_ALLOWED, reason field_locked
ORDER_CUSTOMER_CHECKOUT_ACTIVE409 RESOURCE_IN_USE
ORDER_CUSTOMER_NOT_UPDATABLE_AFTER_PAYMENT409 ACTION_NOT_ALLOWED, reason field_locked
ORDER_DELIVERY_DESTINATION_REPRICE_REQUIRED409 ACTION_NOT_ALLOWED, reason payment_collected
ORDER_FINANCIAL_MUTATION_NOT_ALLOWED409 ACTION_NOT_ALLOWED, reason payment_collected
ORDER_HAS_COLLECTED_MONEY409 ACTION_NOT_ALLOWED, reason payment_collected
ORDER_NOT_OPEN409 ACTION_NOT_ALLOWED, reason terminal_status for closed orders or payment_collected for fully paid orders
ORDER_PAYMENT_CUSTOMER_MISMATCH400 INVALID_REQUEST, detail NOT_ALLOWED, for a known request-field mismatch; stored customer assignments use 409 ACTION_NOT_ALLOWED, reason not_offered, without param
ORDER_PAYMENT_INTENT_CREATE_IN_PROGRESS409 IDEMPOTENCY_KEY_IN_PROGRESS
ORDER_PAYMENT_INTENT_CREATE_REQUIRES_REVIEW409 ACTION_NOT_ALLOWED, reason reconciliation_required
ORDER_PAYMENT_LEG_ALREADY_SETTLED409 ACTION_NOT_ALLOWED, reason payment_collected
ORDER_PAYMENT_LEG_CHECKOUT_ACTIVE409 RESOURCE_IN_USE
ORDER_RECEIPT_EMAIL_ON_FILE409 ACTION_NOT_ALLOWED, reason field_locked
ORDER_RECEIPT_EMAIL_UNAVAILABLE409 ACTION_NOT_ALLOWED, reason configuration_required
ORDER_RECEIPT_MERCHANT_MANAGED409 ACTION_NOT_ALLOWED, reason merchant_managed_email
ORDER_RECEIPT_NOT_AVAILABLE409 ACTION_NOT_ALLOWED, reason status_not_reached
ORDER_RECEIPT_RECIPIENT_LIMIT_REACHED409 LIMIT_REACHED, reason receipt_recipients
ORDER_RECONCILIATION_REQUIRED409 ACTION_NOT_ALLOWED, reason reconciliation_required
ORDER_TAX_NOT_READY409 ACTION_NOT_ALLOWED, reason configuration_required or return_tax_mismatch
ORDER_TAX_NOT_UPDATABLE409 ACTION_NOT_ALLOWED, reason payment_collected or return_tax_mismatch
ORDER_TOTALS_UNAVAILABLE500 INTERNAL_ERROR, reason repair_required
ORDER_TOTAL_BELOW_NET_COLLECTED409 LIMIT_EXCEEDED
PAID_LINE_ITEM_MODIFIER_CHANGE_FORBIDDEN409 ACTION_NOT_ALLOWED, reason payment_collected
PAID_LINE_ITEM_PRICE_CHANGE_FORBIDDEN409 ACTION_NOT_ALLOWED, reason payment_collected
PAID_LINE_ITEM_QUANTITY_CHANGE_FORBIDDEN409 ACTION_NOT_ALLOWED, reason payment_collected
PAID_LINE_ITEM_QUANTITY_DECREASE_FORBIDDEN409 LIMIT_EXCEEDED
PAID_LINE_ITEM_REMOVAL_FORBIDDEN409 ACTION_NOT_ALLOWED, reason payment_collected
PAID_LINE_ITEM_TAX_CHANGE_FORBIDDEN409 ACTION_NOT_ALLOWED, reason payment_collected
TIP_ALLOCATION_CAPACITY_EXCEEDED409 ACTION_NOT_ALLOWED, reason reconciliation_required

A stale order assertion returns VERSION_CONFLICT with the field as sent in param: expected_version, expected_outstanding_money, or accepted_gift_card_allocation.order_version. The detail carries current_version, current_money, or the frozen attempt's expected_attempt_outstanding_money. Read the resource and rebuild the request with a new Idempotency-Key. A payment-time change without a caller assertion omits param. A lost write race uses retry after_refresh, including writes without a fence. If Flint cannot read the current basis after a proven no-effect race, it returns INTERNAL_ERROR with retry same_request. Payment operations that already had an effect remain protected from unchanged retries.

Payment-capacity refusals now use retry none. Change the payment amount or selected legs; an amount whose currency differs from the order uses INVALID_REQUEST with detail NOT_ALLOWED and param: amount_money.currency. Payment-intent review, order reconciliation, and tip-allocation reconciliation use 409 ACTION_NOT_ALLOWED with reason reconciliation_required, retry none, and error_source: flint. Don't retry or start another payment to work around it. Tell buyers to contact the merchant. Merchant servers can contact Flint support with the request ID and resource ID if the outcome remains unresolved. A totals invariant failure uses 500 INTERNAL_ERROR with reason repair_required and retry none.

Error facts use generic references: the owning order or checkout session is in current_resource, and unpaid payment intents are in blocking_resources. collected_money becomes current_money; required_money becomes minimum_money; tip_capable_money becomes maximum_money; gap_money is removed. A paid-order destination refusal keeps shipping_money, requoted_shipping_money, tax_money, and requoted_tax_money when known, with reason payment_collected. A paid line quantity decrease carries minimum_quantity. The order total floor has no param: minimum_money is the collected money plus any unpaid tip, and current_money is the resulting order total. Retained records keep their captured numbers.

Catalog options that no longer match the order use ACTION_NOT_ALLOWED with reason not_offered. Incomplete retained discount or order-state refusals without lifecycle facts also use not_offered. Flint does not invent a status for these records. New state refusals use unsupported_state only with the resource's actual current_status. Receipt, automatic-tax configuration, and tax-readiness refusals omit legacy field pointers absent from the request. Retained order-owned payment refusals omit param and identify the owning order in current_resource; new ownership refusals keep order_owned and the order route in remediation.next_actions.

A customer mismatch caused by a request field uses INVALID_REQUEST with detail NOT_ALLOWED and names that field in param. A mismatch in the order's stored payment or saved-card customer assignment uses ACTION_NOT_ALLOWED with reason not_offered, identifies the order, and omits param. PayOrder cannot change that assignment. Retained customer-mismatch failures use the same refusal.

Receipt refusals use ACTION_NOT_ALLOWED with merchant_managed_email, status_not_reached, field_locked, or configuration_required; the recipient quota is LIMIT_REACHED with reason receipt_recipients. These conditions keep retry none.

Retained idempotency failures use the same mapping when replayed. A same-key replay returns the stored refusal; it does not execute a new payment or turn a version conflict into an automatic retry. Update error handling and regenerate SDKs from the published OpenAPI schema.

  • API
  • Orders
  • Payments
  • Refunds

Named order, payment, refund, and OAuth variants#

OpenAPI now publishes named models with titles and explicit discriminator mappings for order payment actions, modifier group sources, order tax calculation modes, refund types, refund tender allocations, and OAuth token grants. Each model includes the shared fields and the fields and constraints specific to that variant.

Selector names, values, and request behavior are unchanged. OAuth accepts authorization code, refresh token, device code, and workload identity token exchange grants at the same token endpoint. External order tax calculations permit omitted or empty components; nonempty components require additive prices.

See Orders, Refunds, and Partner app installs for request examples.

  • Breaking change
  • API
  • Fulfillment
  • Shipping

Ship with tracking and correct delivered packages#

mark_shipped now accepts carrier, service_code, tracking_number, and tracking_url. Flint applies them before the status change and shipped email, in one transaction. Omitted fields stay unchanged; null is invalid. Other package actions reject these fields.

Package descriptive fields remain editable with PATCH until the package is voided, including after delivery and fulfillment completion. Shipment references and metadata remain editable until the shipment is voided. Corrections never email the buyer. Items, new packages, and voids keep their pre-handoff restrictions.

Breaking: FULFILLMENT_INACTIVE on shipment execution routes, FULFILLMENT_TERMINAL, FULFILLMENT_SHIPMENT_NOT_MUTABLE, FULFILLMENT_SHIPMENT_TERMINAL, SHIPMENT_PACKAGE_NOT_MUTABLE, and SHIPMENT_PACKAGE_TERMINAL refusals now return 409 ACTION_NOT_ALLOWED. Branch on details[0].reason: terminal_status for terminal fulfillments and voided resources; unsupported_state for structural changes after handoff or refused transitions on delivered shipments. Details identify the refusing resource and its public current_status. remediation.retry is none.

The shipment list's query description now lists shipment IDs and external references; it does not promise tracking-number search.

  • API

Find payments, customers, checkout sessions, and risk list entries#

Superseded by The checkout session surface embedded is now headless.

Merchant list routes now support these filters before pagination:

  • Payment intents and refunds: currency works with or without amount bounds. It selects the parent resource's amount_money.currency. Send a three-letter uppercase ISO 4217 code without surrounding whitespace. Amount bounds still require currency; an explicitly empty currency is invalid.
  • Customers: segment matches the complete value byte for byte, including whitespace and Unicode. is_merchant_verified=true|false selects merchant verification. phone matches a complete E.164 number; encode its plus sign as %2B. Existing email lookup trims input and matches the whole address without distinguishing case or accents.
  • Checkout sessions: subscription_plan_id, invoice_id, and surface=hosted|embedded. Surface accepts repeated keys or comma-separated values.
  • Disputes: updated_after and updated_before select changes to the public dispute, with an inclusive lower bound and an exclusive upper bound.
  • Payment method domains: domain_name matches the complete hostname after the existing trimming, lowercase normalization, and validation.
  • Risk lists: alias matches a valid lowercase alias. Archived lists still require status=archived.
  • Risk list items: value matches the complete value after the parent list's item-type normalization. Responses retain the original stored value. Encode plus signs as %2B.

List currency filters, including buyer routes, validate the value as submitted. Lowercase or padded values return 400 INVALID_REQUEST with detail code INVALID_VALUE and param: currency. This corrects the earlier trimming and uppercasing description before release.

Correction: the customer email filter ignores case but keeps accents, so josé@example.com doesn't match jose@example.com. The sentence above that says it ignores accents was wrong.

A valid lookup with no match returns an empty page. Changing an effective filter requires starting a new pagination sequence. These additional filters apply to merchant routes. Buyer payment and refund currency filters still require amount bounds. See the range and sort naming changes for the previously shipped names.

  • API
  • Payments
  • Webhooks

Deleted payment methods report archived#

Deleting a payment method now returns status: archived, including repeated deletes. The card stays readable by ID and cannot be charged again. Use status=archived to list archived cards; status=removed is no longer accepted.

GET /v1/payment-methods and GET /v1/me/payment-methods now list active, pending, failed, and expired payment methods by default. Add status=active to card pickers that need cards you can charge. Checkout session credentials still list only active cards. Page tokens issued for merchant and buyer account lists with the old default filter no longer match. Restart those lists from the first page.

The deletion event is now payment_method.archived, replacing payment_method.removed. Existing endpoint subscriptions to the previous name receive the new event name. Both payment_method.archived and payment_method.failed carry payment method snapshots.

The two payment method set-default routes have been removed. Set default_payment_method_id with PATCH /v1/customers/{customer_id} or PATCH /v1/me; send null to clear it. Changing the default, including deleting the default card, advances the customer's version and sends customer.updated.

  • Breaking change
  • API
  • Errors

protocol_error replaces invalid_request_error, and request logs use error_type#

Breaking: branch on protocol_error, not invalid_request_error. The error type for HTTP 405, 410, 413, 415, and 499 is now protocol_error. These requests broke an HTTP-level rule (the method, the API version, the body size, or the content type), or your client closed the request before Flint responded. Error codes, statuses, and messages are unchanged. 400 responses still use validation_error, and no response uses invalid_request_error anymore.

Request logs and resource timeline entries for API requests replace error_category with error_type. It is the type of the error response for the logged status_code, so the value you read from a log matches the value your client received. Webhook delivery fields are unchanged.

Who is affected

  • Callers that compare error.type with invalid_request_error, or that route 405, 410, 413, or 415 responses by that type.
  • Anything that reads error_category from GET /v1/developer/request-logs, its detail route, or resource timelines.

How to migrate

  1. Replace invalid_request_error with protocol_error in your type checks. Branching on code or the HTTP status needs no change.
  2. Read error_type where you read error_category. Its values are the error types listed in Error handling, such as validation_error or not_found_error, not the old category names.
  3. Treat an unfamiliar error_type like an unfamiliar type: fall back to the HTTP status class.

Regenerate SDKs from the published OpenAPI schema to pick up the new type value and the renamed log field.

  • Breaking change
  • API
  • Refunds
  • Payouts

Refund and payout errors use shared codes#

Refund and payout refusals now use shared public error codes in every supported API version. This is a breaking change.

  • Amounts or quantities over the remaining refundable value, and payouts over the available balance, return 409 LIMIT_EXCEEDED. param identifies the input to change; money and quantity bounds describe that input when known.
  • An exhausted refund returns 409 ACTION_NOT_ALLOWED with reason already_applied. If a dispute or bank return consumed the money, the reason is payment_disputed, with the dispute in blocking_resources when known.
  • Other refund refusals use ACTION_NOT_ALLOWED with refund_unavailable or status_not_reached. Stored flat tax refund data that needs repair returns 500 INTERNAL_ERROR with repair_required.
  • Payout readiness failures return 409 MERCHANT_NOT_READY with a registered reason and the affected capability. Cancellation and configuration refusals use ACTION_NOT_ALLOWED; unsupported_state includes the payout's actual status, and automatic payout cancellation uses not_offered.
  • A gift card refund that needs a replacement destination returns 400 INVALID_REQUEST with detail REQUIRED on the destination field, including indexed tender allocation fields.

Refund and payout retry policies and idempotency keys retain their existing meaning. A terminal failure replays through the current error vocabulary. Read the existing refund or payout before deciding whether to create another movement.

Previous codeCurrent codeReason or detail
AFFIRM_REFUND_RETRY_NOT_ALLOWEDACTION_NOT_ALLOWEDrefund_unavailable
AMOUNT_EXCEEDS_REFUNDABLELIMIT_EXCEEDEDomitted
AUTOMATIC_PAYOUT_NOT_CANCELABLEACTION_NOT_ALLOWEDnot_offered
DEFAULT_PAYOUT_DESTINATIONS_MANAGED_EXTERNALLYACTION_NOT_ALLOWEDmanaged_externally
DEFAULT_PAYOUT_DESTINATION_INVALIDACTION_NOT_ALLOWEDconfiguration_required
DEFAULT_PAYOUT_DESTINATION_REPLACEMENT_REQUIREDACTION_NOT_ALLOWEDconfiguration_required
DEFAULT_PAYOUT_DESTINATION_REQUIREDACTION_NOT_ALLOWEDconfiguration_required
FLAT_TAX_PAYMENT_ATTRIBUTION_UNAVAILABLEACTION_NOT_ALLOWEDrefund_unavailable
FLAT_TAX_REFUND_STATE_INVALIDINTERNAL_ERRORrepair_required
GIFT_CARD_PURCHASE_REFUND_CONFLICTLIMIT_EXCEEDEDomitted
GIFT_CARD_REFUND_DESTINATION_REQUIREDINVALID_REQUESTdetail REQUIRED (400)
INSTANT_PAYOUTS_UNAVAILABLEMERCHANT_NOT_READYcapability_unavailable
INSUFFICIENT_AVAILABLE_BALANCELIMIT_EXCEEDEDomitted
LINE_ITEM_REFUND_QUANTITY_EXCEEDS_REFUNDABLELIMIT_EXCEEDEDomitted
MONEY_MOVEMENT_OPERATION_BLOCKEDMERCHANT_NOT_READYassessment reason, or capability_unavailable
MONEY_MOVEMENT_PROVIDER_NOT_CONFIGUREDMERCHANT_NOT_READYprocessor_not_configured
NEW_ACCOUNT_PAYOUT_TERMS_ACTIVEACTION_NOT_ALLOWEDpayout_delay / payout_frequency
NOTHING_TO_REFUNDACTION_NOT_ALLOWEDalready_applied / payment_disputed
NOTHING_TO_REFUND_FOR_CHARGEACTION_NOT_ALLOWEDalready_applied
NOTHING_TO_REFUND_FOR_LINE_ITEMACTION_NOT_ALLOWEDalready_applied
NOTHING_TO_REFUND_FOR_TAX_BREAKDOWNACTION_NOT_ALLOWEDalready_applied
NO_PAYMENTS_FOR_ORDERACTION_NOT_ALLOWEDstatus_not_reached
ORDER_HAS_NO_REFUNDABLE_CHARGESACTION_NOT_ALLOWEDalready_applied
ORDER_HAS_NO_REFUNDABLE_LINE_ITEMSACTION_NOT_ALLOWEDalready_applied
PAYMENT_INTENT_DISPUTEDACTION_NOT_ALLOWEDpayment_disputed
PAYOUTS_NOT_ENABLEDMERCHANT_NOT_READYcapability_unavailable
PAYOUT_DELAY_PROVIDER_CONTROLLEDACTION_NOT_ALLOWEDmanaged_externally
PAYOUT_DESTINATIONS_MANAGEMENT_UNAVAILABLEMERCHANT_NOT_READYcapability_unavailable
PAYOUT_FEE_NOT_DETERMINABLEACTION_NOT_ALLOWEDnot_offered
PAYOUT_NOT_CANCELABLEACTION_NOT_ALLOWEDunsupported_state
PAYOUT_SETTINGS_MANAGED_EXTERNALLYACTION_NOT_ALLOWEDmanaged_externally
PAYOUT_SETTINGS_MANAGEMENT_UNAVAILABLEMERCHANT_NOT_READYcapability_unavailable
PAYOUT_STATUS_NOT_CANCELABLEACTION_NOT_ALLOWEDunsupported_state
REFUND_ADJUSTMENT_PAYMENT_INTENT_NOT_REFUNDABLEACTION_NOT_ALLOWEDrefund_unavailable
REFUND_ADJUSTMENT_REFUND_EXCEEDS_PAYMENT_INTENT_REFUNDABLELIMIT_EXCEEDEDomitted
REFUND_ADJUSTMENT_REFUND_EXCEEDS_REMAININGLIMIT_EXCEEDEDomitted
REFUND_SUBMISSION_DEADLINE_EXPIREDACTION_NOT_ALLOWEDrefund_unavailable
REFUND_TENDER_CAPACITY_CONFLICTLIMIT_EXCEEDEDomitted
STANDARD_PAYOUTS_UNAVAILABLEMERCHANT_NOT_READYcapability_unavailable
STANDARD_PAYOUT_REQUIRES_MANUAL_SCHEDULEACTION_NOT_ALLOWEDconfiguration_required
TAX_BREAKDOWN_REFUND_EXCEEDS_REMAININGLIMIT_EXCEEDEDomitted
  • Breaking change
  • API
  • Returns

Return processing shares completion mode and reports uncovered quantity#

Breaking: replace completion_behavior with completion_mode on POST /v1/returns/{return_id}/process. Use automatic instead of complete_when_ready and manual instead of leave_open. The old field returns 400 INVALID_REQUEST with detail code UNKNOWN_FIELD.

For both /process and /decide, omitting completion_mode on a requested Return uses the mode shared by pinned policies that set one, or automatic when none sets one. If pinned policies disagree, send an explicit manual or automatic value. On an open Return, omit completion_mode to keep its committed mode, or send that same value. A different value returns 409 ACTION_NOT_ALLOWED with reason field_locked and param: completion_mode.

Processing a requested Return requires a decision for every line. A missing decision or omitted line now returns 409 ACTION_NOT_ALLOWED with reason status_not_reached and identifies the line. On an open Return, omit each decision to keep committed terms, or repeat them unchanged. Changed terms return 409 ACTION_NOT_ALLOWED with reason field_locked.

Deciding remains atomic. To defer one line, decline its quantity or remove it with DELETE /v1/returns/{return_id}/line-items/{return_line_item_id} and open a separate Return for it.

completion_blockers now includes resolution_not_selected whenever a line has approved quantity available for a new resolution, alongside blockers for existing unfinished resolutions. This includes pending replacements waiting for fulfillment.

  • API
  • Returns

Returns publish status meanings and remove unused values#

Returns now describe the meaning of each decision, merchandise, and resolution status in the API reference, including request fields, list filters, and webhook payloads. Completion blocker and failure codes carry their published descriptions too.

merchandise_status no longer includes received. Once all expected merchandise arrives, the line reports the work that remains, such as inspection_required or disposition_required, or resolved when that work is finished. The removed value is also rejected by merchandise status filters.

ReturnResolution.status and its status filter no longer include partially_fulfilled. A line's resolution_status and its filter also exclude that value. The Return's aggregate resolution_status keeps partially_fulfilled for value delivered on some lines while others remain open.

Approving a line with manual resolution now sets its resolution_status, and the Return's, to not_selected until a resolution is proposed. The completion blocker is resolution_not_selected. Proposing a resolution changes the status to pending; canceling the proposal restores not_selected when no other resolution covers the line.

  • API
  • Payments

Save a card when confirming a standalone payment#

Send save_payment_method: true to POST /v1/payment-intents/{payment_intent_id}/confirm to save the card for the payment intent's customer_id with usage: off_session. Send it only when the buyer agreed on your page to later charges, including what you will charge and when. It accepts a card, Apple Pay, or Google Pay credential in stripe.confirmation_token created with setup_future_usage: off_session, or in payment_source_token. API keys and partner tokens also need payments.payment_methods.write.

If the bank requires authentication, current_payment_action carries it. That authentication covers both the payment and saving the card. Continue with an empty confirm body after the buyer completes it; the payment attempt keeps the original save choice.

Flint saves the card after approval, including a payment awaiting manual capture. Wait for payment_method.saved, then retrieve the payment intent to read payment_source.card.payment_method_id. The webhook can arrive before that field is written; if it is missing, read the payment intent again a moment later. A declined payment saves nothing. Order-owned payments continue to save through order pay.

  • Breaking change
  • API
  • Fulfillment

Ship an order in one call#

Package creation now requires status: created or status: shipped, including shipment.package with single_package on fulfillment creation. Update callers that previously omitted it.

Standalone package creation accepts optional items with the same fields as the package-item create route. Use status: shipped to record handoff in that call, with optional shipped_at and buyer_notification_behavior: send|suppress. The handoff time defaults to request time. The package, its items, timeline facts, notification intent, and derived fulfillment progress commit atomically.

Return packages require status: created. The single-package fulfillment input rejects items, return_line_items, and unknown fields instead of silently dropping them. Use status: created for label-first work and mark_shipped when the parcel leaves.

Fulfillment creation adds shipment.packaging: itemized with 1 to 20 shipment.packages, each with required items. Shipment creation adds optional outbound packages, with optional items, for checkout-created fulfillments. Each shipped box requests its own notification; partial coverage leaves the fulfillment unchanged. All changes commit together. These additions introduce no further breaking changes.

Shipment create returns packages when supplied. Read them later with GET /v1/shipments/{shipment_id}?expand=packages, up to 20 packages. Retry either create with the same idempotency key and body to recover the original IDs without duplicate notifications.

  • API
  • Subscriptions

See what a past-due subscription owes#

Past-due subscriptions now include outstanding_money when their failed renewal order has an unpaid balance. It includes tax, shipping and discounts, after payments and credits. Use it to show buyers how much they owe before they retry payment.

last_payment_error reports the latest renewal payment failure using Flint's payment failure codes, with message, failed_at, and merchant remediation. Buyer responses omit remediation and mask sensitive decline reasons.

Both fields appear on subscription reads, lists and webhook payloads. They are absent after the subscription leaves past_due, and outstanding_money is absent when nothing remains owed.

  • Breaking change
  • API
  • Subscriptions
  • Customers

Handle subscription and customer errors with shared codes#

Subscription and customer state refusals now return 409 ACTION_NOT_ALLOWED. Read details[0].reason for the constraint, such as not_offered, in_progress, or unsupported_state. State refusals include current_status when needed. Customer deletion identifies the customer with resource_type and resource_id.

Code quotas now return 409 LIMIT_REACHED with reason verification_codes or saved_card_codes. They have remediation.retry: none. Temporary throttles still return 429 RATE_LIMIT_EXCEEDED.

Buyer-account verification checks used, confirmed, expired, and exhausted state before comparing the code. A wrong code returns 400 INVALID_REQUEST with detail code INVALID_VALUE on code. Email changes keep one combined invalid-code answer: it omits param when both codes were required and names new_email_code when only the new address needed confirmation.

Subscription billing-date bounds return 400 INVALID_REQUEST with detail code INVALID_VALUE on next_billing_at. Incompatible request lines use NOT_ALLOWED; incompatible stored delivery configuration returns 409 ACTION_NOT_ALLOWED with reason configuration_required.

A conflicting subscription offer returns 409 ALREADY_EXISTS with the other offer in details[].current_resource. An active subscription payment retry returns 409 ACTION_NOT_ALLOWED with reason in_progress, retry none, and the retry in blocking_resources. Read that retry until its outcome is known before starting another. Replaying an idempotent request returns its stored response.

Update handlers for the following retired codes. The table lists the final HTTP status and either reason or a validation detail code.

Previous codeHTTP statusCodeReason or detail code
ACCESS_LINK_CUSTOMER_REQUIRED409ACTION_NOT_ALLOWEDconfiguration_required
ACCESS_LINK_MERCHANT_HOSTED409ACTION_NOT_ALLOWEDmerchant_hosted_customer_accounts
BILLING_INTERVAL_CHANGE_NOT_ALLOWED409ACTION_NOT_ALLOWEDnot_offered
CANCEL_IMMEDIATELY_NOT_ALLOWED409ACTION_NOT_ALLOWEDnot_offered
CHECKOUT_CUSTOMER_ALREADY_AUTHORIZED409ACTION_NOT_ALLOWEDalready_applied
CUSTOMER_DELETION_ALREADY_APPROVED409ACTION_NOT_ALLOWEDalready_applied
CUSTOMER_DELETION_BLOCKED409RESOURCE_IN_USENone
CUSTOMER_DELETION_PROCESSING409ACTION_NOT_ALLOWEDin_progress
CUSTOMER_DELETION_REQUEST_NOT_PENDING409ACTION_NOT_ALLOWEDunsupported_state
CUSTOMER_DELETION_STATE_CHANGED409VERSION_CONFLICTNone
CUSTOMER_EMAIL_BUYER_MANAGED409ACTION_NOT_ALLOWEDmanaged_externally
CUSTOMER_EMAIL_REQUIRED404RESOURCE_NOT_FOUNDNone
CUSTOMER_VERIFICATION_ALREADY_CONFIRMED409ACTION_NOT_ALLOWEDalready_applied
CUSTOMER_VERIFICATION_ATTEMPTS_EXHAUSTED409LIMIT_REACHEDverification_attempts
CUSTOMER_VERIFICATION_EMAIL_CHANGED409ACTION_NOT_ALLOWEDterminal_status
CUSTOMER_VERIFICATION_EXPIRED409ACTION_NOT_ALLOWEDterminal_status
CUSTOMER_VERIFICATION_LIMIT_REACHED409LIMIT_REACHEDverification_codes
CUSTOMER_VERIFICATION_NOT_CONFIRMED409ACTION_NOT_ALLOWEDstatus_not_reached
CUSTOMER_VERIFICATION_NOT_OFFERED409ACTION_NOT_ALLOWEDnot_offered
CUSTOMER_VERIFICATION_NOT_SENT409ACTION_NOT_ALLOWEDnot_offered
CUSTOMER_VERIFICATION_TEXT_UNAVAILABLE409ACTION_NOT_ALLOWEDnot_offered
CUSTOMER_VERIFICATION_USED409ACTION_NOT_ALLOWEDalready_applied
DELIVERY_UPDATE_NOT_ALLOWED409ACTION_NOT_ALLOWEDnot_offered
EMAIL_CHANGE_ALREADY_CONFIRMED409ACTION_NOT_ALLOWEDalready_applied
EMAIL_CHANGE_ATTEMPTS_EXHAUSTED409LIMIT_REACHEDverification_attempts
EMAIL_CHANGE_CONFIRMATION_EXPIRED409ACTION_NOT_ALLOWEDterminal_status
EMAIL_CHANGE_SUPERSEDED409ACTION_NOT_ALLOWEDterminal_status
EMAIL_PREFERENCE_LINK_INVALID404RESOURCE_NOT_FOUNDNone
ITEMS_REQUIRED409 / 400ACTION_NOT_ALLOWED / INVALID_REQUESTunsupported_state / REQUIRED
PAUSE_NOT_ALLOWED409ACTION_NOT_ALLOWEDnot_offered
PAYMENT_METHOD_SAVE_EMAIL_UNAVAILABLE409ACTION_NOT_ALLOWEDnot_offered
PAYMENT_METHOD_SAVE_NOT_PENDING409ACTION_NOT_ALLOWEDunsupported_state
PAYMENT_METHOD_SAVE_NOT_READY409ACTION_NOT_ALLOWEDstatus_not_reached
QUANTITY_CHANGE_NOT_ALLOWED409ACTION_NOT_ALLOWEDnot_offered
SAVE_PAYMENT_METHOD_CODE_LIMIT_REACHED409LIMIT_REACHEDsaved_card_codes
SAVE_PAYMENT_METHOD_NOT_OFFERED409ACTION_NOT_ALLOWEDnot_offered
SAVE_PAYMENT_METHOD_VERIFICATION_REQUIRED409ACTION_NOT_ALLOWEDverification_required
SKIP_LIMIT_REACHED409LIMIT_REACHEDconsecutive_skips
SKIP_NOT_ALLOWED409ACTION_NOT_ALLOWEDnot_offered
SUBSCRIPTION_DELIVERY_LINES_NOT_COMBINABLE400 / 409INVALID_REQUEST / ACTION_NOT_ALLOWEDNOT_ALLOWED / configuration_required
SUBSCRIPTION_DELIVERY_MIGRATION_IN_PROGRESS409OPERATION_IN_PROGRESSNone
SUBSCRIPTION_DELIVERY_MIGRATION_TARGET_UNAVAILABLE409ACTION_NOT_ALLOWEDunsupported_state
SUBSCRIPTION_DELIVERY_PROFILE_ACTION_REQUIRED409ACTION_NOT_ALLOWEDconfiguration_required
SUBSCRIPTION_DELIVERY_PROFILE_MISSING409ACTION_NOT_ALLOWEDconfiguration_required
SUBSCRIPTION_NEXT_BILLING_AT_BEFORE_PERIOD_START400INVALID_REQUESTINVALID_VALUE
SUBSCRIPTION_NEXT_BILLING_AT_TOO_FAR400INVALID_REQUESTINVALID_VALUE
SUBSCRIPTION_OFFER_ARCHIVED409ACTION_NOT_ALLOWEDarchived
SUBSCRIPTION_OFFER_NOT_ACTIVE409ACTION_NOT_ALLOWEDunsupported_state
SUBSCRIPTION_OFFER_PROMOTION_UNAVAILABLE409ACTION_NOT_ALLOWEDunsupported_state
SUBSCRIPTION_OFFER_TARGET_CONFLICT409ALREADY_EXISTSNone
SUBSCRIPTION_PAYMENT_RETRY_IN_PROGRESS409ACTION_NOT_ALLOWEDin_progress
SUBSCRIPTION_PAYMENT_RETRY_LIMIT_REACHED409LIMIT_REACHEDpayment_retries_per_period
SUBSCRIPTION_START_OVERRIDE_NOT_ALLOWED400INVALID_REQUESTNOT_ALLOWED
SWAP_NOT_ALLOWED409ACTION_NOT_ALLOWEDnot_offered

ITEMS_REQUIRED uses 409 ACTION_NOT_ALLOWED when removing the final stored subscription line. Missing request line items continue to return 400 INVALID_REQUEST with REQUIRED.

  • Breaking change
  • API
  • Webhooks

Webhook event catalog metadata and previous names#

Webhook event changes apply immediately to every supported API version:

  • enabled_events and test-event requests accept only current event names. Replace previous names with the current event_type from GET /v1/webhook-event-types.
  • The catalog returns every merchant and partner lifecycle event, ordered by event_type, with resource_type, kind (snapshot or notification), and previous_names. previous_names is always an array. The default page_size is now 100, the maximum; follow next_page_token for the remaining types.
  • Stored subscriptions and event reads map previous names to current names permanently. Event filters using a current name also match its previous names. Removed subscriptions are dropped; if none remain, the endpoint receives no events.
  • Test-event requests can name partner lifecycle events. The endpoint's event_sources must support the chosen type; check the catalog's event_sources before sending it.
  • Each OpenAPI webhooks entry publishes its kind as x-flint-event-kind.
  • API

Workload identity management#

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.

  • API

Exchange workload identity tokens for API access#

Superseded by Auth context describes each credential type.

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.

  • API
  • Customers
  • Checkout

Verification requests use the customer's email and purpose-specific fields#

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.

  • Breaking change
  • API
  • Catalog
  • Promotions

Catalog category filters and modifier rules#

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.

Buyer and merchant Return snapshots, including Return webhook payloads, also omit the bundle component's current delivery profile revision.

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.

  • Breaking change
  • API
  • Errors

Child lookups and resource state use 404 and 409#

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.

  • Breaking change
  • API
  • Errors

Configuration prerequisites return ACTION_NOT_ALLOWED#

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 change
  • API
  • Credit-notes

Credit note corrections and available credit#

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 change
  • API
  • Inventory

Inventory holds last up to 24 hours#

Superseded by Inventory lifecycle actions use their own routes.

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 change
  • API
  • Inventory

Control Location allocation with a boolean#

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 change
  • API
  • Delivery

Weight and dimensions share decimal shapes#

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.

  • API

OAuth discovery and public signing keys#

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.

  • Breaking change
  • API
  • Checkout
  • Delivery

One response schema per checkout and delivery operation#

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.

  • API

Rate-limit quota headers#

Responses to merchant credentials carry RateLimit-Policy and RateLimit, using the IETF draft-11 fields, with per-second and per-minute budgets for your credential and your merchant in the route's class. Browsers can read both fields through CORS. Retry-After on a class-budget 429 is now the exact whole seconds until the exhausted windows reset.

Quota fields are absent for buyer credentials, IP limits, requests refused before the route-class check, and when the shared limiter is unavailable. On a 429, honor Retry-After first and use Flint-Rate-Limited-Reason to identify the limiter, including customer for a budget shared by a customer's sessions.

  • Breaking change
  • API
  • Checkout
  • Payments
  • Customers
  • Developers

Resource responses for deletes, receipts, and checkout launches#

Delete responses#

Deleting a customer address, a saved buyer payment method, or a saved buyer gift card returns that resource instead of {"success": true}. An address and a saved gift card return their final snapshot. Removing a payment method returns its removal status.

Before:

JSON
{"data":{"success":true}}

After, for an address (other address fields omitted):

JSON
{"data":{"customer_address_id":"caddr_example","customer_id":"cus_example","address":{"line1":"123 Main Street","country":"US"}}}

A gift card that the buyer has never saved, or has already removed, returns 404. Retrying a successful removal with the same Idempotency-Key replays the snapshot recorded by that removal. Older removal records without a snapshot return 404 because they do not prove the buyer had saved access.

Payout destination DELETE no longer takes a JSON body. Promotion code DELETE continues to archive the code, which stays readable by ID.

Receipt actions#

Use POST /v1/payment-intents/{payment_intent_id}/send-receipt. It accepts standalone and order-owned payment intents. For an order-owned intent, it queues the order receipt. The recipient rules and rate limits are unchanged.

All three receipt actions return their subject: PaymentIntent, Order, or the buyer's order representation. Queuing a receipt does not change the returned resource. For payment intents, the receipt_sent activity records the send once it completes.

Before:

JSON
{"data":{"success":true}}

After, for a payment intent (other payment fields omitted):

JSON
{"data":{"payment_intent_id":"pi_example","status":"succeeded"}}

Checkout credentials and existing sessions#

Checkout creation, payment-link resolution, return-resolution checkout, and customer-verification confirmation return the checkout session's fields with checkout_auth_token beside them. A saved-card confirmation that keeps the current credential omits the token.

Before:

JSON
{"data":{"checkout_session":{"checkout_session_id":"cs_example"},"checkout_access":{"checkout_auth_token":"example"},"reused_existing":false}}

After:

JSON
{"data":{"checkout_session_id":"cs_example","checkout_auth_token":"example"}}

Invoice checkout keeps its resource members and puts the token directly beside them:

JSON
{"data":{"invoice":{"invoice_id":"inv_example"},"checkout_session":{"checkout_session_id":"cs_example"},"checkout_auth_token":"example"}}

Invoice and return-resolution checkout return 201 when they create a session and 200 when they return an existing session. reused_existing is removed. Idempotency-Key replays retain the original status, Idempotency-Replayed header, and meta.idempotency_replayed.

Setup and secret schemas#

Saving a payment method returns its fields with client_setup beside them, in PaymentMethodWithSetup or BuyerPaymentMethodWithSetup.

Before:

JSON
{"data":{"payment_method":{"payment_method_id":"pm_example"},"client_setup":{"stripe":{}}}}

After:

JSON
{"data":{"payment_method_id":"pm_example","client_setup":{"stripe":{}}}}

Creating a developer sandbox returns CreateDeveloperSandboxResult. When issue_test_key is true, api_key and its one-time secret_key sit beside sandbox.

Before:

JSON
{"data":{"sandbox_id":"test_example","api_key":{"api_key_id":"key_example","secret_key":"example"}}}

After:

JSON
{"data":{"sandbox":{"sandbox_id":"test_example"},"api_key":{"api_key_id":"key_example"},"secret_key":"example"}}

Customer-session credentials use CustomerSessionWithSecret. Webhook endpoint creation and secret rotation use WebhookEndpointWithSecret; ordinary endpoint reads omit secret. Payment intent creation and retrieval share PaymentIntentWithCollectionResponse, whose data is PaymentIntentWithCollection. These names identify a resource with response-only fields. Secret replay expiry remains unchanged.

  • Breaking change
  • API
  • Fulfillment
  • Risk
  • Orders
  • Subscriptions
  • Invoices

Fulfillment writes and command results use consistent response shapes#

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:

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

After:

JSON
{"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:

JSON
{"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:

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

After:

JSON
{"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:

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

After:

JSON
{"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:

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

After:

JSON
{"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:

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

After:

JSON
{"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:

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

After:

JSON
{"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.

  • API
  • Returns

Check buyer return eligibility and control reason availability#

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 change
  • API
  • Returns
  • Errors

Returns use generic validation and action refusal codes#

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.

  • Breaking change
  • API
  • Risk

Risk previews check list references and rule limits#

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.

  • Breaking change
  • API
  • Developers
  • Webhooks

Flint mints every request ID#

Superseded by param names the input to change.

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.

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.

  • API
  • Subscriptions

Match subscription offers to external systems and filter by update time#

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.

  • Breaking change
  • API
  • Tax
  • Errors

Tax errors distinguish request input from stored configuration#

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.

  • API
  • Orders
  • Fulfillment

Filter orders with unassigned fulfillment quantity#

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.

  • API

Product variants support unit weight and dimensions#

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 change
  • API
  • Catalog
  • Delivery

Unit measurements belong to items#

Breaking: Delivery profile configuration and delivery_profile.* webhook snapshots no longer include weight or dimensions. Sending either field in profile configuration returns UNKNOWN_FIELD.

Custom line inputs on orders, order line creation, delivery previews, and invoice quick pay now accept top-level unit_weight and unit_dimensions. The former fulfillment.weight and fulfillment.dimensions fields return UNKNOWN_FIELD. Lines with variant_id or bundle_id use catalog measurements and reject measurement overrides.

Order lines expose the unit measurements recorded when the line was created. These fields are omitted when unknown and for bundle lines. Delivery quotes use these recorded measurements; subscription renewal previews use current catalog measurements. Delivery rate callbacks omit total_weight_grams when any delivery obligation in the group has unknown weight.

  • Breaking change
  • API
  • Delivery

Delivery rates use variant unit weight#

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. Unit measurements belong to items removes the profile fields and replaces the custom line 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.

  • API
  • Disputes

Accept a dispute#

POST /v1/disputes/{dispute_id}/accept (acceptDispute) concedes a chargeback. It returns 200 with the dispute in status lost and sends dispute.lost once. Accepting can't be undone. It moves no money: the disputed amount already left your balance, and refunds on the payment stay blocked.

You can accept while status is needs_response and is_action_required is true. The route requires payments.disputes.write, takes no body or {}, and accepts an optional Idempotency-Key. Retry a 503 with the same key, or read the dispute: status: lost means it was accepted. The route uses the sensitive_write rate limit class. flint disputes accept asks for confirmation interactively, and scripts pass --confirm.

Any other state returns 409 ACTION_NOT_ALLOWED. Branch on details[0].reason:

  • already_applied: the dispute is already lost, including bank returns.
  • terminal_status: the dispute is won, prevented, or inquiry_closed.
  • in_progress: the dispute is under review, its response deadline has passed, or another request is accepting it.
  • unsupported_state: the dispute is other, has no response window, or is an inquiry. An inquiry can't be accepted; its error carries a create_refund next action, because a refund is how you concede an inquiry.

The new next action create_dispute_response_session appears when the payment processor declines to close a dispute that Flint still shows as eligible. The error is 409 ACTION_NOT_ALLOWED with reason unsupported_state. Open a response session and accept in the embedded component. The action requires payments.disputes.write and the dispute_id.

See Accept a dispute for the full flow.

  • Breaking change
  • API
  • Analytics

Analytics uses explicit periods and flat metrics#

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.
  • API
  • Customer-accounts
  • Returns

Buyer resource and Return request schemas#

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.

  • Breaking change
  • API
  • Catalog
  • Promotions

Catalog retirement is safe to repeat#

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.

  • Breaking change
  • API
  • Catalog

Edit active bundles and add options to live products#

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.

  • Breaking change
  • API
  • Catalog

Filter catalog lists by creation and update time#

Superseded by Product variant expansion and variant limit.

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 change
  • API
  • Checkout

The checkout credential is one Authorization bearer token#

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:

HTTP
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.

  • Breaking change
  • API
  • Checkout

Checkout creation uses an explicit type and shared buyer fields#

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 change
  • API
  • Delivery

Default delivery profiles use is_default#

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.

  • Breaking change
  • API
  • Catalog

Read files and attach images by file ID#

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.

  • Breaking change
  • API
  • Refunds
  • Gift-cards

Gift card redemption refunds use amount and state errors#

Breaking: POST /v1/refunds returns 409 AMOUNT_EXCEEDS_REFUNDABLE when a gift card redemption or payment intent allocation exceeds its remaining refundable value. This replaces REFUND_TENDER_CAPACITY_CONFLICT for that condition. param names tender_allocations[i].amount_money.amount, and details[0].maximum_money gives the remaining amount and currency. An amount_money above the remaining value of an order funded by gift cards uses the same code and fact, with param: amount_money.amount.

REFUND_TENDER_CAPACITY_CONFLICT still means the allocations don't cover the selected line items, charges, or flat tax.

Breaking: refunding a gift card redemption that hasn't been captured returns 409 ACTION_NOT_ALLOWED instead of REFUND_TENDER_CAPACITY_CONFLICT. param names tender_allocations[i].gift_card_redemption_id. details[0].reason is status_not_reached for a reserved redemption, which needs capturing first, or terminal_status for a canceled or expired redemption, which spent nothing. The details identify the redemption and its current_status when your credential can read it.

Breaking: GIFT_CARD_REFUND_DESTINATION_REQUIRED names tender_allocations[i].destination in param, replacing the coarse tender_allocations param. The details identify the original gift card and its current_status when your credential can read it. Choose destination: "new_gift_card" and submit the revised request with a new Idempotency-Key.

These errors return before Flint creates a refund. Correct the request and use a new key. Replaying a successful request with its original key recovers the same refund without crediting the card again.

Refunding a gift card redemption made outside an order is now documented on the gift cards page.

  • Breaking change
  • API
  • Inventory

Read inventory allocation policy revisions#

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.

  • Breaking change
  • API
  • Inventory

Inventory movements name their source and recording credential#

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 change
  • API
  • Inventory

Inventory transfers replace lines as one collection#

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.

  • API
  • Invoices
  • Orders
  • Tax

Invoice totals and frozen tax breakdowns#

Invoices now include total_money, equal to snapshot.pricing_amounts.total_money, and late_fee_money, the late fees assessed after issue minus waivers. The document total excludes late fees. written_off_money is always present in merchant invoice responses.

Shared pricing_amounts on orders and invoice snapshots now include additive_tax_money and inclusive_tax_money. Their sum equals tax_money. The total is subtotal_money - discount_money + charge_money + additive_tax_money + requested_tip_money, never below zero. Inclusive tax is already inside the prices and is not added again.

Invoice snapshot.tax_breakdowns previews the order's tax rows on a draft and freezes them at issue. External tax produces these jurisdiction rows; automatic tax does not. Each row identifies its line or charge when applicable. Newly issued external-tax invoices use these same rows on the hosted invoice and PDF.

Buyer invoice responses include the document total and net late fees. Expanded invoice summaries also include total_money. Invoice and order webhooks use the updated response shapes; no new events are added.

Idempotent replays keep their recorded response. Replays of mutations made before this deploy may lack the new fields within the idempotency window. They do not reload current invoice or order state to fill the gaps.

  • Breaking change
  • API
  • Payouts
  • Disputes
  • Orders
  • Balances
  • Risk

List filters and money sorts name their response fields#

Breaking: these list range parameters replace their previous names immediately. The removed names return UNSUPPORTED_QUERY_PARAM.

EndpointRemoved parametersReplacement parameters
GET /v1/balance-transactionscreated_after, created_beforeoccurred_after, occurred_before
GET /v1/reviewscreated_after, created_beforeopened_after, opened_before
GET /v1/payoutsarrival_after, arrival_beforearrival_date_from, arrival_date_to

Balance and review bounds remain RFC 3339 instants: the lower bound is inclusive and the upper bound is exclusive. Payout arrival bounds accept strict YYYY-MM-DD dates at midnight UTC: arrival_date_from is inclusive and arrival_date_to is exclusive. arrival_date_from=2026-09-01&arrival_date_to=2026-09-02 selects every arrival whose UTC date is September 1. Timestamps and timezone offsets are rejected. Payout created_after and created_before still filter creation time; balance available_after and available_before still filter availability.

Breaking: GET /v1/disputes replaces sort_by=amount with sort_by=amount_money, and the action_required filter with is_action_required, which matches the dispute field. GET /v1/orders and GET /v1/me/orders replace total_money with pricing_amounts.total_money and outstanding_money with settlement_amounts.outstanding_money. Removed sort values return INVALID_REQUEST. Money comparisons remain numeric in minor units.

These additions support bounded reconciliation and fulfillment queues:

  • created_after and created_before on /v1/credit-notes, /v1/packages, /v1/me/packages, /v1/fraud-warnings, /v1/payment-methods, and /v1/me/payment-methods. They filter created_at with an inclusive lower bound and exclusive upper bound, preserving each list's ordering and access rules. Fraud-warning creation time is independent of reported_at.
  • sort_direction=asc|desc on /v1/fulfillment-events, defaulting to desc for either received_at or occurred_at. Tied timestamps use the event ID in the same direction. The buyer event list retains its existing order.
  • Read-only nullable Fulfillment.scheduled_start_at, derived from the service start or pickup, local-delivery, or shipment window start. Digital and unbooked fulfillments return null. The existing common schedule sort places nulls first ascending and last descending, then sorts tied IDs in the same direction. Nested details remain the schedule inputs.
  • Breaking change
  • API
  • Merchant-billing
  • Reports

List merchant billing entries#

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.
  • Breaking change
  • API
  • Merchant-billing

Merchant billing uses one API vocabulary#

Superseded by Money fields now name what they measure.

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. The status filter accepts comma-separated or repeated values from open, paid, and written_off. The October 27 correction removes the unused statuses originally listed here.

  • Breaking change
  • API
  • Settings

Merchant settings and explicit patch rules#

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.
  • Breaking change
  • API
  • Partners

Partner OAuth follows the OAuth standards#

Superseded by Scope requirements and CLI sessions use explicit context rules, Partner apps mint one token per mode and name the merchant on each request.

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 change
  • API
  • Webhooks
  • Fulfillment

Webhooks report closed-order edits and shipment and package changes#

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.

  • Breaking change
  • API
  • Orders
  • Checkout

Line-item writes use the order version#

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.

  • API
  • Webhooks
  • Inventory

Partner apps can receive inventory events#

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 change
  • API
  • Payments
  • Orders
  • Errors

Payment and order state refusals use ACTION_NOT_ALLOWED#

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:

ReasonMeaning
already_appliedThe requested outcome is already reflected in the resource. Read it to confirm.
terminal_statusThis action is unavailable in the final status. Create a new resource if needed, or follow remediation.next_actions.
status_not_reachedComplete the required earlier step or wait for the resource to reach the required status.
in_progressWait for the operation already underway to finish, then read the resource before choosing an action.
field_lockedOmit the field named by param, or create a new resource with the value you need.
payment_collectedThe order is still open but payment has been collected, so its commercial fields cannot change.

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_email 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.

  • Breaking change
  • API
  • Payments
  • Webhooks

Payment intent responses share one collection 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 change
  • API
  • Payments
  • Orders

Payment intent create and confirm results#

Superseded by Open payment and setup authentication with a Flint URL, Create order payments through the payment intents 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.

  • API
  • Payments
  • Customers

Choose a default payment method on the customer#

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 change
  • API
  • Risk

Payment reviews use explicit names and typed actors#

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.

  • Breaking change
  • API
  • Promotions

Promotion stacking and rule shapes#

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.

  • Breaking change
  • API
  • Refunds
  • Gift-cards

Refunds can issue store credit on new gift cards#

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 change
  • API
  • Reports
  • Balances
  • Payouts

Report CSVs use API money signs, names, and relationships#

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.
  • Breaking change
  • API
  • Developers

Read request logs across callers#

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

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.

  • Breaking change
  • API
  • Risk
  • Gift-cards

Fraud warnings and purchase refund allocations have distinct ID prefixes#

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 change
  • API
  • Returns

Return receipts and inspections have their own versions#

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).

  • API
  • Returns
  • Webhooks

Read Return reasons and activity history#

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 change
  • API
  • Subscriptions

Subscription resumes, scheduled starts, and cancellation timing are explicit#

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.

  • Breaking change
  • API
  • Subscriptions
  • Promotions

Change subscription plans and preview the next charge#

Use POST /v1/subscriptions/{subscription_id}/change-plan with an Idempotency-Key, a subscription_plan_id, and an explicit billing_starts choice:

  • next_renewal changes the plan without charging now. The next unpaid period uses the new terms.
  • now charges a new period today and credits the unused part of the current paid period's items. If the credit exceeds the new items after promotions, use next_renewal. A declined payment leaves the subscription unchanged.

Older payments with no known paid service period receive 0 unused-time credit in previews and charges; you can still issue a manual credit.

Changing a plan replaces the subscription's lines with the plan's current lines and prices. The same plan can be selected to refresh its prices. Contract terms and attached promotions carry over.

Use POST /v1/subscription-previews in plan_change mode to estimate a change, or in next_renewal mode to estimate the next charge. Buyers can use next_renewal on POST /v1/me/subscription-previews. Estimates include discounts, shipping, and available tax calculations. They do not check stock.

Subscriptions include promotions, with the frozen name, recurrence, and remaining charged cycles for each recurring promotion that still applies. Orders identify unused-time credits with discount source plan_change_credit.

Subscribe to subscription.plan_changed for committed plan changes. A change that bills immediately also sends subscription.payment_succeeded.

Breaking change: Subscription.recurring_subtotal_money replaces recurring_amount_money in merchant and buyer responses and subscription webhook payloads. It is the items subtotal before discounts, shipping, and tax. SubscribedLine.recurring_amount_money on order lines is unchanged. These changes apply immediately to every supported API version.

The plan-change result uses order_payment_attempt, renamed from payment_attempt before production release to match other order payment results.

  • API
  • Subscriptions
  • Payments

Subscription plan resets and checkout payment risk#

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 change
  • API
  • Subscriptions
  • Errors

Subscription state refusals use ACTION_NOT_ALLOWED#

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.

  • Breaking change
  • API
  • Orders

Order tickets move to ticketed_event#

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 change
  • API
  • Webhooks

Webhook deliveries are listed at /v1/webhook-deliveries#

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.

  • API

Resource version rollout preparation#

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 change
  • API
  • Errors

State refusals include required reasons, and live-mode refusals return FORBIDDEN#

Superseded by Shared merchant profile writes require live credentials.

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_email, 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.

  • API
  • Payments

Buyer payment responses omit risk#

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.

  • API
  • Customers

Customer sessions return a resource and support sign-out#

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.

  • Breaking change
  • API
  • Customers
  • Webhooks

Customers have a status, deleted customers leave the list, and deletion requests use one path#

Breaking: customers have a status. Customer, and the customer summary that expand=customer returns on orders, invoices, payments, and subscriptions, now include a required, read-only status:

ValueMeaning
activeThe customer can be changed and used for new purchases.
deletion_processingYou approved a deletion request and it is in progress. The customer can't be changed, charged, or signed in to.
deletedThe customer's personal data was erased. Only its ID, created_at, and the records that reference it remain. It can't be changed or restored.

A customer whose deletion request is pending_review or rejected is still active. Writes to a deletion_processing or deleted customer return 409 CUSTOMER_DELETION_PROCESSING; the error now covers both.

Breaking: the list omits deleted customers. GET /v1/customers returns active and deletion_processing customers. A new status filter takes one or more values, repeated or comma-separated, and status=deleted lists the customers whose data was erased. A page token is bound to the status filter it came from. A deleted customer is still readable by ID, and still appears when you expand customer on an order, invoice, payment, or subscription, as the same record: status: "deleted", the name "Deleted customer", and its personal fields empty. If you build a customer list from GET /v1/customers, a deleted customer now disappears from it, so purge your copy when you receive customer.deleted.

Breaking: deletion requests have one path shape.

BeforeNow
POST /v1/customers/{customer_id}/deletion-requestsPOST /v1/customer-deletion-requests with {"customer_id": "cus_..."}
GET /v1/customers/{customer_id}/deletion-requests/{customer_deletion_request_id}GET /v1/customer-deletion-requests/{customer_deletion_request_id}

The old paths are removed. Operation IDs are unchanged, so SDK method names stay the same, but the create method now takes customer_id in its request body. The new GET needs customers.read and also accepts a dashboard session that can manage customers. GET /v1/customer-deletion-requests and the resolve route are unchanged, and /v1/me/deletion-requests keeps its paths.

Breaking: creating a request returns 201 or 200, not 202. A new request returns 201 Created. When the customer already has an open request (pending_review, processing, or failed), Flint returns it unchanged with 200 OK. Both apply to POST /v1/customer-deletion-requests and POST /v1/me/deletion-requests. Nothing is deleted until a request is approved, so there is no work in progress to accept. A retry with the same Idempotency-Key replays the original status. The key now covers the body, so the same key with another customer_id returns 409 IDEMPOTENCY_KEY_REUSED. Check for 2xx rather than 202.

Breaking: retention_policy is an enum. CustomerDeletionRequest.retention_policy is published as an enum whose only value today is retain_required_commerce_records. The enum is extensible, so handle values you don't recognize.

Breaking: not-found errors. Creating, reading, and resolving a deletion request return 404 RESOURCE_NOT_FOUND instead of CUSTOMER_ACCOUNT_RESOURCE_NOT_FOUND. param is customer_id when you create a request and customer_deletion_request_id when you read or resolve one.

Customer events follow the lifecycle.

  • customer.updated is sent when you approve a request, with status: "deletion_processing" and a higher version. Approving a failed request again doesn't send it.
  • customer.deleted is new. It is sent when deletion completes, alongside customer_deletion_request.completed, and data.object is the deleted customer, the same record GET /v1/customers/{customer_id} returns afterward. It needs customers.read for partner apps, like the other customer events.
  • Flint erases external_reference_id, so correlate deleted customers by customer_id, or read the mapping when customer_deletion_request.created or the approval's customer.updated arrives.

Regenerate SDKs and validators that read the OpenAPI schema. See Customer deletion requests and Customers.

Deleting a customer revokes its invoice links, removes its email from invoice delivery attempts, and keeps the issued identity on issued invoices; InvoiceDeliveryAttempt.to_email can be null.

Contact copies created while customer deletion is finishing are erased within minutes, including stored email and webhook payloads awaiting delivery. Flint checks again about 24 hours later. Issued invoice identity and merchant PDFs stay unchanged; revoked buyer links remain rejected.

  • Breaking change
  • API
  • Disputes
  • Webhooks

Embed dispute responses and use Flint dispute statuses#

Superseded by Payout success status and dispute actions.

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:

Previous valueNew value
warning_needs_responseinquiry_needs_response
warning_under_reviewinquiry_under_review
warning_closedinquiry_closed

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.

  • Breaking change
  • API
  • Errors
  • Checkout
  • Refunds

Throttles and duplicate error codes use shared names#

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 change
  • API
  • Gift-cards
  • Orders
  • Customer-accounts

Gift card command results and consistent field names#

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

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.

OldNew
POST /v1/gift-cards/{gift_card_id}/adjustments, createGiftCardAdjustmentPOST /v1/gift-cards/{gift_card_id}/adjust-balance, adjustGiftCardBalance
POST /v1/gift-cards/{gift_card_id}/cash-outs, createGiftCardCashOutPOST /v1/gift-cards/{gift_card_id}/cash-out, cashOutGiftCard
CreateGiftCardAdjustmentRequestAdjustGiftCardBalanceRequest
CreateGiftCardCashOutRequestCashOutGiftCardRequest
GiftCardWithCodeCreateGiftCardResult or RotateGiftCardCodeResult
GiftCardWithTransactionsAdjustGiftCardBalanceResult or CashOutGiftCardResult
GiftCardLoadWithCardCreateGiftCardLoadResult
GiftCardRedemptionWithCardGiftCardRedemptionResult
gift_card_transaction_idsgift_card_transactions, with full transaction objects
secret_recovery_expires_atcode_recovery_expires_at
payout_reference on cash-out requests, transactions, and the transaction filtercash_out_reference
Funding source.buyer_id, including refund provenancesource.customer_id
last_characters on gift cards, buyer gift cards, order selections and settlements, payment attempt redemptions, and purchased gift cardslast4
Notification delivery.provider_outcomes[].kinddelivery.events[].type
Notification delivery.has_more_provider_outcomesdelivery.has_more_events
GiftCardNotificationProviderOutcomeGiftCardNotificationDeliveryEvent

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.

  • API
  • Invoices
  • Credit-notes

Inclusive invoice line totals#

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.

  • Breaking change
  • API
  • Errors

Request validation uses INVALID_REQUEST#

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 change
  • API
  • Errors

Inventory counts recover from stock that moves#

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.

  • Breaking change
  • API
  • Inventory
  • Errors

Inventory provenance accepts opaque identifiers and publishes validation rules#

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 change
  • API
  • Invoices

Invoice delivery attempts return failure and suppression reasons#

Superseded by Sandbox buyer emails report the daily limit.

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.

  • Breaking change
  • API
  • Onboarding

Merchant requirement codes and account session targeting#

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.

  • API
  • Orders
  • Fulfillment

Order line items report fulfillment quantities#

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.

  • API
  • Partners

Preparation for partner app updates#

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.

  • Breaking change
  • API
  • Security
  • Webhooks
  • Partners

Webhook mutations require merchant credentials#

Superseded by Partner-source webhooks require live configuration access.

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 change
  • API
  • Refunds

Refund create names its type, a recorded refund is always 201, and refund statuses split in two#

Superseded by Credit-note refunds move to the refunds API.

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.

refund_typeRefundsRequiresNot accepted
fullEverything still refundable on the targetorder_id, payment_intent_id, or gift_card_load_idamount_money, line_items, charges, tax_breakdown_refunds, tender_allocations
amountThe amount_money you sendamount_money, plus order_id, payment_intent_id, gift_card_load_id, or tender_allocationsNothing beyond the per-target rules
targetsThe named line_items, charges, and tax_breakdown_refundsAt least one of those, and an order through order_id or a payment_intent_id on an orderamount_money, tender_allocations, gift_card_load_id

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.

  • Breaking change
  • API
  • Returns

Exchanges and replacements are fulfilled when their Order is#

Breaking: an exchange or replacement is fulfilled when its replacement Order is. Before, the resolution became fulfilled as soon as Flint created the replacement Order. Now it stays pending with the fulfillment_pending execution blocker until the Order's fulfillment_status is fulfilled or not_applicable. The blocker's linked_resource names the Order. Until then the Return stays open with a resolution_pending completion blocker, so ReturnResolution.status: fulfilled, Return.resolution_status: fulfilled, and return.completed all arrive later than they did.

Every unit's fulfillment must be completed. For a shipment with packages that is delivery, and for pickup it is the handover. Report delivery with package actions, or send complete on the fulfillment. An Order with nothing to fulfill counts at once.

Fulfillment needs a paid Order. If the buyer owes a balance, the resolution holds buyer_payment_pending and fulfillment_pending together, and keeps only fulfillment_pending once the payment succeeds. A replacement fully covered by return credit becomes paid on its own. A zero-total replacement needs POST /v1/orders/{order_id}/pay with no payment_source before you can fulfill it.

Breaking: a canceled fulfillment fails the resolution. When the replacement Order's fulfillment_status becomes canceled, or closed because some units were canceled and the rest completed, the resolution becomes failed with failure_code: replacement_fulfillment_canceled and no blockers, and the Return shows resolution_failed. retry and cancel are not offered for it yet. To send the goods another way, fail the fulfillment with release_quantity: true and create a new one instead of canceling it.

Breaking: checkout_session is offered only while a balance is owed. A paid exchange waiting on fulfillment no longer lists checkout_session in supported_actions, and the checkout route refuses it.

Breaking: credit_effect_pending is removed. It was never returned. The ReturnResolutionExecutionBlocker.code enum no longer lists it, so regenerate SDKs and validators that read the enum.

return_resolution.updated and return.updated fire when the replacement Order is created, when the balance is paid, and again when the resolution becomes fulfilled or failed. Returns that already completed stay completed.

  • Breaking change
  • API
  • Returns

Returns use release timing and stable adjustment IDs#

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.

  • Breaking change
  • API
  • Risk
  • Webhooks

A failed decline refund reopens the review, and expiry shows as resolving#

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.

  • API
  • Payments
  • Risk

Risk list checks no longer fail on accepted email addresses#

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.

  • API
  • Sandboxes

Sandbox resets link archived and replacement sandboxes#

Superseded by Resetting a sandbox keeps its ID, keys, and webhook endpoints.

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.

  • API
  • Invoices
  • Credit-notes
  • Returns

Shared invoice credit limits for Returns and credit notes#

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.

  • API

Enforce published text limits before normalization#

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.

  • Breaking change
  • API
  • Subscriptions

Create and import subscriptions from offers#

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:

JSON
{
  "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 change
  • API
  • Subscriptions
  • Webhooks

Subscription events cover every change, activation follows the first paid period, and billing-schedule initiated_by is removed#

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.

  • Breaking change
  • API
  • Errors

Response warnings use typed fields#

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:

Previous codeCurrent code
MERCHANT_ONBOARDING_PAST_DUE_WARNINGmerchant_onboarding_past_due
MERCHANT_ONBOARDING_DEADLINE_WARNINGmerchant_onboarding_deadline
MERCHANT_CAPABILITY_PENDING_WARNINGmerchant_capability_pending
MERCHANT_CAPABILITY_INACTIVE_WARNINGmerchant_capability_inactive
PAYOUT_SETTINGS_RECONCILINGpayout_settings_reconciling
RULE_EVALUATION_STAGE_CHANGEDrule_evaluation_stage_changed
BOOTSTRAP_SCOPES_REDUCEDapi_key_scopes_reduced

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 change
  • API
  • Errors

Stale versions on catalog, subscription, plan, and risk writes return VERSION_CONFLICT#

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:

ConditionResponse
A stale expected_version on a risk rule409 VERSION_CONFLICT with resource_type risk_rule and current_version
Changing an archived rule, or adding items to or deleting items from an archived list409 ACTION_NOT_ALLOWED with current_status archived and resource_type risk_rule or risk_list
A risk control write that loses a race409 CONCURRENT_MODIFICATION

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.

  • Breaking change
  • API
  • Errors

Stale versions on customer, settings, invoice, and other writes return VERSION_CONFLICT with the current value#

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

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.

  • Breaking change
  • API
  • Webhooks

Resend pending webhook deliveries and create missing ones#

Superseded by Webhook refusals name the recovery action.

Breaking: resend works while Flint is still retrying. POST /v1/webhook-deliveries/{webhook_delivery_id}/resend on a pending delivery returned 409 WEBHOOK_DELIVERY_IN_FLIGHT. It now sends the event to the endpoint immediately and returns that attempt, like a resend of a failed or delivered delivery.

  • If your endpoint answers 2xx, the delivery becomes delivered and its remaining retries are canceled.
  • If the attempt fails, the delivery stays pending with the same next_retry_at. Only last_response_code and last_error change.
  • A resend never counts toward automatic_attempt_count or max_attempts. Attempt numbers count every attempt, so a resend between two retries takes the next number.

WEBHOOK_DELIVERY_IN_FLIGHT now means only that another attempt for the same delivery is running right now. It is returned before anything is sent, carries Retry-After: 10, and has remediation.retry of same_request: wait, then send the same request with the same Idempotency-Key.

Create a delivery for an event an endpoint never received. POST /v1/webhook-deliveries takes webhook_event_id, webhook_endpoint_id, and an optional reason_message. It creates the delivery, attempts it before responding, and returns 201 with the webhook delivery. Use it for events published while an endpoint was disabled, or to backfill a new endpoint from retained events.

  • The event's payload must still be retained (14 days), the endpoint must be enabled, and the endpoint must subscribe to the event type now. Otherwise the request returns 409 WEBHOOK_EVENT_PAYLOAD_EXPIRED, 409 WEBHOOK_ENDPOINT_NOT_ACTIVE, or the new 409 WEBHOOK_ENDPOINT_NOT_SUBSCRIBED.
  • Each event and endpoint pair has one delivery. A second create returns 409 ALREADY_EXISTS with the existing delivery in current_resource.
  • The first attempt has the new delivery_trigger value manual_delivery. If it fails, the delivery follows the normal automatic schedule, with its first retry after about 30 seconds.
  • Like the other webhook write routes, it requires an API key or Dashboard session with webhooks.write, not a partner install token.

Higher limits for recovery. Resend and create now use the write rate class (20 per second and 600 per minute per key) instead of external_provider_action (2 per second for resend), so recovering thousands of events takes minutes.

Disabling an endpoint suppresses its pending deliveries immediately, in the same update, not at their next attempt. Re-enabling it doesn't restart them. The webhooks guide walks through resending suppressed deliveries and creating the missing ones.

  • Breaking change
  • API
  • Webhooks

Webhook endpoint status and secret rotation#

Webhook endpoint changes apply immediately to every supported API version:

  • Send status: active or status: inactive instead of enabled on create and update. Responses return status. Inactive endpoints receive no new events and their pending deliveries are suppressed.
  • Create requires a non-empty enabled_events. Updates reject an empty list. Send ["*"] for every event type the endpoint's sources deliver, including future types. * must be the only entry and cannot be used with installed_merchants.
  • DELETE returns the endpoint with status: deleted. Its endpoint record is removed, pending deliveries are suppressed, and subsequent retrieval returns 404.
  • Secret rotation returns the endpoint, including the new secret, which is shown once. The replaced secret keeps signing for 24 hours by default. previous_secret_expires_at is present while it still signs.
  • To stop a leaked secret immediately, rotate with expire_previous_secret_at set to the current RFC 3339 time or a past time. Deploy the new secret to your receiver; verification fails until it uses that secret. You can choose a future expiry up to 7 days away. Rotating again during an overlap ends the older previous secret immediately, so deliveries carry at most two signatures. Rotation no longer returns WEBHOOK_SECRET_ROTATION_OVERLAP_ACTIVE.
  • api_version_rollback_expires_at accompanies api_version_previous while a supported previous version is available for rollback.
  • Breaking change
  • API
  • Invoices

Build invoice pages with the buyer invoice document#

GET /v1/me/invoices/{invoice_id} and the invoice in POST /v1/me/invoices/{invoice_id}/checkout-session now include the hosted invoice document. Both customer sessions and invoice access tokens receive ordered issue and balance rows, available payment options, collection mode, and merchant branding and support details. Active payment attempts and payment-option cost comparisons appear when available. Invoice lists omit these fields.

Closing total and amount-due rows are informational and state the sum of the contributing rows. Payment options are empty when the buyer cannot pay the invoice online now. A new checkout's cost comparison uses its collection amount, including a selected installment, before any payment attempt exists.

GET /v1/me/invoices/{invoice_id} with an invoice token now stamps viewed_at once. Token checkout stamps it after checkout is created or reused. Customer-session reads leave it unchanged.

Checkout creation with an invoice token is now bound to that token. If the merchant regenerates the link during creation, the request returns 409 INVOICE_LINK_UNAVAILABLE without param. The buyer must use the current invoice link.

  • API
  • Customers
  • Orders
  • Fulfillment

Buyer responses omit merchant inventory, tax configuration, and courier operations#

Buyer responses immediately omit these merchant fields on every supported API version:

  • Order.inventory_routing_source
  • Order.inventory_exception_status
  • Order.inventory_exception_reason
  • Order.tax.location.location_id
  • Order.tax.location.device_id
  • Customer.tax_exempt
  • Fulfillment.outcome.notes
  • Fulfillment.local_delivery_details.service_area_id
  • Fulfillment.local_delivery_details.external_delivery_id

This applies to customer profile reads and updates, order and fulfillment reads under /v1/me, checkout order reads, and order results nested in subscription renewal, delivery selection, and payment actions. Retrying a completed request with the same idempotency key also omits these fields immediately.

Buyers retain the applied transaction exemption at Order.tax.exemption.tax_exempt, pickup destination choices, delivery instructions, normalized outcome reasons, tracking, public courier support details, and client payment setup and action payloads. Merchant API credentials, Dashboard, and merchant webhooks retain their merchant fields.

  • Breaking change
  • API
  • Webhooks
  • Catalog
  • Promotions

Catalog changes send webhook events, and deleted promotion codes read archived#

Superseded by Promotion codes, gift card loads, and buyer transactions use top-level routes, Catalog changes reach every resource they change, Catalog parents send their own event when a child changes them.

Catalog resources now send webhook events, so a point-of-sale system, ERP, or search index can stay current without polling. Each event carries the resource as its GET returns it in data.object.

  • product.created, product.updated, and product.archived
  • product_variant.created, product_variant.updated, and product_variant.archived
  • bundle.created, bundle.updated, and bundle.archived
  • category.created, category.updated, and category.deleted
  • modifier_group.created, modifier_group.updated, and modifier_group.archived
  • modifier_set.created, modifier_set.updated, and modifier_set.archived
  • promotion.created, promotion.updated, and promotion.archived
  • promotion_code.created, promotion_code.updated, and promotion_code.archived

created follows a POST, archived and deleted follow a DELETE, and updated follows every other committed change, including a status change between active and inactive. Variants and promotion codes have their own write routes, so they send their own events:

  • POST /v1/products sends product.created and one product_variant.created for each variant it creates. A request with two variants sends three events, and the default variant is one of the two.
  • POST /v1/promotions sends promotion.created and one promotion_code.created for each code.
  • A variant or code write sends only its own event, even though it also advances the parent's version and updated_at and changes its rollups.
  • Archiving a product archives its variants, and archiving a promotion archives its codes. Only product.archived or promotion.archived is sent.
  • Options, bundle components, modifiers, and the groups in a modifier set have no routes of their own and no events. The parent's updated event covers them.

A field that one resource shows and another owns changes without an event for the resource that shows it. A product's price_range and variant_count change when a variant does, and categories[].name changes when a category is renamed. Redemptions and schedule boundaries send no events either. Join these fields by ID when you mirror.

Flint reads the resource when it prepares the event, so data.object can include a change made after the event's own. category.deleted carries the category as DELETE returned it, because a deleted category can no longer be read. Partner apps receive these events for an install that holds the matching read scope: commerce.products.read, commerce.bundles.read, commerce.catalog.read, or commerce.promotions.read.

Breaking: DELETE /v1/promotions/{promotion_id}/codes/{promotion_code_id} now returns the code with status: "archived". Before, it returned inactive, and the code then returned 404.

Breaking: a promotion code has a new status value, archived, with unavailable_reason: "archived". An archived code, including every code of an archived promotion, is returned by GET /v1/promotions/{promotion_id}/codes/{promotion_code_id} instead of 404. GET /v1/promotion-codes leaves archived codes out unless you pass status=archived, and its status filter now accepts active, inactive, and archived. The code filter finds an archived code only together with status=archived. Handle archived wherever you switch on a code's status.

Breaking: PATCH on an archived promotion code returns 409 ACTION_NOT_ALLOWED with current_status: archived in details[0]. Before, a deleted code returned 404.

GET /v1/modifier-groups/{modifier_group_id} and GET /v1/modifier-sets/{modifier_set_id} return an archived group or set with status: "archived" instead of 404, so a delayed event can render it. PATCH and DELETE on one still return 404.

updated_at on products, variants, bundles, modifier groups, modifier sets, promotions, and promotion codes no longer moves backward. Before, a variant write, an archive, or a promotion or code DELETE could set it earlier than a recent PATCH had, so a poll on updated_at could miss the change.

Catalog events lists what each event means, and Keep another system in sync covers mirroring and backfill.

  • API
  • Checkout
  • Orders

Read checkout branding, subscription choices, and order tax price mode#

GET /v1/checkout-sessions/{checkout_session_id} returns merchant_name, show_flint_mark, and, when set, merchant_logo, merchant_icon, and payment_link_image. These read-only fields are available with either an API key or the session's checkout credential. Create and launch results, lists, and webhooks omit them. If Flint can't load the merchant, the GET returns 500 INTERNAL_ERROR rather than incomplete branding.

Session theme and the public payment link read's checkout_theme use the read-only CheckoutTheme shape. Alongside title, primary_color, and accent_color, it includes branding settings' background_color, text_color, font_family, and corner_radius. Request theme objects and the link's own theme keep ThemeConfig, with only the title and two color overrides.

Session responses and webhooks also return tax when the session has tax settings: enabled as set at creation, and read-only location_fixed_by_merchant when the order already held a tax location. This adds session tax settings back to responses; the order's tax remains the source for its current calculation and amounts.

GET /v1/payment-links/{payment_link_id}/public adds show_flint_mark and, for subscription signup links, subscription_preview.billing_interval_options and subscription_preview.quantity_options. A successful response includes the link's Flint-Mode and Flint-Merchant-Id headers, plus Flint-Sandbox-Id for a sandbox link. Errors omit those headers. The endpoint still requires no credential.

Orders Flint renders after 2026-10-20 include read-only tax.price_mode, either additive or inclusive, with additive when no tax configuration is set. A response replayed for an idempotent retry of an earlier request omits it, so the response field is optional. Line items and charges keep their own tax.calculation.price_mode. Replacement orders created by a return also include read-only return_resolution_id; other orders omit it.

  • Breaking change
  • API
  • Credit-notes

Credit note tax and remaining value#

Credit notes now calculate from each frozen invoice line's remaining billed value, discount, and tax. Crediting one of two inclusive units with total 1200 and tax 200 returns total 600, including tax 100. A full credit returns total 1200 and tax 200. Tax is neither added twice nor changed to force an amount correction's total.

Breaking: remaining-pool rounding replaces the previous tax-first residual policy for all callers. Amount corrections reduce the remaining units' value without consuming quantity. Later quantity corrections use that reduced value, and exhausting a line consumes its original components exactly across issued, non-void notes. Public field names are unchanged. Tax-exclusive consideration remains total_money - tax_money.

Issue preserves previewed amounts. If another issued or voided note changes a fitting draft's allocation, issue returns 409 CONCURRENT_MODIFICATION with reason credit_note_creditable_value_changed and retry after_refresh. Retrieve the draft, replace its existing line_items corrections using its current expected_version, review the recalculated amounts, and issue with a new key.

New corrections, allocations, and linked refunds that would spend affected historical credit return 409 ACTION_NOT_ALLOWED with reason credit_note_tax_reconciliation_required and blocking credit-note references. Reads, issued amounts, and committed command retries preserve their stored results. Allocation reversal and eligible voids remain available for recovery; already-refunded money requires accounting reconciliation.

PDFs distinguish added Tax from informational Includes tax. Credit-note issue does not submit a Quaderno credit document or automatically reverse tax in Flint's built-in tax reports.

See Credit notes for rounding examples and recovery steps.

  • API
  • Fulfillment
  • Checkout

Fulfillment event types are complete, and checkout surfaces stay consistent#

Superseded by The checkout session surface embedded is now headless.

The event_type vocabulary on fulfillment event responses now documents all 21 values. The newly documented values are accepted, preparing, picked, packed, ready, dispatched, completed, canceled, failed, and no_show. This vocabulary is extensible, so clients must accept values they do not recognize. Creating an event still accepts only carrier_scan and custom. The list filter keeps its existing values.

Checkout session lists and close or expire responses now preserve surface: "embedded" for embedded sessions and surface: "hosted" for hosted sessions. Older sessions created before surfaces were introduced report hosted, consistently with retrieving the same session. Responses no longer return surface: "unspecified"; the published values remain hosted and embedded.

  • Breaking change
  • API
  • Webhooks
  • Invoices

Invoice webhooks cover every status change, and paid invoices can reopen#

Superseded by Record late payments after an invoice write-off.

paid and credited close an invoice's balance but are not final. Reversing a manual payment, losing a dispute, or reversing a credit note allocation can return the invoice to open or partially_paid. void and uncollectible remain final, and refunds still change only refund_status. paid_at clears when an invoice leaves paid, and closed_at clears when it returns to open or partially_paid.

Two webhook events are new. Both need commerce.invoices.read:

  • invoice.reopened fires when a reversal returns a paid or credited invoice to open or partially_paid, or returns a partially_paid invoice to open. data.object is the invoice.
  • invoice_payment_attempt.succeeded fires once when an invoice payment attempt succeeds, including an attempt that pays only part of the balance and an ACH debit that leaves processing. data.object is the payment attempt with status: "succeeded" and settled_at. Manual payments do not create payment attempts and do not send it.

invoice.paid now fires whenever the balance reaches zero with collected payments applied, including when a credit note allocation or a late fee waiver clears the rest, and when a reversed payment is recovered. invoice.credited fires whenever credit clears the balance with no collected payments remaining. Each payment that leaves a balance still sends invoice.partially_paid. Manual payment reversals and lost disputes that reopen the balance now send invoice.reopened as well as their existing events.

Breaking: reversing a credit note allocation that reopens an invoice sends invoice.reopened instead of invoice.updated. Subscribe to invoice.reopened if your system treats paid or credited as final. Flint does not resend earlier events.

One change can send several events, such as invoice.manual_payment_reversed and invoice.reopened, and Flint does not guarantee the order they arrive in. See Invoicing.

  • API
  • Orders
  • Invoices

Order sort errors and tax and invoice values match responses#

The error for an empty sort_by on GET /v1/orders now lists created_at, updated_at, outstanding_money, and total_money. It no longer lists order_number. The error code remains INVALID_REQUEST.

TaxBreakdown.taxability_reason now documents all six values already returned by the API: standard_rated, not_taxable, customer_exempt, tax_disabled, location_required, and calculation_incomplete. The vocabulary remains extensible, so handle unrecognized values.

InvoiceDiscount.discount_class now documents only order and line_item, matching invoice responses. AppliedDiscount.discount_class continues to include service_charge.

  • Breaking change
  • API
  • Organizations

Organization membership changes require existing access#

Superseded: The public organizations API was removed on November 5, 2026. The organization routes, merchant organization field and expansion, and organization scopes described here are no longer available.

POST /v1/organizations/{organization_id}/memberships sets roles only for users who already have an active membership in that organization or a parent organization. It returns 201 when it adds a direct membership and 200 when it changes one. Other user_id values return 404 RESOURCE_NOT_FOUND with param: "user_id", whether the account exists or not. The API cannot invite new people.

The grant request accepts admin, operator, and viewer. Sending owner returns 400 INVALID_REQUEST with detail code INVALID_VALUE and param: "role". Membership responses still include the owner role. Removing a direct membership returns status: "removed" instead of "revoked".

POST /v1/organizations/{organization_id}/transfer-ownership has been removed. Account ownership changes are reserved for Flint.

Organization writes return 403 FORBIDDEN with details[0].reason: "organization_role_insufficient" when the acting user's organization role doesn't allow the change, or "organization_live_mode_required" when the request uses test mode. These replace the generic not_permitted reason. Organizations outside the credential's access still return 404.

  • API
  • Payments

Filter payments that need action and send standalone receipts#

GET /v1/payment-intents accepts the optional action_required boolean filter. true returns payments that require capture or have a dispute that needs a merchant response. The dispute must have status needs_response or warning_needs_response, allow evidence responses, and have no deadline or a deadline that has not passed. false returns the remaining payments. Omit the filter to include both groups.

POST /v1/payment-intents/{payment_intent_id}/receipts queues a receipt for a succeeded payment with no order. Send email to choose a recipient, or omit it to use the payment's receipt_email, then the customer's email. The saved receipt email stays unchanged. Payments linked to an order continue to use POST /v1/orders/{order_id}/send-receipt.

The receipt action requires payments.payment_intents.write for API keys and partner tokens. Dashboard owners, admins, and operators can also send receipts. It returns the same action response as order receipt sends: data.success is true after the receipt is queued. Sending requires Flint-managed receipt delivery and is limited to once every five minutes per payment. Send an Idempotency-Key and reuse it when retrying the same send.

  • API

Required response fields include nullable values#

OpenAPI now marks a response field as required when Flint always includes its key. A required field can still be nullable: for example, a Customer response includes "tax_identity": null when no tax identity is set. Check the field's nullable schema separately from whether its key is required.

Response JSON is unchanged. Optional fields can still be omitted, and buyer response schemas continue to describe the fields available to buyers. Regenerate clients from the updated OpenAPI document to use the corrected required fields.

  • API
  • Disputes

Filter disputes that need a response and choose their order#

GET /v1/disputes accepts three new optional query parameters:

  • action_required=true returns disputes that need a merchant response now: their status is needs_response or warning_needs_response, evidence responses are allowed, and the evidence deadline has not passed. A dispute with no deadline can still need a response. false returns the remaining disputes; omitting the parameter applies no action filter.
  • sort_by accepts created_at, evidence_due_at, or amount. amount compares amount_money.amount in minor units. Disputes without an evidence deadline sort after dated disputes in either direction.
  • sort_direction accepts asc or desc. The default remains created_at descending, with ties broken by dispute_id in the same direction.

For example, GET /v1/disputes?action_required=true&sort_by=evidence_due_at&sort_direction=asc lists disputes that need a response by their evidence deadline.

GET /v1/disputes and GET /v1/disputes/{dispute_id} also accept dashboard sessions for merchant owners, admins, operators, and viewers. Dashboard requests use the selected live or sandbox environment.

  • Breaking change
  • API
  • Gift-cards

Gift card restrictions, a default funding disposition, and a customer filter#

Superseded by Gift card lifecycle verbs and shared status words.

Why a card is frozen. Every gift card now has restrictions, which is [] when nothing keeps it frozen. A merchant_freeze restriction comes from a freeze transition and carries its reason. A funding_dispute restriction names the dispute_id on a payment that funded the card, with dispute_status open or lost. unfreeze is supported only when every restriction is a merchant_freeze, and a lost dispute needs a funding disposition. You no longer need to scan the card's loads to find out. The field also appears on gift_card.* webhooks and on the card returned with loads and redemptions. Buyer reads under /v1/me/gift-cards don't include it. See Gift cards.

disposition is optional. POST /v1/gift-card-funding-dispositions defaults disposition to honor_value, its only value. Send dispute_id and reason_message. A request that sends honor_value and one that omits it are the same request, so either replays under the same Idempotency-Key.

Find a customer's cards. GET /v1/gift-cards?customer_id=cus_... returns the cards associated with that customer.

Breaking: no gift_card_id filter on the card list. GET /v1/gift-cards?gift_card_id= now returns 400 UNSUPPORTED_QUERY_PARAM. Retrieve one card with GET /v1/gift-cards/{gift_card_id}. Loads, redemptions, notifications, and transactions still filter by gift_card_id.

  • Breaking change
  • API
  • Errors

One code for records in the way and one for a taken key#

Breaking: RESOURCE_IN_USE. When other records stop a change, Flint returns 409 RESOURCE_IN_USE. details[0].blocking_resources lists up to 25 of them as resource_type and resource_id references, and details[0].blocking_resource_count gives the total. details[0].resource_type and resource_id name the record you tried to change. One response lists every kind of blocker the change checks, so resolve them all before you retry. Blockers appear only for resource types your credential can read, and the count covers only those: a key with only commerce.products.write gets the refusal and the product, but no order IDs. Grant the read scope for a blocker's type to see it. These codes are replaced:

Old codeBlockers listed
PRODUCT_IN_USE, PRODUCT_IN_OPEN_ORDER, VARIANT_IN_OPEN_ORDER, BUNDLE_IN_OPEN_ORDERorder
PRODUCT_IN_OPEN_CHECKOUT_SESSION, VARIANT_IN_OPEN_CHECKOUT_SESSION, BUNDLE_IN_OPEN_CHECKOUT_SESSIONcheckout_session
PRODUCT_IN_OPEN_INVOICE_PAYMENT_ATTEMPT, VARIANT_IN_OPEN_INVOICE_PAYMENT_ATTEMPT, BUNDLE_IN_OPEN_INVOICE_PAYMENT_ATTEMPTinvoice_payment_attempt
PRODUCT_IN_ACTIVE_PLAN, VARIANT_IN_ACTIVE_SUBSCRIPTION_PLAN, BUNDLE_IN_ACTIVE_SUBSCRIPTION_PLANsubscription_plan
PRODUCT_IN_ACTIVE_SUBSCRIPTION, VARIANT_IN_ACTIVE_SUBSCRIPTION, BUNDLE_IN_ACTIVE_SUBSCRIPTIONsubscription
VARIANT_IN_ACTIVE_PAYMENT_LINK, BUNDLE_IN_ACTIVE_PAYMENT_LINKpayment_link
VARIANT_IN_ACTIVE_BUNDLEbundle
INVENTORY_ITEM_IN_USEproduct_variant, inventory_level, inventory_reservation, inventory_transfer
INVENTORY_ALLOCATION_POLICY_IN_USEinventory_reservation
LOCATION_IN_USEinventory_allocation_policy, device, fulfillment, inventory_level, inventory_reservation, inventory_transfer, inventory_count, merchant
MODIFIER_SET_IN_USEproduct, product_variant, bundle
MODIFIER_GROUP_IN_USE, MODIFIER_IN_USEmodifier_set
CATEGORY_REFERENCEDproduct, bundle, promotion, return_policy, return_reason
LIST_IN_USErisk_rule (risk_rule_ids stays, with the same read filter)
DELIVERY_RESOURCE_HAS_DEPENDENCIESunchanged
INVOICE_PAYMENT_TERM_IN_USE, INVOICE_HAS_ISSUED_CREDIT_NOTE, CREDIT_NOTE_HAS_ALLOCATIONSunchanged
ORGANIZATION_HAS_ACTIVE_DESCENDANTS, ORGANIZATION_LINKED_TO_MERCHANTunchanged, up to 10

Changing tracked inventory on an order line while an active inventory reservation holds it also returns RESOURCE_IN_USE, listing the inventory_reservation, instead of INVENTORY_RESERVATION_EXISTS.

Breaking: ALREADY_EXISTS. When a unique key or exclusive slot is taken, Flint returns 409 ALREADY_EXISTS. param names the field, and with merchant credentials details[0].current_resource names the record that has it, as {"resource_type": "product_variant", "resource_id": "var_..."}, when your credential can read that record's type. These codes are replaced:

Old codecurrent_resource
SKU_ALREADY_EXISTS, BARCODE_ALREADY_EXISTSthe product, product_variant, or bundle with that SKU or barcode
PRODUCT_OPTION_ALREADY_EXISTS, PRODUCT_OPTION_VALUE_ALREADY_EXISTSthe product_option or product_option_value
VARIANT_OPTION_COMBINATION_ALREADY_EXISTSthe product_variant that selects the combination
CATEGORY_HANDLE_EXISTSthe category
PAYMENT_METHOD_DOMAIN_ALREADY_EXISTSthe payment_method_domain, replacing payment_method_domain_id
RISK_LIST_ALIAS_ALREADY_EXISTSthe risk_list
SANDBOX_ALREADY_EXISTSthe sandbox
INVENTORY_RESERVATION_EXISTS (the owner key already holds a reservation)the inventory_reservation

Breaking: duplicates within one request are 400. Two variants in one product create that select the same combination or share a SKU or barcode, or two options with the same name, return 400 INVALID_REQUEST with detail INVALID_VALUE and param naming the later entry, such as variants[1].selected_options, instead of 409 VARIANT_OPTION_COMBINATION_ALREADY_EXISTS or PRODUCT_OPTION_ALREADY_EXISTS. Fix the request; nothing stored conflicts.

Breaking: DANGLING_EXPANSION_REFERENCE is INTERNAL_ERROR. When an expansion finds a stored reference to a record that no longer exists, Flint returns 500 INTERNAL_ERROR. It is a Flint data failure, not a problem with your request. Retry, or read the resource without that expand value, and contact support with the request_id.

CHECKOUT_SESSION_ALREADY_EXISTS, PAYMENT_METHOD_HAS_ACTIVE_SUBSCRIPTIONS, and PROMOTION_HAS_ACTIVE_SUBSCRIPTION_OFFERS are unchanged. A response replayed for an Idempotency-Key first used before this change carries the new code without blockers or current_resource, and so does a refusal whose holder Flint can't read at that moment. See Error handling.

  • Breaking change
  • API
  • Fulfillment

Packages dispatch and complete shipments, and the buyer gets one email per moment#

A shipment fulfillment with packages now moves itself. It reaches dispatched once every unit is in an outbound package and every package has shipped, and completed once every package is delivered, in the same request as the package transition. dispatched_at is the latest package's shipped_at, and completed_at is the latest package's delivered_at. fulfillment.completed therefore fires at carrier delivery instead of at your complete, and returns become possible from then, with a delivered return window counting from that delivery. A package in exception or returned blocks the automatic complete, and a completed fulfillment is never reopened. dispatch and complete still work for shipments without packages and as overrides. See How packages move the fulfillment.

Breaking: POST /v1/fulfillments/{fulfillment_id}/events records only entries that change no status. event_type accepts carrier_scan and custom; shipped, in_transit, out_for_delivery, delivered, delivery_attempted, exception, returned, and tracking_updated return 400 INVALID_REQUEST with param: event_type. Send the matching package transition instead. The request no longer takes buyer_notification_behavior, and the response no longer has fulfillment_notifications, because these entries never email the buyer. carrier_scan is a new event_type value on fulfillment events.

Breaking: once a shipment fulfillment has a package, PATCH /v1/fulfillments/{fulfillment_id} returns 409 ACTION_NOT_ALLOWED with param: completed_at and details[0].reason: derived_from_packages when it sets completed_at, because the packages set it.

Breaking: the buyer gets one email per moment. Packages send shipped, out for delivery, delivery attempted, delivered, exception, and returned, once each per package. When packages move the fulfillment, they send nothing more, and a dispatch or complete you send stays silent once a package sent that moment. Without packages, a shipment's dispatch sends the shipped email and complete the delivered email. In transit scans and tracking changes no longer email, so buyer_notification_behavior is removed from POST /v1/shipments/{shipment_id}/packages, PATCH /v1/packages/{package_id}, and shipment.package on POST /v1/orders/{order_id}/fulfillments. Transitions and voids keep it. See What the buyer receives.

  • API
  • Subscriptions
  • Payment-methods
  • Errors

Retry PAYMENT_METHOD_NOT_READY with the same Idempotency-Key#

Superseded by Payment errors use shared codes and resource facts.

Same key, once the card is ready. Changing a subscription's card with a card that is still pending returns 409 PAYMENT_METHOD_NOT_READY and changes nothing. That refusal now releases the request's Idempotency-Key, and its remediation.retry is same_request. Send the same request with the same key once payment_method.saved arrives, and it attaches the card. Before, a retry with that key returned 409 IDEMPOTENCY_KEY_IN_PROGRESS until the key's lease expired, so each attempt needed a new key. This applies to POST /v1/subscriptions/{subscription_id}/payment-method, POST /v1/me/subscriptions/{subscription_id}/payment-method, and POST /v1/subscriptions.

Other card refusals replay. On the card change routes, RESOURCE_NOT_FOUND for the card, PAYMENT_METHOD_CUSTOMER_MISMATCH, PAYMENT_METHOD_NOT_ACTIVE, and PAYMENT_METHOD_ON_SESSION_ONLY can't change by asking again, so the same key returns the same refusal. Use a new key for a different card. See Saved cards.

Superseded on 2026-10-25. This refusal is now 409 ACTION_NOT_ALLOWED with reason status_not_reached and remediation.retry: none, and the original key replays it. Once the card is active, send a new request with a new Idempotency-Key. See Payment errors use shared codes.