Skip to content

Statuses & lifecycles

You read a status to decide what to do next: ship the goods, retry a payment, grant access, or stop polling. Flint splits those decisions across separate fields, and each field moves on its own. An order has status, payment_status, fulfillment_status, refund_status, and inventory_exception_status, and a paid order can stay not_fulfilled for weeks.

Four rules keep the branches right:

  • Read the field that answers your question. payment_status says whether the money arrived. fulfillment_status says whether the goods left. Neither implies the other.
  • Know which values are final. Several values that sound final can still change, such as a succeeded refund or a succeeded payout.
  • Ask the resource what it accepts. Where a resource has supported_actions, it lists the actions its current state allows. Branch on that instead of rebuilding the rules from status.
  • Treat the resource as the truth and events as the signal. Webhooks arrive at least once and in no guaranteed order. When the next step depends on current state, read the resource.

Find the field for your question#

You want to knowRead
Can I still change this order or take a payment on it?Order status
Why and when did the order close?Order closed_reason and closed_at
Did the buyer pay for the order?Order payment_status
Has money gone back to the buyer?refund_status on the order, payment intent, or invoice
Have the goods been delivered or handed over?Order fulfillment_status for the whole order, Fulfillment status for one piece of work
Where is a parcel?Package status, or Shipment status for all its packages
Did this payment succeed?PaymentIntent status
Did my pay request finish, and can I resume it?Payment attempt status and is_resumable
Is a payment disputed?PaymentIntent dispute_status, then Dispute status
Is the return finished?Return status and completion_blockers
Is the subscriber current on billing?Subscription status
Did the payout reach my bank, and did it stay there?Payout status and reversal_status
Which actions can I take right now?supported_actions, where the resource has it

The same word means different things in different fields, so always read a value together with its field name. paid on an order's payment_status means collection completed. succeeded on a payout means the bank received the deposit. closed on an order's status means it no longer accepts changes, closed on its fulfillment_status means every quantity was either fulfilled or canceled, and closed on a checkout session means a merchant closed it. pending appears on refunds, payouts, fulfillments, and two of a return's statuses, with a different meaning on each.

Which values are final#

A final value never changes again. The OpenAPI specification publishes each closed status vocabulary's final values in x-flint-terminal-values and ends each final value's description with "This status is final." Copies and narrowed projections carry the same metadata for the values they return. An empty set means no value is guaranteed final; keep listening for events or read the resource again.

<!-- BEGIN GENERATED TERMINAL VALUES -->

