Skip to content

Taxation ​

TiruPay handles tax calculation, tracking, and authority payment reporting. Taxes are determined by the order's country - normally the customer's country, or an order-level override for draft orders created without a customer - and applied per order position.

Countries ​

A country defines a tax jurisdiction. Each country has a name, an ISO 3166-1 alpha-2 code (e.g. DE, AT, CH), a currency, and one or more tax categories.

Every customer is assigned a country, which determines the tax rate applied to their orders. Currency is resolved separately when the order is created.

Currency ​

Currency is its own reference-data model: a Currency is simply an ISO 4217 code (e.g. EUR, CHF, GBP) that must exist in the currency table before anything can reference it.

Each country has a currency_code field pointing to one of these currencies. This field defines the country's default currency and is used when a service falls back to its invoicing country's currency.

The default currency is EUR. Update it for countries where a different currency applies (e.g. CHF for Switzerland, GBP for Great Britain).

Currency flows through the system

ArticleAvailability.currency (if set) → Order.currency_code (snapshotted at creation) → Subscription.currency_code (snapshotted from first order)

If no ArticleAvailability.currency is set, Order.currency_code falls back to the service's invoicing country's Country.currency_code.

Once an order is created, its currency is fixed. For subscription renewals, the currency is inherited from the subscription - changing an article availability or country's currency later does not affect running subscriptions.

Currency Fields ​

FieldTypeRequiredDescription
currency_codestringyesISO 4217 currency code (e.g. EUR, CHF, GBP). Primary key.
symbolstringnoCurrency symbol (e.g. €, $, £).

Tax Categories ​

A tax category represents a specific tax rate within a country. Countries typically have multiple categories for different types of goods or services.

FieldTypeRequiredDescription
namestringyesName of the tax category (e.g. "Regelsteuersatz")
taxfloatyesTax rate as percentage (e.g. 19.0 for 19%)
descriptionstringnoDescription
country_codestringyesThe country this tax category belongs to

Default Tax Rates ​

TiruPay comes with default tax categories for Germany, Austria, and Switzerland:

CountryCategoryRate
Germany (DE)Regelsteuersatz19%
Germany (DE)Ermäßigter Steuersatz7%
Germany (DE)Steuerfrei0%
Austria (AT)Normalsteuersatz20%
Austria (AT)Ermäßigter Steuersatz10%
Austria (AT)Reduzierter Steuersatz13%
Austria (AT)Steuerfrei0%
Switzerland (CH)Normalsatz8.1%
Switzerland (CH)Reduzierter Satz2.6%
Switzerland (CH)Sondersatz Beherbergung3.8%
Switzerland (CH)Steuerfrei0%

You can create additional countries and tax categories as needed.

How Tax is Calculated ​

When an order is finalized, TiruPay calculates the tax for each position:

  1. Resolve the order's country - its own override if set, otherwise the customer's country.
  2. Find the tax category for that country.
  3. For each position: tax = total_price_after_discount × (tax_rate / 100)
  4. Round to 2 decimal places.
  5. Store the tax rate and value as a snapshot on the order position.

A customer-less draft order is treated as not tax-exempt (company_tax_exempt lives on the customer) until a customer is linked.

Tax is always calculated on the discounted price. For reference, each order position also stores total_tax_before_discount - the hypothetical tax on the undiscounted price. This value is informational only and is never used for payment calculations.

Snapshot Values

The tax rate and tax value are captured at the time of purchase. If the tax rate for a country changes later, existing orders are not affected.

Rounding on Gross-Priced Articles ​

When an availability is priced with gross_price, its net price is derived from the gross price, and the two do not always add back up. A 9.99 gross price at 19% is 8.394958 net, which taxes to 1.60 - a total of 9.994958, half a cent over what the customer is charged.

The system absorbs that gap into the tax rather than the price: the difference is recorded on the tax entry as rounding_error and already deducted from tax_value, so net price plus tax always matches the gross price the customer actually paid. The value is signed - positive when net plus tax overshoots the gross price, negative when it falls short - and is always 0 for net-priced articles.

