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_statussays whether the money arrived.fulfillment_statussays whether the goods left. Neither implies the other. - Know which values are final. Several values that sound final can still change, such as a
succeededrefund or asucceededpayout. - 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 fromstatus. - 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 know | Read |
|---|---|
| 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 -->
| Vocabulary | Resource and field | Final values |
|---|---|---|
api_key_status | APIKey status | revoked |
applied_discount_status | OrderDiscount status | redeemed, canceled |
balance_transaction_status | BalanceTransaction status | None |
bundle_status | Bundle status | archived |
category_status | Category status | deleted |
checkout_payment_method_save_status | CheckoutPaymentMethodSave status | expired |
checkout_session_status | CheckoutSession status | paid, partially_paid, expired, closed, invalidated |
credit_note_status | CreditNote status | void |
customer_deletion_request_status | CustomerDeletionRequest status | completed, rejected |
customer_status | Customer status | deleted |
delivery_choice_group_availability_status | DeliveryQuoteChoiceGroupResource availability_status | None |
delivery_configuration_status | Product delivery_configuration_status | None |
delivery_location_set_status | DeliveryLocationSet status | archived |
delivery_method_status | DeliveryMethod status | archived |
delivery_profile_status | DeliveryProfile status | archived |
delivery_quote_status | DeliveryQuote status | revoked |
delivery_rate_callback_status | DeliveryRateCallback status | archived |
delivery_selection_status | DeliverySelection status | committed, superseded, expired, released |
delivery_zone_status | DeliveryZone status | archived |
developer_sandbox_status | Sandbox status | archived |
device_status | Device status | archived |
dispute_status | Dispute status | lost |
file_status | File status | failed, expired |
fulfillment_status | Fulfillment status | completed, canceled, failed, no_show |
gift_card_funding_dispute_status | GiftCardFundingDispute status | None |
gift_card_purchase_refund_allocation_status | GiftCardPurchaseRefundAllocation status | succeeded, failed |
gift_card_redemption_status | GiftCardRedemption status | succeeded, canceled, expired |
gift_card_status | GiftCard status | closed |
inventory_allocation_policy_status | InventoryAllocationPolicy status | archived |
inventory_count_status | InventoryCount status | applied, canceled |
inventory_item_status | InventoryItem status | archived |
inventory_reservation_status | InventoryReservation status | closed |
inventory_transfer_status | InventoryTransfer status | closed |
invoice_collection_block_status | Invoice collection_block_status | None |
invoice_payment_attempt_status | InvoicePaymentAttempt status | settled, failed, canceled, expired |
invoice_payment_term_status | InvoicePaymentTerm status | archived |
invoice_schedule_entry_status | InvoiceScheduleEntry status | None |
invoice_status | Invoice status | void, uncollectible |
location_status | Location status | archived |
merchant_billing_invoice_status | MerchantBillingInvoice status | written_off |
merchant_readiness_status | ReadinessAxis status | None |
merchant_status | Merchant status | None |
message_status | WebhookDelivery status; GiftCardNotification status | canceled |
modifier_group_status | ModifierGroup status | archived |
modifier_set_status | ModifierSet status | archived |
modifier_status | Modifier status | archived |
onboarding_state_status | OnboardingState status | None |
order_fulfillment_status | Order fulfillment_status | None |
order_inventory_exception_status | Order inventory_exception_status | None |
order_payment_attempt_status | OrderPaymentAttempt status | partially_succeeded, succeeded, failed, canceled, expired |
order_payment_status | Order payment_status | paid |
order_status | Order status | closed |
order_tax_status | OrderTax status | None |
order_ticket_status | TicketedEvent ticket_status | void |
organization_membership_status | OrganizationMembership status | None |
organization_status | Organization status | archived |
package_status | Package status | returned, voided |
partner_app_credential_status | PartnerAppCredential status | removed |
partner_app_install_status | PartnerAppInstall status | None |
partner_environment_grant_status | PartnerEnvironmentGrant status | None |
payment_fulfillment_hold_status | PaymentFulfillmentHold status | released |
payment_intent_dispute_status | PaymentIntent dispute_status | None |
payment_intent_status | PaymentIntent status | canceled, succeeded, expired |
payment_link_status | PaymentLink status | None |
payment_method_domain_status | PaymentMethodDomain status | None |
payment_method_status | PaymentMethod status | archived |
payment_refund_status | PaymentRefund status | failed, canceled |
payment_review_status | PaymentReview status | closed |
payout_destination_status | PayoutDestination status | None |
payout_reversal_status | Payout reversal_status | reversed |
payout_settings_status | PayoutSettings status | None |
payout_status | Payout status | None |
product_option_status | ProductOption status | archived |
product_option_value_status | ProductOptionValue status | archived |
product_status | Product status | archived |
product_variant_status | ProductVariant status | archived |
promotion_code_status | PromotionCode status | archived |
promotion_status | Promotion status | archived |
refund_status | Order refund_status | None |
refund_status_lifecycle | Refund status | failed |
refund_tender_allocation_status | RefundTenderAllocation status | failed, canceled |
report_status | Report status | succeeded, failed |
return_decision_status | Return decision_status | approved, partially_approved, declined |
return_disposition_status | ReturnDisposition status | succeeded, canceled |
return_eligibility_status | ReturnEligibilityPreview status | None |
return_handoff_requirement_status | ReturnHandoffRequirement status | None |
return_inspection_line_item_acceptance_status | ReturnInspectionLineItem acceptance_status | accepted, rejected |
return_inspection_status | ReturnInspection status | superseded |
return_line_item_status | ReturnLineItem status | declined, canceled |
return_merchandise_status | Return merchandise_status | None |
return_policy_status | ReturnPolicy status | archived |
return_reason_status | ReturnReason status | archived |
return_receipt_status | ReturnReceipt status | superseded |
return_resolution_adjustment_status | ReturnResolutionAdjustment status | None |
return_resolution_status | ReturnResolution status | fulfilled, canceled |
return_resolution_summary_status | Return resolution_status | None |
return_status | Return status | declined, canceled |
risk_list_status | RiskList status | archived |
risk_rule_status | RiskRule status | archived |
shipment_status | Shipment status | voided |
subscription_address_verification_state | SubscriptionAddressVerification state | None |
subscription_delivery_migration_status | SubscriptionDeliveryMigration status | completed |
subscription_offer_status | SubscriptionOffer status | archived |
subscription_payment_retry_status | SubscriptionPaymentRetry status | succeeded, failed |
subscription_plan_status | SubscriptionPlan status | archived |
subscription_status | Subscription status | canceled |
tax_connection_status | TaxConnection status | None |
tax_registration_status | TaxRegistration status | removed |
test_clock_status | TestClock status | archived |
tip_status | Tip status | canceled |
user_status | User status | deactivated |
webhook_endpoint_status | WebhookEndpoint status | deleted |
<!-- END GENERATED TERMINAL VALUES -->
These values look final but can still change:
| Value | Can become | When |
|---|---|---|
Refund succeeded or partially_succeeded | partially_succeeded or failed | A bank rejects a refund it first accepted. |
Payout succeeded | failed | The bank returns the deposit. A reversal is reported separately in reversal_status. |
Invoice paid or credited | open or partially_paid | A payment or credit allocation is reversed. invoice.reopened reports it. |
Return completed | open | You reopen it with POST /v1/returns/{return_id}/reopen to record a late fact. return.reopened reports it. |
Package delivered | returned | You 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.
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.
| Field | Answers | Values |
|---|---|---|
status | Does the order still accept changes and new payments? | open, closed |
closed_reason | Why did it close? Present exactly when status is closed. | See below |
payment_status | How much of the total was collected? | unpaid, partially_paid, paid |
refund_status | How much collected money went back? | none, partially_refunded, refunded |
fulfillment_status | How far has the work across all quantities gone? | See below |
inventory_exception_status | Did 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 '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 orderclosed_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 orderSee 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 intentRefunds 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_retryis 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.finalizingmeans 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_succeededis 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 status | Meaning |
|---|---|
pending | At least one part is still in progress. |
succeeded | Every part succeeded. A bank can still reject one later. |
partially_succeeded | Some parts succeeded and the rest failed or were canceled. |
failed | No 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.
| Field | Answers |
|---|---|
decision_status | Did you approve the request? |
merchandise_status | Did the goods come back? On the return, this is the least-finished line's value. |
resolution_status | Did the buyer receive their refund, exchange, or store credit? |
status | Is 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#
| Field | Values |
|---|---|
Invoice status | draft, open, partially_paid, paid, void, uncollectible, credited |
Invoice refund_status | none, partially_refunded, refunded |
Credit note status | draft, issued, void |
Subscription status | trialing, 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_paidmeans the session collected part of the amount due before it ended. The order keeps the remaining balance.expiredmeans the session's deadline passed before it completed.invalidatedmeans 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
exceptionmakes the shipmentexception. - 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
voidedonly 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_closedcan still become a chargeback. needs_responseandunder_revieware an open chargeback.lostis final. A later provider update can changewonorprevented.otheris 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.
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.
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
versionthat increases with each change. Skip a snapshot whoseversionis lower than one you already applied. - Read the resource when the next step depends on it. Disputes and payouts have no
version, and aversioncovers 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, andpartially_paiddescribe 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: archivedand 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: deletedand can't be read afterward. A tax registration returnsstatus: removed. A customer address has nostatusand 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.