VocabularyResource and fieldFinal values
api_key_statusAPIKey statusrevoked
applied_discount_statusOrderDiscount statusredeemed, canceled
balance_transaction_statusBalanceTransaction statusNone
bundle_statusBundle statusarchived
category_statusCategory statusdeleted
checkout_payment_method_save_statusCheckoutPaymentMethodSave statusexpired
checkout_session_statusCheckoutSession statuspaid, partially_paid, expired, closed, invalidated
credit_note_statusCreditNote statusvoid
customer_deletion_request_statusCustomerDeletionRequest statuscompleted, rejected
customer_statusCustomer statusdeleted
delivery_choice_group_availability_statusDeliveryQuoteChoiceGroupResource availability_statusNone
delivery_configuration_statusProduct delivery_configuration_statusNone
delivery_location_set_statusDeliveryLocationSet statusarchived
delivery_method_statusDeliveryMethod statusarchived
delivery_profile_statusDeliveryProfile statusarchived
delivery_quote_statusDeliveryQuote statusrevoked
delivery_rate_callback_statusDeliveryRateCallback statusarchived
delivery_selection_statusDeliverySelection statuscommitted, superseded, expired, released
delivery_zone_statusDeliveryZone statusarchived
developer_sandbox_statusSandbox statusarchived
device_statusDevice statusarchived
dispute_statusDispute statuslost
file_statusFile statusfailed, expired
fulfillment_statusFulfillment statuscompleted, canceled, failed, no_show
gift_card_funding_dispute_statusGiftCardFundingDispute statusNone
gift_card_purchase_refund_allocation_statusGiftCardPurchaseRefundAllocation statussucceeded, failed
gift_card_redemption_statusGiftCardRedemption statussucceeded, canceled, expired
gift_card_statusGiftCard statusclosed
inventory_allocation_policy_statusInventoryAllocationPolicy statusarchived
inventory_count_statusInventoryCount statusapplied, canceled
inventory_item_statusInventoryItem statusarchived
inventory_reservation_statusInventoryReservation statusclosed
inventory_transfer_statusInventoryTransfer statusclosed
invoice_collection_block_statusInvoice collection_block_statusNone
invoice_payment_attempt_statusInvoicePaymentAttempt statussettled, failed, canceled, expired
invoice_payment_term_statusInvoicePaymentTerm statusarchived
invoice_schedule_entry_statusInvoiceScheduleEntry statusNone
invoice_statusInvoice statusvoid, uncollectible
location_statusLocation statusarchived
merchant_billing_invoice_statusMerchantBillingInvoice statuswritten_off
merchant_readiness_statusReadinessAxis statusNone
merchant_statusMerchant statusNone
message_statusWebhookDelivery status; GiftCardNotification statuscanceled
modifier_group_statusModifierGroup statusarchived
modifier_set_statusModifierSet statusarchived
modifier_statusModifier statusarchived
onboarding_state_statusOnboardingState statusNone
order_fulfillment_statusOrder fulfillment_statusNone
order_inventory_exception_statusOrder inventory_exception_statusNone
order_payment_attempt_statusOrderPaymentAttempt statuspartially_succeeded, succeeded, failed, canceled, expired
order_payment_statusOrder payment_statuspaid
order_statusOrder statusclosed
order_tax_statusOrderTax statusNone
order_ticket_statusTicketedEvent ticket_statusvoid
organization_membership_statusOrganizationMembership statusNone
organization_statusOrganization statusarchived
package_statusPackage statusreturned, voided
partner_app_credential_statusPartnerAppCredential statusremoved
partner_app_install_statusPartnerAppInstall statusNone
partner_environment_grant_statusPartnerEnvironmentGrant statusNone
payment_fulfillment_hold_statusPaymentFulfillmentHold statusreleased
payment_intent_dispute_statusPaymentIntent dispute_statusNone
payment_intent_statusPaymentIntent statuscanceled, succeeded, expired
payment_link_statusPaymentLink statusNone
payment_method_domain_statusPaymentMethodDomain statusNone
payment_method_statusPaymentMethod statusarchived
payment_refund_statusPaymentRefund statusfailed, canceled
payment_review_statusPaymentReview statusclosed
payout_destination_statusPayoutDestination statusNone
payout_reversal_statusPayout reversal_statusreversed
payout_settings_statusPayoutSettings statusNone
payout_statusPayout statusNone
product_option_statusProductOption statusarchived
product_option_value_statusProductOptionValue statusarchived
product_statusProduct statusarchived
product_variant_statusProductVariant statusarchived
promotion_code_statusPromotionCode statusarchived
promotion_statusPromotion statusarchived
refund_statusOrder refund_statusNone
refund_status_lifecycleRefund statusfailed
refund_tender_allocation_statusRefundTenderAllocation statusfailed, canceled
report_statusReport statussucceeded, failed
return_decision_statusReturn decision_statusapproved, partially_approved, declined
return_disposition_statusReturnDisposition statussucceeded, canceled
return_eligibility_statusReturnEligibilityPreview statusNone
return_handoff_requirement_statusReturnHandoffRequirement statusNone
return_inspection_line_item_acceptance_statusReturnInspectionLineItem acceptance_statusaccepted, rejected
return_inspection_statusReturnInspection statussuperseded
return_line_item_statusReturnLineItem statusdeclined, canceled
return_merchandise_statusReturn merchandise_statusNone
return_policy_statusReturnPolicy statusarchived
return_reason_statusReturnReason statusarchived
return_receipt_statusReturnReceipt statussuperseded
return_resolution_adjustment_statusReturnResolutionAdjustment statusNone
return_resolution_statusReturnResolution statusfulfilled, canceled
return_resolution_summary_statusReturn resolution_statusNone
return_statusReturn statusdeclined, canceled
risk_list_statusRiskList statusarchived
risk_rule_statusRiskRule statusarchived
shipment_statusShipment statusvoided
subscription_address_verification_stateSubscriptionAddressVerification stateNone
subscription_delivery_migration_statusSubscriptionDeliveryMigration statuscompleted
subscription_offer_statusSubscriptionOffer statusarchived
subscription_payment_retry_statusSubscriptionPaymentRetry statussucceeded, failed
subscription_plan_statusSubscriptionPlan statusarchived
subscription_statusSubscription statuscanceled
tax_connection_statusTaxConnection statusNone
tax_registration_statusTaxRegistration statusremoved
test_clock_statusTestClock statusarchived
tip_statusTip statuscanceled
user_statusUser statusdeactivated
webhook_endpoint_statusWebhookEndpoint statusdeleted