On the electronic invoice, the VAT breakdown shows the uncorrected tax and the gap is disclosed separately as the document's rounding amount, so the grand total still matches what the customer pays. SevDesk documents show gross position prices, so their total matches the paid amount as well.

Article Availability ​

Article Availability links articles and extensions to countries. This serves two purposes:

  1. Tax classification: Assign a specific tax category to an article per country (e.g. reduced rate for books in Germany).
  2. Country-specific pricing: Optionally override the article's default price for a specific country.
FieldTypeRequiredDescription
article_idstringconditionalThe article (exclusive with article_extension_id)
article_extension_idstringconditionalThe extension (exclusive with article_id)
tax_category_idstringyesWhich tax category applies
country_codestringautoDerived from the tax category's country
net_pricedecimalnoCountry-specific net price override in the country's currency. At most one of net_price/gross_price may be set. If neither is set, the article's default price is used.
gross_pricedecimalnoCountry-specific gross (tax-included) price override in the country's currency. At most one of net_price/gross_price may be set.

Price Changes

We recommend using the Scheduled Price Changes feature to update article availability prices, rather than updating the net_price/gross_price fields directly. This ensures proper handling of existing subscriptions and customer notifications. When you update the price of an article availability directly, it only affects new purchases. Existing subscriptions that reference that article availability keep their original price.

Net and gross are always both returned

Unlike the base article, an availability has a resolvable tax rate (via tax_category_id), so both net_price and gross_price are always present in the response - whichever wasn't the stored override (or, if there's no override at all, whichever wasn't the parent article's price) is derived live using this availability's tax rate.

Changing an article's mode (net ↔ gross) does not affect availabilities that already have their own price override - those are resolved independently of the parent.

Deleting an availability cancels affected subscriptions

If an article or extension has no remaining availability for a country, it's no longer purchasable or renewable there. Deleting the availability for an article/extension + country combination automatically cancels any active or paused subscriptions held by customers in that country for that article/extension - the same way a customer-initiated cancellation works, respecting the current billing period and minimum term. The same thing happens if a customer's country is changed to one with no availability for an article/extension they're subscribed to.

Payment Method Availability ​

Each article availability can specify which payment methods are allowed for that article in that country. You explicitly add the payment methods that should be available.

FieldTypeDescription
article_availability_idstringThe article availability this belongs to
payment_method_idstringThe allowed payment method
is_enabledbooleanWhether this payment method is currently active (default: true)

No Payment Methods

If no payment methods are defined and enabled for an article availability, this article is not purchasable in that country. Make sure to add at least one active payment method for each article availability.

Unique Combinations

Each payment method can only be added once per article availability. Adding the same payment method again will fail with a uniqueness constraint.

Service Must Activate the Payment Method First

A payment method can only be linked to an article availability if the owning service has already activated it via ServicePaymentMethodConfig for the matching order type - subscription if the article is a subscription article (or an extension of one), one_time otherwise. Linking a payment method that isn't activated for the service returns a 404.

Managing Availabilities in Bulk ​

Selling in many countries (e.g. the whole EEA) means one availability per article/extension and country. Two admin endpoints handle this without one request per availability:

EndpointDescription
GET /admin/tax/availability-coverage?service_id=All articles and extensions of the service (extensions directly after their article), their availabilities with the enabled payment method IDs, the payment methods the service has activated per order type, all countries and tax categories, and per country the number of customers and active customers (running subscription or paid order within active_customer_window_days)
POST /admin/tax/availabilities/batchApplies up to 2000 upserts and deletes in one transaction

Each operation names one of article_id/article_extension_id plus a country_code. An upsert:

  • creates the availability if it doesn't exist yet. tax_category_id is required and must belong to country_code.
  • sets the price of a new availability: either its own net_price or gross_price (at most one) with an optional currency, or neither to inherit the article's or extension's base price. A currency other than the service's base currency (base_currency in the coverage response) requires an own price, so a base price of 20 is never charged as 20 of another currency.
  • leaves the tax category, price and currency of an existing availability unchanged. If different ones were sent, the availability is listed in kept_tax_category or kept_price. Use a price change to change them.
  • if payment_method_ids is given, makes it the exact set of enabled payment methods: listed methods are enabled, all others disabled. Leave it out to keep the current payment methods.

