Skip to content

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_FINALIZED

Subscription Orders ​

plain
DRAFT → PENDING → COMPLETED_OUTSTANDING → COMPLETED_FINALIZED
            ↑                                       ↓
            │                       Subscription period advances
            │                                       ↓
            └─────────────────── New order created at next renewal

See Order Lifecycle for the full state machine with all transitions, side effects, and edge cases.

All Order Statuses ​

StatusDescription
DRAFTCreated but not yet finalized. Positions can still be modified.
PENDINGFinalized and awaiting payment.
NEEDS_MANUAL_CAPTUREPayment authorized/reserved; awaiting a Service/Admin to confirm or cancel the capture. Only reached with capture_mode: manual - see Capture Modes.
COMPLETED_OUTSTANDINGPayment received, but can still be withdrawn by the customer.
COMPLETED_FINALIZEDFully completed and finalized.
PARTIALLY_REFUNDEDPartially refunded to the customer.
REFUNDEDFully refunded.
REVOKEDPayment was withdrawn/revoked by the customer, or the order fell overdue and was revoked.
DUNNINGDunning is active (payment reminders).
CANCELLEDOrder was cancelled.
WRITTEN_OFFDunning exhausted every configured tier - terminal, no automatic way back.

Order Fields ​

FieldTypeRequiredDescription
order_numberstringautoUnique, auto-generated per service using the configured order number template
order_datedatetimeautoSet when the order transitions to PENDING
order_statusenumautoCurrent status (see above)
total_amountdecimalautoSum of all position prices (before discount)
total_taxdecimalautoTotal tax calculated on the pre-discount net amount
total_discountdecimalautoTotal discount from coupons
total_amount_after_discountdecimalautoNet amount after discounts
total_tax_after_discountdecimalautoTotal tax calculated on the post-discount net amount (actual tax charged)
gross_pricedecimalautoGross amount after discounts: total_amount_after_discount + total_tax_after_discount
gross_price_before_discountdecimalautoGross amount before discounts: total_amount + total_tax
valid_tilldatetimeautoExpiration date for draft orders. Defaults to 14 days after creation. Expired drafts are automatically cancelled.
currency_codestringautoISO 4217 currency code, snapshotted at order creation. For subscription renewals, inherited from the subscription (e.g. EUR, CHF, GBP)
customer_idstringconditionalThe 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_codestringconditionalTax-country override for the order, taking precedence over the customer's own country. Required if customer_id is not set.
tax_countryobjectautoCountry 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_idstringnoAnother customer of the same service who pays the order. Responses show it as paying_customer. See Paying Customer.
service_idstringyesThe service this order belongs to
start_trialbooleannoStart 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_unitinteger / enumnoTrial 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. Any country_code override 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:

Position Fields ​

FieldTypeDescription
quantitydecimalNumber of units
unit_pricedecimalPrice per unit (auto-fetched from article if not provided)
unit_price_after_trialdecimalTrial orders only: price per unit once the Trial continues as a paid plan. Empty for the article's price when the Trial starts
total_pricedecimalquantity × unit_price
discount_amountdecimalDiscount applied from coupons
total_price_after_discountdecimaltotal_price - discount_amount
sort_orderintegerPosition in the order
overwrite_namestringOptional: override the article's name on the invoice
overwrite_descriptionstringOptional: 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:

  1. 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_at timestamp, creating a complete audit trail.
  2. Balances are topped up - If the purchased articles grant balance top-ups, the customer's balance is updated.
  3. 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_discount of 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:

TypeDescription
full (default)Refunds the entire order amount. Not available for subscription orders.
positionRefunds a single order position in full (order_position_id required).
position_partialRefunds 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 position refund is rejected if any previous refund already exists for that position. A position_partial refund 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:

ModeAvailable forDescription
balance (default)all typesGross amount credited to the customer's Credit Balance
moneyall typesGross amount refunded via the original payment provider
splitfull onlyPortion 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:

JobScheduleDescription
Cancel expired draftsDailyCancels DRAFT orders past their valid_till date
Deactivate ended subscriptionsDailyEnds features for subscriptions marked ENDED_AFTER_PERIOD once the scheduled date has passed
PAYG billingMonthly (1st)Creates billing orders for pay-as-you-go balances with pending usage
Revoke overdue ordersDailyRevokes PENDING orders (invoice-style or mandate-based) past their due_date + grace period
Dunning remindersDailyFires 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:

  1. User creates an order via POST /user/orders/ (restricted schema: no order_number or valid_till).
  2. User finalizes the order via POST /user/orders/{id}/finalize with payment selection data.
  3. Safe defaults are used: self_hosted_checkout, automatic capture, and the TiruPay frontend_url as fallback redirect.

Service-Initiated Flow ​

A service creates the order and hands the user off to TiruPay for payment:

  1. Service creates the order via POST /service/orders/.
  2. Service creates a checkout session via POST /service/orders/{id}/checkout-session, specifying checkout_mode, capture_mode, and final_redirect_url.
  3. The response includes a checkout_url - the service redirects the user there.
  4. User finalizes the order via POST /user/orders/{id}/finalize with the checkout_session_id from the URL.
  5. 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:

FieldWhere it comes from
checkout_modeCheckout session or default (self_hosted_checkout)
capture_modeCheckout session or default (automatic) - see Capture Modes
final_redirect_urlCheckout 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.