<!-- END GENERATED TERMINAL VALUES -->

These values look final but can still change:

ValueCan becomeWhen
Refund succeeded or partially_succeededpartially_succeeded or failedA bank rejects a refund it first accepted.
Payout succeededfailedThe bank returns the deposit. A reversal is reported separately in reversal_status.
Invoice paid or creditedopen or partially_paidA payment or credit allocation is reversed. invoice.reopened reports it.
Return completedopenYou reopen it with POST /v1/returns/{return_id}/reopen to record a late fact. return.reopened reports it.
Package deliveredreturnedYou mark it returned after a return to sender. Its shipment reads returned once every package in it is.

Order closed is final, but it stops changes, not activity. Refunds, fulfillment, disputes, returns, and metadata or note edits all continue on a closed order. closed_reason and closed_at are set once when the order closes and never change.

New values and your API version#

Status fields are closed, so you branch on them. Under the closed enum rule, a closed status can still gain a value on the version you pin, so keep a default branch for a status you don't recognize. Check the changelog for new values.

Reason fields are extensible and gain values at any time: closed_reason, failure_reason, cancellation_reason, terminal_reason, pause_reason, and the payment attempt's status_reason. Branch on the reasons you handle and keep a default branch for the rest. The OpenAPI specification marks every response enum with x-flint-enum-kind, either closed or extensible, and API versions and upgrades covers the full rule.

TypeScript
type Refund = {
  refund_id: string;
  status: "pending" | "succeeded" | "partially_succeeded" | "failed";
  failure_reason?: string;
};

function handleRefund(refund: Refund) {
  // status is closed, so each value you know has a branch. Keep a default for a new one.
  switch (refund.status) {
    case "pending":
      return; // Wait for refund.succeeded, refund.partially_succeeded, or refund.failed.
    case "succeeded":
    case "partially_succeeded":
      return recordRefund(refund); // A bank can still reject it later.
    case "failed":
      return handleFailedRefund(refund);
  }
}

function handleFailedRefund(refund: Refund) {
  // failure_reason is extensible, so unknown reasons need a default.
  switch (refund.failure_reason) {
    case "expired_or_canceled_card":
      return askBuyerWhereToSendMoney(refund);
    case "insufficient_available_balance":
      return alertFinanceTeam(refund);
    default:
      return flagForReview(refund);
  }
}

Orders#

An order is the durable record of a sale, so it carries the most fields.

FieldAnswersValues
statusDoes the order still accept changes and new payments?open, closed
closed_reasonWhy did it close? Present exactly when status is closed.See below
payment_statusHow much of the total was collected?unpaid, partially_paid, paid
refund_statusHow much collected money went back?none, partially_refunded, refunded
fulfillment_statusHow far has the work across all quantities gone?See below
inventory_exception_statusDid stock fail after payment? Absent when nothing went wrong.paid_inventory_failed, resolved

The money fields are independent. A refund changes refund_status and never payment_status, so a fully refunded order reads payment_status: paid and refund_status: refunded, because the money did arrive before it went back. An order becomes paid when collection completes, which is also when it closes with closed_reason: paid.

To list orders by more than one field, combine the filters on GET /v1/orders. Values within one filter match any of them, and separate filters must all match. This lists paid orders that were refunded in full:

cURL
curl 'https://api.withflintpay.com/v1/orders?payment_status=paid&refund_status=refunded' \
  -H "Authorization: Bearer YOUR_API_KEY"

Why an order closed#

closed_reason and closed_at record how and when an order closed, once, at the moment it closed. Read them instead of inferring the reason from the payment fields. closed_reason is extensible, so treat a reason you don't recognize like other.