Deleting a missing availability is a no-op. The response counts created, updated, deleted and unchanged operations.

All or nothing

Every operation is validated first. If any is invalid, nothing is applied: the response has applied: false and lists each problem in errors, with the operation's list (upsert/delete) and position.

Preview deletions with dry_run=true

Deleting availabilities cancels subscriptions (see above). Send the batch with ?dry_run=true first: it validates and counts everything, including affected_subscriptions, without applying anything.

Extensions are only offered where their article is sold, and only with payment methods both offer. All items of an order share one currency, so an extension must also be sold in the same currency as its article in each country. Keep an extension's countries, currency and payment methods in line with its article; the coverage endpoint gives you everything needed to compare them.

Tax Tracking ​

Every tax amount is tracked individually via Order Position Tax entries. Each entry records the tax rate, calculated value, and a status that follows the full lifecycle from creation to payment to the tax authority.

Tax Statuses ​

StatusDescription
PENDINGTax calculated but order not yet paid
RECEIVED_OUTSTANDINGPayment received from customer, can still be withdrawn
RECEIVED_FINALIZEDPayment received and finalized
PAIDTax has been paid to the tax authority
CANCELLEDOrder was cancelled before payment
REFUND_PENDINGA full order was refunded/cancelled before its tax was ever paid to the authority - zero financial effect, nothing to offset
REFUND_OFFSETREFUND_PENDING closed out by a tax payment run - still zero financial effect
REFUND_PARTIAL_PENDINGA partial refund created a separate negative delta row netting against a still-outstanding original row that was never paid to the authority - a real credit
REFUND_PARTIAL_OFFSETREFUND_PARTIAL_PENDING reconciled in a tax payment - real credit
REFUND_AFTER_PAYMENT_PENDINGA full refund initiated after tax was already paid to authority - real credit
REFUND_AFTER_PAYMENT_OFFSETREFUND_AFTER_PAYMENT_PENDING reconciled in a tax payment - real credit
REFUND_PARTIAL_AFTER_PAYMENT_PENDINGA partial refund's delta row netting against an original row whose tax was already paid to authority - real credit
REFUND_PARTIAL_AFTER_PAYMENT_OFFSETREFUND_PARTIAL_AFTER_PAYMENT_PENDING reconciled in a tax payment - real credit
WITHDRAWAL_PENDINGCustomer exercised their statutory withdrawal right before tax was paid to authority - zero financial effect
WITHDRAWAL_OFFSETWITHDRAWAL_PENDING closed out by a tax payment run - still zero financial effect
WITHDRAWAL_AFTER_PAYMENT_PENDINGWithdrawal after tax was already paid to authority - real credit
WITHDRAWAL_AFTER_PAYMENT_OFFSETWithdrawal reconciled in a tax payment (tax was already paid to authority) - real credit
REVOKEDCustomer revoked payment before tax was paid to authority - zero financial effect
REVOKED_OFFSETRevocation reconciled in a tax payment - still zero financial effect
REVOKED_AFTER_PAYMENT_PENDINGCustomer revoked after tax was paid to authority - real credit
REVOKED_AFTER_PAYMENT_OFFSETRevocation after payment, reconciled - real credit

"Pending"/"Offset" statuses do not always mean money changed hands

REFUND_PENDING, WITHDRAWAL_PENDING, and REVOKED (and their _OFFSET counterparts) mean an order's tax was cancelled before it was ever paid to the tax authority - there is nothing to reclaim, so these never reduce a tax authority payment. Only the _AFTER_PAYMENT_* variants and REFUND_PARTIAL_* represent tax that was actually collected from (or is still owed alongside) a real payment, and only those are subtracted when calculating or processing a payment.

Normal Flow ​

plain
PENDING → RECEIVED_OUTSTANDING → RECEIVED_FINALIZED → PAID

Refund Flow ​

If a full refund happens before tax was paid to the authority, the existing tax log is mutated in place - no money was ever collected, so nothing is offset:

plain
RECEIVED_* → REFUND_PENDING → REFUND_OFFSET

