Appearance
Orders & Subscriptions
An Order represents a purchase made by a customer. It contains one or more positions, each referencing an article, an extension, or a balance usage. Orders handle pricing, discounts, tax calculation, payment processing, invoicing, and feature activation - all in one flow.
Subscriptions live in a dedicated Subscription entity. Each billing cycle creates a new order linked to that subscription. This gives you full flexibility - pricing, items, and taxes can change between cycles.
Example
A customer subscribes to the "Pro Plan" (monthly, 29.99 €). TiruPay creates the first order. After successful payment, the subscription records the current period and schedules the next renewal. When the renewal date arrives, a new order is created, payment is triggered, and the cycle repeats.
Order Lifecycle
Every order goes through a series of status transitions. The typical flow looks like this:
One-Time Orders
plain
DRAFT → PENDING → COMPLETED_OUTSTANDING → COMPLETED_FINALIZEDSubscription Orders
plain
DRAFT → PENDING → COMPLETED_OUTSTANDING → COMPLETED_FINALIZED
↑ ↓
│ Subscription period advances
│ ↓
└─────────────────── New order created at next renewalSee Order Lifecycle for the full state machine with all transitions, side effects, and edge cases.
All Order Statuses
| 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 - see Capture Modes. |
COMPLETED_OUTSTANDING | Payment received, but can still be withdrawn by the customer. |
COMPLETED_FINALIZED | Fully completed and finalized. |
PARTIALLY_REFUNDED | Partially refunded to the customer. |
REFUNDED | Fully refunded. |
REVOKED | Payment was withdrawn/revoked by the customer, or the order fell overdue and was revoked. |
DUNNING | Dunning is active (payment reminders). |
CANCELLED | Order was cancelled. |
WRITTEN_OFF | Dunning exhausted every configured tier - terminal, no automatic way back. |
Order Fields
| Field | Type | Required | Description |
|---|---|---|---|
order_number | string | auto | Unique, auto-generated per service using the configured order number template |
order_date | datetime | auto | Set when the order transitions to PENDING |
order_status | enum | auto | Current status (see above) |
total_amount | decimal | auto | Sum of all position prices (before discount) |
total_tax | decimal | auto | Total tax calculated on the pre-discount net amount |
total_discount | decimal | auto | Total discount from coupons |
total_amount_after_discount | decimal | auto | Net amount after discounts |
total_tax_after_discount | decimal | auto | Total tax calculated on the post-discount net amount (actual tax charged) |
gross_price | decimal | auto | Gross amount after discounts: total_amount_after_discount + total_tax_after_discount |
gross_price_before_discount | decimal | auto | Gross amount before discounts: total_amount + total_tax |
valid_till | datetime | auto | Expiration date for draft orders. Defaults to 14 days after creation. Expired drafts are automatically cancelled. |
currency_code | string | auto | ISO 4217 currency code, snapshotted at order creation. For subscription renewals, inherited from the subscription (e.g. EUR, CHF, GBP) |
customer_id | string | conditional | The customer placing the order. Required unless country_code is set instead - see Draft Orders Without a Customer. Always required by the time the order is finalized. |
country_code | string | conditional | Tax-country override for the order, taking precedence over the customer's own country. Required if customer_id is not set. |
tax_country | object | auto | Country the order is taxed in (country_code, name, flag, currency_code): the country_code override if set, otherwise the paying customer's country |
paying_customer_id | string | no | Another customer of the same service who pays the order. Responses show it as paying_customer. See Paying Customer. |
service_id | string | yes | The service this order belongs to |
start_trial | boolean | no | Start a Trial of the order's subscription article instead of a purchase. The order then costs nothing. Only on create; responses show it as is_trial (default: false) |
trial_duration_value / trial_duration_unit | integer / enum | no | Trial length for this order, overriding the article's. Only with start_trial |
Net vs. Gross
All total_* amounts on the order are net (before tax), except the tax totals themselves. gross_price is the gross amount (total_amount_after_discount + total_tax_after_discount), the amount the customer actually pays. gross_price_before_discount is the same without any discount applied.
total_tax reflects the tax on the original price before any discount was applied. This can differ from total_tax_after_discount when a coupon is used.
Currency
The order's currency_code is snapshotted at creation and cannot change afterwards. For subscription renewals, the currency is inherited from the subscription, which fixes it at the time of the first order.
Draft Orders Without a Customer
Admin and Service accounts can create a DRAFT order before a customer is known, by setting country_code instead of customer_id - useful when the customer's identity is resolved later but the order's tax jurisdiction is already known. This is not available to the User role, which always creates an order for its own linked customer.
Positions can be added to a country-only draft order the same way as any other draft - pricing and tax are resolved against country_code. A customer without a company_tax_exempt flag set is treated as not tax-exempt.
Two endpoints complete such an order:
PATCH /orders/{id}/customer- links a customer to the order. Anycountry_codeoverride already set is kept as-is, not replaced by the customer's own country.PATCH /orders/{id}/country- changes the order's tax-country override.
Both reprice existing positions against the resulting country and are only available while the order is in DRAFT. A customer must be linked before the order can be finalized.
Coupons vs. Referral Codes on a Customer-Less Order
A coupon can be applied to a country-only draft order right away. A referral code cannot - it's queued instead, and only takes effect once PATCH /orders/{id}/customer links a customer. See Applying a Referral Code Before a Customer Is Known.
Order Positions
Each order contains one or more positions. A position references exactly one of:
- An Article - a purchasable product or subscription plan
- An Article Extension - an add-on to a subscription
- A Balance Usage - a pay-as-you-go or prepaid charge
Position Fields
| Field | Type | Description |
|---|---|---|
quantity | decimal | Number of units |
unit_price | decimal | Price per unit (auto-fetched from article if not provided) |
unit_price_after_trial | decimal | Trial orders only: price per unit once the Trial continues as a paid plan. Empty for the article's price when the Trial starts |
total_price | decimal | quantity × unit_price |
discount_amount | decimal | Discount applied from coupons |
total_price_after_discount | decimal | total_price - discount_amount |
sort_order | integer | Position in the order |
overwrite_name | string | Optional: override the article's name on the invoice |
overwrite_description | string | Optional: override the article's description on the invoice |
Positions Are Immutable After Finalization
You can add, update, and remove positions while the order is in DRAFT status. Once the order is finalized (status PENDING or later), 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.
Subscriptions
Subscriptions are managed as a dedicated resource. See Subscriptions for the full lifecycle, statuses, upgrade/downgrade, cancellation, and termination.
Each subscription order carries a subscription_id linking it to its parent Subscription. The subscription tracks the current billing period, cancellation state, and pending plan changes independently of individual orders.
What Happens When an Order Completes
When a payment is confirmed and the order transitions to COMPLETED_OUTSTANDING, several things happen automatically:
- Features are activated - Feature logs are created and the customer's feature assignments are recalculated. Each activated feature is tracked as an immutable Feature Log entry with a
granted_attimestamp, creating a complete audit trail. - Balances are topped up - If the purchased articles grant balance top-ups, the customer's balance is updated.
- Subscription is created - For subscription orders, a Subscription record is created and linked to the order.
For a service configured with activate_features_on = pending (see Payments), features and, for a first-time subscription order, the Subscription itself are already created earlier, when the order was finalized to PENDING - completion then skips creating them again.
Activation
Admins can also manually complete a PENDING order without waiting for a payment webhook.
Tax Handling
Taxes are calculated based on the order's country - its own country_code if set, otherwise the customer's country - and attached to each order position individually.
- Tax is calculated on the
total_price_after_discountof each position. - Each position gets a tax entry tracking the tax rate, tax value, and payment status.
- Tax entries follow their own lifecycle (pending → received → paid to authority) independently of the order.
See Taxation for more details on how tax rates are determined.
Revocation & Refund
Revoke
When a customer revokes a payment (e.g. credit card chargeback):
- All features from the order are deactivated.
- Balance top-ups are reversed.
- The order enters the dunning process.
- For subscriptions, the subscription is paused.
Reactivation
A revoked order can be reactivated if the customer pays again - features and balances are restored.
Refund
Refunds are admin-only. Every refund is kept as its own record for a full audit trail. Three refund types are available:
| Type | Description |
|---|---|
full (default) | Refunds the entire order amount. Not available for subscription orders. |
position | Refunds a single order position in full (order_position_id required). |
position_partial | Refunds a fraction of a position (order_position_id + fraction required; 0 < fraction ≤ 1, max 4 decimal places). |
Subscription refunds (upgrade / termination pro-rata credits) are system-initiated and always go to the Credit Balance.
After one or more partial refunds the order enters PARTIALLY_REFUNDED. Once the cumulative refunded amount equals the order gross, the order moves to REFUNDED.
Two levels of guards prevent over-refunding:
- Per-position: A
positionrefund is rejected if any previous refund already exists for that position. Aposition_partialrefund is rejected if the cumulative refunded amount for that position would exceed its gross. - Order-level: Any refund is rejected if the cumulative refunded gross across all positions would exceed the order gross.
Refund Modes
The refund_mode parameter controls where the refunded amount goes:
| Mode | Available for | Description |
|---|---|---|
balance (default) | all types | Gross amount credited to the customer's Credit Balance |
money | all types | Gross amount refunded via the original payment provider |
split | full only | Portion originally paid via Credit Balance goes back to the balance; remainder refunded via payment provider |
split not available for position refunds
split requires knowing how much of the original payment was covered by Credit Balance per position, which is not tracked at that granularity. Use balance or money for position and position_partial refunds.
Feature Deactivation
The optional deactivate_features flag (available for position and position_partial) deactivates all features on the order and reverses all balance top-ups - not just those tied to the refunded position.
For full refunds, features are always deactivated automatically.
In all cases a credit note is created in the invoicing provider per refund event.
Automated Jobs
TiruPay runs scheduled jobs to manage orders and subscriptions:
| Job | Schedule | Description |
|---|---|---|
| Cancel expired drafts | Daily | Cancels DRAFT orders past their valid_till date |
| Deactivate ended subscriptions | Daily | Ends features for subscriptions marked ENDED_AFTER_PERIOD once the scheduled date has passed |
| PAYG billing | Monthly (1st) | Creates billing orders for pay-as-you-go balances with pending usage |
| Revoke overdue orders | Daily | Revokes PENDING orders (invoice-style or mandate-based) past their due_date + grace period |
| Dunning reminders | Daily | Fires the next dunning tier for overdue orders, or writes them off once every tier has fired |
User Checkout
Users can (and in most cases should) create and finalize their own orders. This supports two flows:
Direct TiruPay Flow
The user creates and pays for an order directly in the TiruPay frontend:
- User creates an order via
POST /user/orders/(restricted schema: noorder_numberorvalid_till). - User finalizes the order via
POST /user/orders/{id}/finalizewith payment selection data. - Safe defaults are used:
self_hosted_checkout,automaticcapture, and the TiruPayfrontend_urlas fallback redirect.
Service-Initiated Flow
A service creates the order and hands the user off to TiruPay for payment:
- Service creates the order via
POST /service/orders/. - Service creates a checkout session via
POST /service/orders/{id}/checkout-session, specifyingcheckout_mode,capture_mode, andfinal_redirect_url. - The response includes a
checkout_url- the service redirects the user there. - User finalizes the order via
POST /user/orders/{id}/finalizewith thecheckout_session_idfrom the URL. - TiruPay reads the service-controlled parameters from the session.
Checkout Sessions
Checkout sessions are valid for 1 hour. After the order is finalized, the session is simply ignored (the order is no longer in DRAFT status).
User Payment Selection
When finalizing, users provide a restricted set of payment fields. The following fields are excluded because they are controlled by the service or TiruPay:
| Field | Where it comes from |
|---|---|
checkout_mode | Checkout session or default (self_hosted_checkout) |
capture_mode | Checkout session or default (automatic) - see Capture Modes |
final_redirect_url | Checkout session or default (frontend_url) |
The user can set: partner, payment_method_id, partner_mandate_id, mollie_card_token, SEPA/PayPal mandate creation fields, and expected_gross_amount (required when someone else pays).
User Order Positions
Users can only order catalog items at catalog prices. When creating an order (items) or adding a position, a user sends article_id or article_extension_id, quantity (greater than 0) and sort_order. When updating a position, only quantity and sort_order can be changed.
Any other field, such as unit_price, unit_price_after_trial, tax_category_id or overwrite_name, is rejected with 422. Set custom prices from your service before handing the order to the user.
Good to know
Order Numbers
Order numbers are auto-generated using the template configured on the service. You can customize the format and set a starting sequence number.
Draft Expiration
Orders default to a 14-day expiration (valid_till). Expired drafts are cleaned up daily by a scheduled job.
User View
Users see a simplified view of orders, scoped to their own customer account. Service and Admin roles see the full details, scoped to their own service(s).
Relationships
- Customers - Orders usually belong to a customer; an Admin/Service-created draft order can start without one, using a country override instead.
- Paying Customer - Another customer can pay the order.
- Articles - Order positions reference articles and extensions.
- Balances - Orders can trigger balance top-ups and reference balance usage.
- Coupons - A coupon can be applied per order for discounts.
- Payments - Each order has one or more payment attempts.
- Taxation - Tax is tracked per position per country.
- Invoicing - Invoices, credit notes, and dunning notices are linked to orders.
- Dunning - Revoked orders escalate through a service's dunning policy, potentially adding fee positions and ending in
WRITTEN_OFF.