closed_reason on order
  • paid
    Collection completed, including a zero-balance order completed with POST /v1/orders/{order_id}/pay. closed_at is when collection completed.
  • closed_by_merchant
    You closed it with POST /v1/orders/{order_id}/close. A partially paid order you close keeps its money and still reads partially_paid. Your note, if you sent one, is in closed_reason_message.
  • checkout_expired
    An unpaid payment-link checkout expired. See Checkout sessions.
  • written_off
    The order's invoice was marked uncollectible. payment_status reflects only what was paid, unpaid or partially_paid, because the written-off balance never arrived.
  • superseded
    A newer subscription renewal attempt replaced this unpaid order.
  • return_resolution_canceled
    The return resolution that created this replacement order was canceled.
  • other
    A reason Flint doesn't recognize. Handle any value you don't know the same way.

closed_reason_message holds only the note you sent to POST /v1/orders/{order_id}/close. Closures Flint makes leave it absent. Buyers never see it.

Order fulfillment status#

fulfillment_status counts quantities in completed and canceled fulfillments only. It stays not_fulfilled while goods are picked, packed, and dispatched, and moves once a fulfillment completes. Read each fulfillment's own status for the step it has reached.

fulfillment_status on order
  • not_applicable
    Nothing on the order needs fulfilling.
  • not_fulfilled
    No quantity has been fulfilled or canceled yet.
  • partially_fulfilled
    Some quantity was fulfilled and some is still outstanding.
  • fulfilled
    Every quantity was fulfilled.
  • canceled
    Every quantity was canceled.
  • closed
    Every quantity was either fulfilled or canceled, with some of each.

See Why Flint is orders-first for the model, the Orders reference for every filter, and Order activities for the history of an order.

Payments#

Two resources describe a payment. A payment intent is one payment from a buyer, such as one card charge, for an order or standalone. A payment attempt is one POST /v1/orders/{order_id}/pay call across the payment intents you selected; with split tender, each payment intent is one leg of the attempt.

status on payment intent
Final values do not change again
  • requires_payment_method
    Waiting for payment details. Either nothing was attempted yet, or the last attempt was declined, failed, or blocked, and last_payment_error says why.
  • requires_confirmation
    Payment details are attached but confirmation hasn't finished. This is brief unless confirmation was interrupted.
  • requires_action
    The buyer must finish a step, such as 3D Secure or a redirect, before the payment can continue.
  • processing
    Submitted, with the outcome not known yet. ACH debits stay here for a few business days until the bank settles them.
  • requires_capture
    A manual-capture hold is in place and nothing is collected yet. Capture or cancel before authorization_expires_at.
  • succeededFinal
    Collected. captured_money is the amount.
  • canceledFinal
    Canceled before any money was collected. cancellation_reason says why when Flint knows it.
  • expiredFinal
    A manual-capture hold reached authorization_expires_at without a capture, and the funds went back to the buyer.

Refunds and disputes never change a payment intent's status. Read its refund_status and dispute_status for those. dispute_status is none or one of the dispute statuses described below.

A payment attempt's status is one of processing, requires_action, requires_capture, requires_retry, finalizing, succeeded, partially_succeeded, failed, canceled, or expired. Three of them decide how you write the branch:

  • requires_retry is an unknown outcome, not a decline. Flint doesn't know yet whether every leg went through, so resume the same attempt and let Flint read the result instead of starting a new payment.
  • finalizing means the outcome is known and Flint is applying it to the order. The buyer has usually been charged already, so a new payment would charge them twice. Wait and read the attempt again.
  • partially_succeeded is final for the attempt, and the order still has a balance. Collect only the remainder.

Read is_resumable before you choose between resuming and starting over. Declines and payment attempts has the full attempt lifecycle and recovery model.

Refunds#

A refund's status summarizes its parts: each entry in payment_refunds and tender_allocations has its own status of pending, requires_action, succeeded, failed, or canceled.

Refund statusMeaning
pendingAt least one part is still in progress.
succeededEvery part succeeded. A bank can still reject one later.
partially_succeededSome parts succeeded and the rest failed or were canceled.
failedNo money went back, and failure_reason says why. The amount is refundable again. Final.

