Appearance
Order Lifecycle
This document describes every status an order can have, every transition between them, what triggers each transition, and what side effects occur.
Status Overview
| Status | Description |
|---|---|
DRAFT | Created but not yet finalized. Positions can still be modified. |
PENDING | Finalized and awaiting payment. |
NEEDS_MANUAL_CAPTURE | Payment authorized/reserved; awaiting a Service/Admin to confirm or cancel the capture. Only reached with capture_mode: manual. |
COMPLETED_OUTSTANDING | Payment received, but a chargeback is still possible. |
COMPLETED_FINALIZED | Fully settled. No chargeback possible. |
PARTIALLY_REFUNDED | Partially refunded. |
REFUNDED | Fully refunded. |
REVOKED | Payment was charged back, or the order fell overdue and was revoked. |
DUNNING | Dunning is active - a genuine customer payment default (card declined, mandate charge failed, invoice overdue). |
FAILED | A technical error occurred while attempting the charge (Payment Processor/partner infrastructure issue or a TiruPay-side request bug) - not the customer's fault, retried automatically. |
CANCELLED | Cancelled - payment expired, aborted, or never received. |
WRITTEN_OFF | Dunning exhausted every configured tier - terminal, no automatic way back. |
COMPLETED_OUTSTANDING vs COMPLETED_FINALIZED
The distinction between these two statuses is only relevant for tax logs. RECEIVED_OUTSTANDING tax logs can still be reverted; RECEIVED_FINALIZED ones cannot. From a business logic perspective both statuses mean "paid".
Automatically managed statuses
COMPLETED_FINALIZED is set automatically every day once the chargeback window has closed. PARTIALLY_REFUNDED is set by TiruPay when a partial refund is processed.
Transitions in Detail
DRAFT → PENDING
Trigger: Explicit API call (POST /orders/{id}/finalize)
Precondition: Order must be in DRAFT, valid_till must not have passed, and a customer must be linked - a customer-less draft order cannot be finalized until one is.
What happens:
- Customer is created in the payment processor if not already present
- Payment method is validated against all articles
- Tax logs are created for all positions (status:
PENDING) - skipped forcapture_mode: manual, deferred until the capture is confirmed (see "NEEDS_MANUAL_CAPTURE → PENDING" below) total_taxandtotal_tax_after_discountare calculated on all positions- A payment record is created in TiruPay
- For subscriptions: a mandate is created or reused (SEPA, PayPal, Mollie credit card)
- An invoice is created in the external invoicing provider - skipped for
capture_mode: manual, deferred until the capture is confirmed - Payment is initiated in the payment processor, with the invoice number as payment reference (see Invoicing). If this fails, the invoice is cancelled again.
- If the service's payment method configuration has
activate_features_on = pending- features (and, for a first-time subscription order, the Subscription record itself) are activated immediately here, before payment is confirmed. See Payments. - Returns a redirect URL to the payment page
Features are activated here only for the activate_features_on = pending case above - otherwise, that happens only after successful payment.
PENDING → NEEDS_MANUAL_CAPTURE
Trigger: Payment processor webhook (payment_status: "ready_for_capture") - only occurs for orders finalized with capture_mode: manual, see Capture Modes.
Precondition: Order must be PENDING and have a customer.
Idempotent: Yes - if the order is already NEEDS_MANUAL_CAPTURE, a duplicate webhook delivery is a no-op.
What happens: Nothing else changes yet - the order waits for a Service/Admin to confirm or cancel the capture.
NEEDS_MANUAL_CAPTURE → PENDING (capture confirmed)
Trigger: Explicit API call (POST /orders/{id}/capture, Service/Admin only)
What happens:
- Tax logs are created for all positions (deferred from finalization, see step 3 above)
total_taxandtotal_tax_after_discountare calculated- Any Credit Balance surplus is refunded to the customer, if positions were reduced since the reservation was made
- An invoice is created in the external invoicing provider
- The order returns to
PENDING - The payment partner is told to actually capture the reserved amount
From here the order continues through the normal PENDING → COMPLETED_OUTSTANDING flow once the payment webhook confirms the capture.
NEEDS_MANUAL_CAPTURE → CANCELLED
Reached via two different triggers, same outcome:
- Explicit API call (
POST /orders/{id}/cancel_capture, Service/Admin only) - releases the reservation at the partner. - Payment processor webhook (
payment_status: "expired") - the partner expired the reservation on its own; nothing needs to be freed.
Terminal status.
PENDING → DRAFT / PENDING / FAILED (payment failed)
Reached via two different triggers with different meanings:
- Payment processor webhook (
payment_status: "failed") - a genuine customer-caused decline (card declined, insufficient funds, mandate revoked). The payment processor has already exhausted its own retry attempts before reporting this. - The payment attempt itself could not be carried out - almost always a technical or infrastructure issue, essentially never the customer's fault.
What happens (common steps):
- A payment-method-failure email is sent to the customer (only once - not repeated on later retries within the same overdue window)
- All
PENDINGtax logs are set toCANCELLED(withrefund_date) - Any Credit Balance used on the order is refunded back to the customer
Resulting status:
| Case | Resulting status | PAYG balance usage | Invoice |
|---|---|---|---|
| Technical/infrastructure failure | FAILED | Unchanged (BILLED_PENDING stays as-is) | Kept |
| Subscription renewal or PAYG order, customer-caused decline | Stays PENDING, due_date set | Unchanged (BILLED_PENDING stays as-is) | Kept, so dunning can create a reminder once the order is eventually revoked |
| One-time order, customer-caused decline | DRAFT | Reset BILLED_PENDING → PENDING | Cancelled - the customer can try again |
PAYG orders are billed for usage already consumed by the customer - BILLED_PENDING is only ever reset to PENDING for genuine one-time orders reverting to DRAFT, never for PAYG or subscription orders, since the service is still owed that money through this same order.
Subscription/PAYG declines don't jump straight to DUNNING
A customer-caused decline on a subscription renewal or PAYG order keeps the order PENDING and stamps due_date (if not already set), rather than transitioning straight to DUNNING. This lets the same overdue-revocation mechanism used for invoice-style orders (see below) handle both paths uniformly - see Dunning. In the meantime, the order keeps getting retried via the mandate on a daily schedule.
PENDING → CANCELLED (payment aborted or expired)
Trigger: Payment processor webhook (payment_status: "canceled" or "expired")
What happens:
- The invoice is cancelled in the invoicing provider
Terminal status. No way back.
PENDING → COMPLETED_OUTSTANDING (payment successful)
Trigger: Payment processor webhook (payment_status: "paid")
Idempotent: Yes - if the order is already COMPLETED_OUTSTANDING or COMPLETED_FINALIZED, nothing happens.
Special case - overdue order: If the order is in REVOKED or DUNNING and has a due_date set (meaning it was revoked by the overdue job - either invoice-style or mandate-based - not by a chargeback), TiruPay first restores the order to PENDING (tax logs REVOKED → PENDING, next_dunning_date cleared) before running the normal completion flow below.
What happens:
- All
PENDINGtax logs →RECEIVED_OUTSTANDING - PAYG balance usages from
BILLED_PENDING→BILLED - Subscription is created (if this is a subscription order and one wasn't already created earlier at
PENDINGtime - see below) - Consent records for active price change groups are created for new subscribers (skipped if already created earlier alongside the subscription)
- Features are activated (unless already activated at
PENDINGtime viaactivate_features_on = pending) due_dateis cleared- Balance top-ups are processed (if articles grant credit)
- The invoice is booked in the invoicing provider
- If a subscription was paused due to the overdue payment, it is unpaused
COMPLETED_OUTSTANDING → COMPLETED_FINALIZED
Trigger: Cron job (finalize_outstanding_orders, runs daily at 01:30 UTC)
Condition: order_date + payment_method.revoke_deadline_days <= today
Meaning: The chargeback window has closed - the payment is irrevocable.
Tax log effect: RECEIVED_OUTSTANDING → RECEIVED_FINALIZED
From this point on, chargebacks are no longer possible. Refunds must go through the invoicing provider.
COMPLETED_OUTSTANDING / COMPLETED_FINALIZED / PARTIALLY_REFUNDED → REFUNDED
Trigger: Admin API call (POST /{order_id}/refund with refund_type: full)
Restriction: Not available for subscription orders.
What happens:
- Features are deactivated and balance top-ups are reversed
- Tax log transitions:
PAID→REFUND_AFTER_PAYMENT_PENDING(already remitted to the tax authority - must be recovered in the next tax payment)PENDING/RECEIVED_OUTSTANDING/RECEIVED_FINALIZED→REFUND_PENDING
- PAYG balance usages from
BILLED/BILLED_PENDING→REFUNDED - Refund is processed according to the chosen
refund_mode(see below) - An
OrderRefundrecord is created for audit purposes - A credit note is created in the invoicing provider
COMPLETED_OUTSTANDING / COMPLETED_FINALIZED / PARTIALLY_REFUNDED → PARTIALLY_REFUNDED / REFUNDED
Trigger: Admin API call (POST /{order_id}/refund with refund_type: position or position_partial)
Restriction: Not available for subscription orders.
What happens:
- Tax log transitions for the affected position:
position: Existing tax logs are set toREFUND_AFTER_PAYMENT_PENDING(ifPAID) orREFUND_PENDINGposition_partial: New negative tax log entries are created for the fractional amount; originals are unchanged
- If
deactivate_featuresis set: all features on the order are deactivated and all balance top-ups are reversed (not just those tied to the refunded position) - Per-position refund guard (using stored
fractionvalues inOrderRefund):position: Rejected if any previous refund exists for this positionposition_partial: Rejected if the sum of already-refunded fractions plus the new fraction would exceed 1
- Order-level remaining-amount check: cumulative refunded gross across all positions must not exceed the order gross
- Refund is processed according to the chosen
refund_mode - An
OrderRefundrecord is created for audit purposes - A credit note is created in the invoicing provider
- Order status becomes
PARTIALLY_REFUNDEDorREFUNDEDdepending on the remaining refundable amount
Refund Modes
The refund_mode parameter controls where the gross refund amount goes:
| Mode | Available for | Description |
|---|---|---|
balance (default) | all types | Gross amount is credited to the customer's Credit Balance |
money | all types | Gross amount is refunded via the original payment provider |
split | full only | The portion originally paid via Credit Balance goes back to the balance; the remainder is refunded via the payment provider |
split is not available for position or position_partial refunds - the per-position balance contribution is not tracked at that granularity.
Credit note booking
If no payment provider refund is needed (balance or a split where the entire amount was covered by balance), the credit note is booked immediately. Otherwise it is booked when the refund_settled webhook arrives from the payment processor.
COMPLETED_OUTSTANDING / COMPLETED_FINALIZED → REVOKED (chargeback)
Trigger: Payment processor webhook (payment_status: "charged_back")
Precondition: Order must not already be REVOKED.
What happens:
- Tax log transitions:
PAID→REVOKED_AFTER_PAYMENT_PENDING(already remitted - must be deducted in the next tax payment)PENDING/RECEIVED_OUTSTANDING/RECEIVED_FINALIZED→REVOKED
- PAYG balance usages from
BILLED/BILLED_PENDING→REVOKED - For non-subscription orders: features are deactivated, balance top-ups are reversed
- For subscription orders: the subscription is paused - features are revoked, subscription enters
PAUSED - Payment status is not touched by TiruPay - the payment processor is the single source of truth
REVOKED / DUNNING → DUNNING / WRITTEN_OFF
Trigger: Daily job, once the order's next_dunning_date (or, for a first-time REVOKED order, immediately) is due.
Precondition: Order must have ext_invoice_id set, and its service must have an active dunning policy with at least one tier - otherwise the order is left untouched.
What happens: The next tier in the service's dunning policy fires - a reminder notice is created at the invoicing provider, an optional fee may be added as a new order position, and next_dunning_date is set for the following tier. If every tier has already fired, the order is written off instead (WRITTEN_OFF) rather than dunned again.
See Dunning for the full escalation model, fee handling, and write-off behavior. Errors are non-blocking.
REVOKED / DUNNING → COMPLETED_OUTSTANDING (reactivation)
Trigger: Manual API call (admin) or after a successful re-payment
Precondition: Order must be in REVOKED or DUNNING.
What happens:
- Tax log transitions:
REVOKED→RECEIVED_OUTSTANDINGREVOKED_AFTER_PAYMENT_PENDING→RECEIVED_FINALIZEDrefund_dateis cleared on affected tax logs
- PAYG balance usages from
REVOKED→BILLED next_dunning_dateis cleared- For non-subscription orders: features are reactivated, balance top-ups are re-applied
- For subscription orders: features are restored
- Consent records for active price change groups are created for the reactivated subscription
FAILED / DUNNING → PENDING (mandate retry)
Trigger: A daily job, or a manual mandate/payment-method update by the customer or admin (PATCH /subscriptions/{id}/mandate, PATCH /balance/items/{id}/mandate)
What happens:
- The order is moved back to
PENDING - For a
DUNNINGorder:next_dunning_dateis cleared (so the invoice-reminder job doesn't also fire a reminder mid-retry) - the existing invoice is preserved, never cancelled or regenerated - A new charge attempt is made via the mandate
- On success: the normal
PENDING → COMPLETED_OUTSTANDINGflow follows - On failure: the order returns to its original status (
FAILEDorDUNNING)
Scheduling difference: the daily job only retries PENDING and FAILED orders - DUNNING is a genuine customer payment default, so blindly retrying it on a schedule makes no sense (nothing about the payment method changed). DUNNING is only retried when a manual mandate/payment-method change suggests the customer or admin is actively trying to fix the problem.
A PENDING order with due_date is also retried automatically
A subscription/PAYG order that stayed PENDING after a decline (see above) is included in the daily job's normal PENDING retry - no manual trigger needed. It's only once the order is actually revoked into DUNNING that automatic retries stop and dunning escalation takes over instead.
Automated Transitions (Jobs)
In addition to webhook-triggered transitions, daily jobs affect orders:
| Job | Description |
|---|---|
| Cancel expired drafts | Cancels DRAFT orders with a customer whose valid_till has passed |
| Delete expired orphaned drafts | Hard-deletes DRAFT orders with no customer (customer_id is NULL) whose valid_till has passed - these never became fiscal records, so they're removed instead of cancelled. All other orders, including cancelled ones, remain undeletable |
| Deactivate ended subscriptions | Terminates subscriptions with an expired cancellation_effective_at (no order status change - subscription only) |
| Revoke overdue orders | Revokes PENDING orders (invoice-style or mandate-based) with a passed due_date + grace_period_days - deactivates features and starts dunning |
| Create dunning reminders | Fires the next dunning tier for REVOKED and DUNNING orders with a past next_dunning_date, or writes the order off if every tier has already fired |
| Renew due subscriptions | Creates a new PENDING renewal order for subscriptions whose current_period_end has passed |
| Retry mandate orders | Retries PENDING and FAILED orders (PAYG and subscription renewals) billed via a mandate - see "FAILED / DUNNING → PENDING" above |
Subscription Renewal
Subscription orders go through the same statuses as regular orders.
plain
Subscription due (current_period_end ≤ now)
↓
Renewal triggered by daily job
→ new order created directly in PENDING
→ payment triggered via mandate
→ webhook → payment confirmed → features activated, new period startsThe renewal order receives the same subscription_id as the original order. If an active price change group exists whose effective_date has not yet been reached, the old price is used for the renewal.
Feature and Balance Side Effects
Summary of which transitions affect features and balances:
| Transition | Features | Balance top-ups | Balance usage (PAYG) |
|---|---|---|---|
| PENDING → COMPLETED_OUTSTANDING | Activated (or recalculated if already active) | Applied | BILLED_PENDING → BILLED |
| PENDING → DRAFT (failed, one-time order) | - | - | BILLED_PENDING → PENDING |
| PENDING → PENDING / FAILED (failed, subscription/PAYG order) | - | - | Unchanged (BILLED_PENDING stays) |
| PENDING → CANCELLED | Deactivated | - | - |
| PENDING → REVOKED (overdue) | Deactivated | - | - |
| COMPLETED_* → REVOKED (chargeback) | Deactivated (non-sub) / paused (sub) | Reversed (non-sub) | BILLED → REVOKED |
| REVOKED / DUNNING → COMPLETED_OUTSTANDING (reactivation) | Reactivated | Re-applied | REVOKED → BILLED |
| COMPLETED_* → REFUNDED | Deactivated | Reversed | BILLED → REFUNDED |
| DUNNING → WRITTEN_OFF | - | - | Never collected again (BILLED_PENDING/PENDING → REVOKED/WAIVED) |
Tax Log Transitions
Tax logs have their own lifecycle, independent of the order status:
plain
PENDING
→ RECEIVED_OUTSTANDING (complete_order)
→ RECEIVED_FINALIZED (COMPLETED_FINALIZED via processor)
→ PAID (process_tax_payment - remitted to tax authority)
→ REVOKED_AFTER_PAYMENT_PENDING (revoke after PAID)
→ REFUND_AFTER_PAYMENT_PENDING (refund after PAID)
→ REVOKED (revoke before PAID)
→ REVOKED_OFFSET (process_tax_payment - offset)
→ REFUND_PENDING (refund before PAID)
→ REFUND_OFFSET (process_tax_payment - offset)
→ CANCELLED (payment_failed)REVOKED_AFTER_PAYMENT_PENDING and REFUND_AFTER_PAYMENT_PENDING arise when tax has already been remitted to the authority and then needs to be recovered via a chargeback or refund. These are offset in the next tax payment run.
Positions Are Immutable After Finalization
Positions can only be modified while the order is in DRAFT. Once the order reaches PENDING or any later status, all positions are locked.
Exception: while an order is NEEDS_MANUAL_CAPTURE, a Service or Admin (not the customer) may still edit positions, as long as the new order total doesn't exceed the amount already reserved with the payment partner. Any resulting Credit Balance surplus is refunded automatically.