If a partial refund happens, the original tax log is left untouched (it's still owed) and a separate row is created for just the refunded portion - this is a real credit. Which status the delta row gets depends on whether the original row's tax was already paid to the authority:

plain
RECEIVED_* (unchanged)  +  REFUND_PARTIAL_PENDING → REFUND_PARTIAL_OFFSET
PAID (unchanged)        +  REFUND_PARTIAL_AFTER_PAYMENT_PENDING → REFUND_PARTIAL_AFTER_PAYMENT_OFFSET

If a full refund happens after tax was already paid:

plain
PAID → REFUND_AFTER_PAYMENT_PENDING → REFUND_AFTER_PAYMENT_OFFSET

Only REFUND_PARTIAL_*, REFUND_PARTIAL_AFTER_PAYMENT_*, and REFUND_AFTER_PAYMENT_* amounts are subtracted from the next tax authority payment - REFUND_PENDING/REFUND_OFFSET never are, since no tax was ever paid in the first place.

Withdrawal Flow ​

Triggered when a customer exercises their statutory right of withdrawal (Widerrufsrecht). Same shape as the refund flow, but without a partial variant - a withdrawal always reverses the full order:

plain
RECEIVED_* → WITHDRAWAL_PENDING → WITHDRAWAL_OFFSET
PAID → WITHDRAWAL_AFTER_PAYMENT_PENDING → WITHDRAWAL_AFTER_PAYMENT_OFFSET

As with refunds, only the _AFTER_PAYMENT_* amount is a real credit - WITHDRAWAL_PENDING/WITHDRAWAL_OFFSET closes out with zero financial effect.

Revocation Flow ​

Same logic as refunds, but triggered by a customer chargeback:

plain
RECEIVED_* → REVOKED → REVOKED_OFFSET
PAID → REVOKED_AFTER_PAYMENT_PENDING → REVOKED_AFTER_PAYMENT_OFFSET

A revoked order can be reactivated if the customer pays again, which reverses the tax status back to RECEIVED_OUTSTANDING or RECEIVED_FINALIZED.

Tax Authority Payments ​

TiruPay tracks how much tax needs to be paid to each country's tax authority. All operations are available under the /tax endpoints.

All operations support the following filters:

FilterDescription
service_idsRestrict to specific services (services are limited to their own)
country_codesRestrict to specific countries - useful for paying one country at a time
tax_category_idsRestrict to specific tax categories
invoice_date_from / invoice_date_toRestrict to a specific invoice date range

Calculate Next Payment ​

A read-only helper that returns a preview of the net amount currently owed, grouped by country. Useful for dashboards or pre-checks, but does not mark anything as paid.

  • taxes_to_pay: Sum of RECEIVED_OUTSTANDING + RECEIVED_FINALIZED (taxes collected)
  • credits_to_offset: Sum of REFUND_AFTER_PAYMENT_PENDING, REFUND_PARTIAL_AFTER_PAYMENT_PENDING, WITHDRAWAL_AFTER_PAYMENT_PENDING, REVOKED_AFTER_PAYMENT_PENDING, and REFUND_PARTIAL_PENDING - i.e. only rows representing real money (already paid to the authority, or a partial-refund credit against a still-outstanding original). REFUND_PENDING, WITHDRAWAL_PENDING, and REVOKED are excluded entirely - they represent tax that was cancelled before ever being paid, so there is nothing to offset.
  • net_payment = taxes_to_pay − credits_to_offset

Snapshot, not a commitment

The amount returned by Calculate is a point-in-time snapshot. Between calling Calculate and actually paying, new tax logs may arrive (e.g. from completed orders). Process Payment will include those newer entries and may therefore return a different total.

Process Payment ​

The operation to use when actually settling taxes with the authority. It calculates the net amount (same logic as Calculate) and atomically marks all included entries as paid in a single step - so nothing is missed or double-counted.

  • RECEIVED_OUTSTANDING / RECEIVED_FINALIZED → PAID
  • REFUND_PENDING → REFUND_OFFSET, WITHDRAWAL_PENDING → WITHDRAWAL_OFFSET, REVOKED → REVOKED_OFFSET - closed out, but zero financial effect (never counted in net_payment)
  • REFUND_PARTIAL_PENDING → REFUND_PARTIAL_OFFSET - real credit
  • REFUND_AFTER_PAYMENT_PENDING / REFUND_PARTIAL_AFTER_PAYMENT_PENDING / WITHDRAWAL_AFTER_PAYMENT_PENDING / REVOKED_AFTER_PAYMENT_PENDING → their respective _OFFSET - real credit

Every entry that gets touched (including the zero-effect ones) is closed out to a terminal status and recorded in the batch - a payment run always leaves every row it processed in a clean, final state, whether or not it moved any money.

Every Process Payment call creates a Tax Payment Batch record that logs who triggered the processing, when, and which filters were applied. This ensures a full audit trail from collection through authority payment.

Payment History ​

GET /tax/history returns all processed tax entries (PAID, REFUND_OFFSET, REFUND_PARTIAL_OFFSET, REFUND_AFTER_PAYMENT_OFFSET, REFUND_PARTIAL_AFTER_PAYMENT_OFFSET, WITHDRAWAL_OFFSET, WITHDRAWAL_AFTER_PAYMENT_OFFSET, REVOKED_OFFSET, REVOKED_AFTER_PAYMENT_OFFSET), grouped by country with aggregated totals:

  • total_paid - sum of all PAID entries
  • total_offset - sum of all REFUND_PARTIAL_OFFSET, REFUND_AFTER_PAYMENT_OFFSET, REFUND_PARTIAL_AFTER_PAYMENT_OFFSET, WITHDRAWAL_AFTER_PAYMENT_OFFSET, REVOKED_AFTER_PAYMENT_OFFSET entries (real credits). Zero-effect closures (REFUND_OFFSET, WITHDRAWAL_OFFSET, REVOKED_OFFSET) still appear in the entry list for the audit trail but are not summed into total_offset.

Supports the same filters as Calculate and Process.

Export ​

POST /tax/export enqueues a background job that generates a report from current tax data and stores it as a file. Returns a job_id immediately (HTTP 202) - poll GET /jobs/{job_id} for status, then download the file via the files endpoint once the job completes.

ParameterDescription
export_formatcsv (default), excel, or html
file_service_idThe service the exported file is stored under
sort_bySort summary by country, net_payment, or taxes_to_pay
sort_orderasc (default) or desc
mark_as_processedtrue to process exactly the exported entries once the file is stored, in the same step. Admin only, needs write access to every exported service. Default false

Use mark_as_processed instead of calling Process Payment after the download: Process Payment selects entries by filter again and can include entries that arrived after the export.

CSV exports contain detail rows (one per tax log). Excel exports have two sheets: Summary (one row per country) and Details (one row per tax log). HTML exports render both as tables.

Every detail row includes the raw status value plus a has_financial_effect boolean, so you can tell at a glance whether a row represents real money movement (PAID, any _AFTER_PAYMENT_*, any _PARTIAL_*) or a zero-effect closure (PENDING, CANCELLED, REFUND_PENDING/REFUND_OFFSET, WITHDRAWAL_PENDING/WITHDRAWAL_OFFSET, REVOKED/REVOKED_OFFSET) - tax that was cancelled before it was ever paid to the authority. No rows are filtered out of the export; this field just disambiguates them.

Good to know ​

Tax on Discounted Price

Coupons reduce the taxable amount. A 20% discount on a 100.00 € article means tax is calculated on 80.00 €, not 100.00 €.

Multiple Tax Categories Per Country

Countries can have multiple tax categories (e.g. standard, reduced, zero). Use article availabilities to assign the correct category per article and country.

Tax Authority Payment Is Manual

TiruPay calculates and tracks what's owed, but the actual payment to the tax authority happens outside of TiruPay. Always use Process Payment when settling - it returns the definitive amounts and marks entries as paid in one atomic step.

Process Payment is Admin-only

A Service account can Calculate a preview, view History, and Export, but only an Admin account can call Process Payment to actually settle taxes with the authority.

Relationships ​

  • Countries - Define tax jurisdictions with tax categories.
  • Customers - Each customer has a country that determines their tax rate.
  • Orders - Tax is calculated and tracked per order position.
  • Articles - Article availability links articles to countries and tax categories.
  • Coupons - Discounts are applied before tax calculation.