POST /v1/refunds returns 201 whenever it creates a refund. When processing finishes during the request, the response reports the outcome, including status: "failed" for a processor rejection. Otherwise it returns pending; read the refund with GET /v1/refunds/{refund_id} or follow refund.* events for its current state. Check status on every create response. A parent status change sends refund.succeeded, refund.partially_succeeded, or refund.failed, and other changes send refund.updated. Refunds covers each status and how to recover from a failure.

Returns#

A return keeps four statuses because the decision, the goods, and the money each move at their own pace.

FieldAnswers
decision_statusDid you approve the request?
merchandise_statusDid the goods come back? On the return, this is the least-finished line's value.
resolution_statusDid the buyer receive their refund, exchange, or store credit?
statusIs the whole return finished?

status is requested while the return waits for a decision, open once some quantity is approved, and completed once every blocker clears. declined and canceled are final.

completion_blockers lists what is still owed, and an empty array is the real done signal. Act on return.completed rather than on a refund succeeding: a resolution can settle while merchandise work is still open. Returns has the full value sets and transitions.

Invoices, credit notes, and subscriptions#

FieldValues
Invoice statusdraft, open, partially_paid, paid, void, uncollectible, credited
Invoice refund_statusnone, partially_refunded, refunded
Credit note statusdraft, issued, void
Subscription statustrialing, active, paused, past_due, canceled, incomplete, scheduled

paid and credited both mean the invoice's current balance is cleared: paid when collected money cleared it, and credited when applied credit cleared it with no money collected. Either can reopen to open or partially_paid when a payment or credit allocation is reversed, and invoice.reopened reports it. void and uncollectible are final. A refund changes refund_status without reopening the balance.

For subscriptions, incomplete means the first period's payment is still being collected or is held, so don't provision yet. scheduled means the subscription waits for starts_at and nothing has been charged. At starts_at it becomes active once the first payment succeeds, or past_due if it fails. past_due means a charge failed and Flint is retrying or waiting for a new payment method. Whether a past-due subscriber keeps access is your decision. paused suspends billing, and pause_reason says why.

See Invoicing, Credit notes, and Subscription billing.

Checkout sessions#

A checkout session is open, paid, partially_paid, expired, closed, or invalidated. Every value except open is final, and terminal_reason says why the session ended.

  • partially_paid means the session collected part of the amount due before it ended. The order keeps the remaining balance.
  • expired means the session's deadline passed before it completed.
  • invalidated means something outside the session ended it, such as a replacement session, a payment made elsewhere, or an order edit that closed or completed the order. Other order edits keep the session open.

An expired payment-link checkout also closes its order when nothing was paid or authorized, no invoice or other active collection owns the order, and the order isn't linked to a return. The order sends order.closed with closed_reason: checkout_expired. When an existing-order, quick-pay, subscription-plan, or invoice checkout expires, the order stays open. Checkout sessions covers each status.

Fulfillments, shipments, and packages#

A fulfillment's status is exact for its type, so the set is wide: pending, accepted, scheduled, in_progress, preparing, picked, packed, ready, dispatched, on_hold, completed, canceled, failed, and no_show. The last four are final, and terminal_at records when the fulfillment reached one. A missed pickup or appointment reads no_show, with the reason in outcome.

A fulfillment on_hold carries active_hold, whose previous_status is where the work paused. It leaves the hold only forward: release_hold returns it to previous_status, and any other action that status allows moves it on. Buyer responses never show a hold. They show previous_status instead. Fulfillment and shipping has each status and action.

A package is one parcel, and its status follows the carrier: created, packed, shipped, in_transit, out_for_delivery, delivery_attempted, delivered, exception, returned, or voided. returned and voided are final. A delivered package can still be marked returned, and a package can be voided only before handoff, while it is created or packed. Each package lists the actions it accepts in supported_actions.

A shipment's status is read-only and derived from its packages:

  • Voided packages don't count. A shipment with no other packages reads created.
  • Any package in exception makes the shipment exception.
  • Otherwise the least advanced package sets it, in this order: created, packed, shipped, in_transit, out_for_delivery, delivery_attempted, delivered, returned.
  • A shipment reads voided only when you void the whole shipment.

A shipment also has a direction: outbound sends items to the buyer, and return brings them back to you. Return tracking lives on a return shipment rather than on the return itself.

Disputes and payouts#

A dispute's status is inquiry_needs_response, inquiry_under_review, inquiry_closed, needs_response, under_review, won, lost, prevented, or other.

  • The inquiry_* values are the issuer's questions before any chargeback, and the case may never become one. inquiry_closed can still become a chargeback.
  • needs_response and under_review are an open chargeback. lost is final. A later provider update can change won or prevented.
  • other is a state Flint doesn't recognize yet and isn't final. Treat the dispute as open, don't assume an outcome, and read it again later.

A payout's status is pending until it is sent, in_transit on its way to your bank, then succeeded or failed. canceled means a manual payout was canceled while pending. A succeeded payout can still become failed if the bank returns the deposit. Separately, reversal_status moves from none to reversed when Flint pulls a paid payout back from your bank: a payout_reversal balance transaction returns the money, and status stays succeeded. Read both fields.

See Disputes and Payouts.

Decide what you can do next#

status tells you what happened. To decide whether an action is available now, read supported_actions on the resources that carry it: payment intents, fulfillments, packages, returns, return resolutions, subscriptions, and gift cards. It lists only actions the resource's own state allows. A listed action can still be refused by something outside the resource, such as a payment in progress on its order, so handle the errors below either way.

Writes that depend on a resource's state accept the version you read as expected_version, in the body or, for DELETE, as a query parameter. Flint compares it before changing anything.

  • HTTP 409
    The resource's current state doesn't allow the action. details[0] carries current_status, supported_actions, and a reason such as terminal_status, unsupported_state, in_progress, or status_not_reached. Read the resource again and choose an action from supported_actions
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The resource changed after you read it, and nothing was applied. param names the version field you sent, and details[0].current_version has the current version. Read the resource again, decide again, and send the new version with a new Idempotency-Key

Read statuses from webhooks#

An event's data.object is a snapshot of the resource when the event happened. Because delivery is at least once and unordered, a later snapshot can arrive before an earlier one.

  • Compare versions, not arrival order. Orders, payment intents, refunds, returns, fulfillments, shipments, packages, invoices, credit notes, subscriptions, and checkout sessions carry a version that increases with each change. Skip a snapshot whose version is lower than one you already applied.
  • Read the resource when the next step depends on it. Disputes and payouts have no version, and a version covers only the resource's own fields, not resources expanded inside it. When you are about to ship, refund, or grant access, fetch the current state first.
  • Money statuses aren't permissions. past_due, requires_capture, and partially_paid describe the money. What access or service that buys is your decision.

Webhooks covers delivery, retries, and deduplication, and the event payloads list the status each event reports.

What a delete returns#

DELETE takes no request body and returns 200 with the resource in the same shape GET returns. It never returns {"success": true}. Most DELETE routes accept expected_version as a query parameter to delete only if nothing changed since your read.

  • Archived resources stay readable. Products, bundles, promotions and promotion codes, payment methods, payout destinations, locations, and most configuration resources return status: archived and stay readable by ID. Repeating the delete on an archived product, bundle, promotion, payment method, or delivery configuration resource returns it again unchanged.
  • Removed resources keep their record. An organization membership and a partner app credential return status: removed.
  • Permanently deleted resources return a final snapshot. A category and a webhook endpoint return status: deleted and can't be read afterward. A tax registration returns status: removed. A customer address has no status and returns the address as it was when Flint deleted it.
  • Removing a line returns its parent. Deleting an order's line item, charge, or gift card returns the order. Deleting a subscription line item returns the subscription, and deleting a return line item returns the return.

A buyer's saved gift card works the same way. DELETE /v1/me/gift-cards/{gift_card_id} removes only that buyer's saved access, returns the card as they saw it, and returns 404 for a card they never saved or already removed. Retrying with the original Idempotency-Key replays the first response.

Next steps#

Declines and payment attemptsThe payment attempt lifecycle, resuming, and recovering from a decline.WebhooksDelivery, retries, ordering, and deduplication.API versions and upgradesHow new status values reach your integration.ErrorsEvery error code and its retry guidance.

Was this helpful?