Appearance
Coupons
A Coupon provides a discount on orders. Coupons can be percentage-based or fixed-amount, and can be restricted to specific articles, limited by usage count, or set to recur on subscription renewals.
Only one coupon can be applied per order.
Example
You create a coupon WELCOME20 that gives 20% off the first order. A customer applies it to their "Pro Plan" subscription (29.99 €/month) and gets 6.00 € off. Since it's marked as first_order_only, the same customer cannot use it again.
Coupon Types
| Type | Description | Example |
|---|---|---|
PERCENTAGE | Discount as a percentage of the position price | 20% off → 29.99 € becomes 23.99 € |
AMOUNT | Fixed discount amount distributed across positions | 10.00 € off a 50.00 € order |
How Fixed-Amount Discounts Work
A fixed-amount coupon distributes the discount proportionally across all applicable positions based on their price ratio. This ensures each position's discount is fair relative to its price.
Example
A coupon gives 10.00 € off. The order has two applicable positions: Article A (30.00 €) and Article B (20.00 €). Article A gets 6.00 € off (30/50 × 10) and Article B gets 4.00 € off (20/50 × 10).
Gross vs. Net Discount Amounts
Order positions are always priced net of tax, so discount_amount is interpreted as a net amount by default. Set discount_amount_is_gross to true if the amount should instead be interpreted as gross (tax-included) - the value a customer sees on the invoice.
This matters because the same fixed amount discounts differently depending on which base it's subtracted from. A 10.00 € discount taken from the net price is worth more to the customer than 10.00 € taken from the gross price, once tax is added back on top of the (larger) discounted net amount.
Example
A 19% tax article costs 100.00 € net (119.00 € gross). A coupon with discount_amount = 10.00 and discount_amount_is_gross = false reduces the net price to 90.00 € (107.10 € gross) - the customer saves 11.90 € gross. The same discount_amount = 10.00 with discount_amount_is_gross = true instead reduces the net price by 10.00 € / 1.19 = 8.40 €, leaving 91.60 € net (109.00 € gross) - the customer saves 10.00 € gross, matching the amount they were promised.
When an order has multiple applicable positions with different tax rates, each position's share of a gross discount is converted to net using that position's own tax rate before being subtracted, not a single rate for the whole order.
A position is never discounted below 0. If its share of a gross discount is larger than its own gross price, the rest goes to the other applicable positions, so the full gross amount is discounted as long as the positions together are worth at least that much.
Example
Position A costs 10.00 € net at 0% tax (10.00 € gross), position B 10.00 € net at 100% tax (20.00 € gross). A gross coupon of 25.00 € splits 12.50 € / 12.50 € by net price, but A can only take 10.00 €. The remaining 2.50 € go to B: A is discounted 10.00 €, B 15.00 € gross (7.50 € net) - 25.00 € gross in total.
Rounding
Converting a gross amount to net (2 decimal places) and then recomputing tax on that net amount can occasionally be off by 1 cent from the original gross amount - not every combination of amount and tax rate has an exact net equivalent. TiruPay corrects for this automatically so the gross discount stays within 1 cent of what was promised, but it is not always possible to match it exactly.
discount_amount_is_gross only applies to AMOUNT coupons - PERCENTAGE coupons discount the same proportion regardless of whether it's computed on the net or gross price, so there is no gross/net distinction for them.
Fields
| Field | Type | Required | Description |
|---|---|---|---|
code | string | yes | The coupon code customers enter. Unique per service. |
name | string | yes | Display name of the coupon |
description | string | no | Description |
coupon_type | enum | yes | PERCENTAGE or AMOUNT |
discount_percentage | decimal | conditional | Required if type is PERCENTAGE. Range: 0–100. |
discount_amount | decimal | conditional | Required if type is AMOUNT. Must be >= 0. |
discount_amount_is_gross | boolean | no | If true, discount_amount is a gross (tax-included) amount rather than net (default: false). Only meaningful for AMOUNT coupons. |
min_order_amount | decimal | conditional | Minimum value of the positions the coupon applies to (only the discounted units count, see Unit Limitation). Compared against the net value, or the gross value if discount_amount_is_gross is true. Required if discount_amount is set, and must be greater than the discount amount. |
valid_from | datetime | yes | When the coupon becomes valid (default: now) |
valid_until | datetime | no | When the coupon expires |
is_global | boolean | no | If true, applies to all articles in the service (default: false) |
coupon_category_id | string | conditional | Coupon category whose availabilities decide where the coupon applies. Required unless is_global is true. |
max_redemptions | integer | no | Maximum total uses across all customers |
first_order_only | boolean | no | If true, only applies to a customer's first order (default: false) |
recurring_discount | boolean | no | If true, automatically re-applies on subscription renewals (default: false) |
Coupon Availability
A non-global coupon needs to specify which articles it applies to. This is done through Coupon Categories and Availabilities.
Coupon Categories
A coupon category groups a set of availability rules. Multiple coupons can share the same category, making it easy to define "this group of articles" once and reuse it.
Availabilities
Each availability targets exactly one of:
- A specific article
- A specific article extension
- An entire article category (all articles in that category)
The inherit flag controls whether extensions of a targeted article also get the discount.
An availability can also cap how many units of its target it discounts, via unit_limitation - see Unit Limitation below.
Global Coupons
If is_global is true, the coupon applies to every article in the service - no availability rules needed.
Unit Limitation
By default, an availability discounts every unit of its target. Setting unit_limitation to a positive integer caps that to at most that many units, order-wide and not per position. If an order contains more units than the limit allows, only the first units (up to the limit) are discounted; the rest are charged at full price on the same position, rather than being split into a separate line item.
Example
A coupon gives 50% off, with an availability on an extension set to unit_limitation = 5. An order has 10 units of that extension at 10.00 € each (100.00 € total). Only 5 units are discounted: 5 × 10.00 € × 50% = 25.00 € off, instead of the 50.00 € an unlimited coupon would give. The position's total_price_after_discount is 75.00 €.
Units are counted per availability, not per article. An availability with inherit = true shares its single unit_limitation across every child it matches - a category-level availability with unit_limitation = 5 caps the combined discounted units across all articles in that category, not 5 units per article.
Example
An availability targets an article category with inherit = true and unit_limitation = 5. An order has 3 units of Article A and 4 units of Article B, both in that category. Only 5 of the combined 7 units are discounted: all 3 of Article A's units, then 2 of Article B's 4 units. Article B's remaining 2 units are charged at full price.
When the limit runs out partway through, TiruPay needs to decide which positions get the remaining discount first. The apply-code endpoint takes an order_position_sort_order parameter to control this:
| Value | Behavior |
|---|---|
sort_order (default) | Positions are prioritized by their stored sort_order field, lowest first. |
price_asc | Cheaper positions are prioritized first. |
price_desc | More expensive positions are prioritized first. |
Example
An availability targets an article category with inherit = true and unit_limitation = 1. An order has one unit of Article A (5.00 €) and one unit of Article B (20.00 €), both in that category. With order_position_sort_order = price_desc, Article B (the pricier one) gets the discount and Article A stays at full price.
Not Remembered on Renewal
order_position_sort_order is a parameter of the apply-code call itself - it isn't stored on the coupon, the availability, or the order. Subscription renewals re-apply a recurring_discount coupon automatically and always use the default sort_order strategy, regardless of what was chosen when the coupon was first applied. If you need a specific, repeatable allocation across renewals, don't rely on price_asc/price_desc! Set the sort_order of the renewal's own order positions explicitly instead. As subscriptions have at most one article, this should rarely be an issue.
Listing Coupons and Categories
GET /coupons/ returns coupons with their redemptions_count, paginated with offset/limit. Besides search (code, name, description, value and category name) it takes these filters:
| Parameter | Description |
|---|---|
coupon_category_ids | Only coupons of these coupon categories |
is_global | true for global coupons only, false for non-global ones only |
has_category | true for coupons with a category, false for coupons without one. Combined with is_global=false, this lists coupons that currently can't be applied anywhere. |
article_id / article_extension_id / article_category_id | Only coupons available for this target (plus global coupons, unless include_global=false) |
GET /coupons/categories returns the categories sorted by name, each with coupon_count and availability_count.
GET /coupons/categories/{category_id}/availabilities returns the category's availabilities paginated (count, items), with offset/limit and a search over the name of the targeted article, extension or article category.
Deleting a category
A coupon category can only be deleted once no coupon belongs to it anymore - move its coupons to another category (or make them global) or delete them first. Otherwise the request fails with 409. Deleting the category also removes its availabilities.
Validation & Limits
When a coupon is applied, TiruPay checks all of the following:
- Service match - The coupon belongs to the same service as the order.
- Validity period - The current time is between
valid_fromandvalid_until. - Minimum order amount - The order total meets the minimum (if set).
- Redemption limit - The coupon hasn't exceeded
max_redemptions. - First order only - The customer hasn't used this coupon before (if enabled).
- Availability - The coupon applies to at least one position in the order (global or matching availability).
First Order Only on Drafts Without a Customer
A draft order created without a customer can still have a first_order_only coupon applied - the check runs once a customer is linked. If that customer has already used the coupon on another order, linking succeeds but the coupon is removed from the order and its totals are recalculated.
You can preview whether a coupon is applicable without actually applying it using the validation endpoint. It returns a boolean result with a reason if the coupon is not applicable.
No PAYG
Coupons cannot be applied to orders that contain pay-as-you-go positions.
Recurring Discounts
When recurring_discount is true, the coupon automatically re-applies to subscription renewal orders. On each renewal, TiruPay checks if the coupon is still valid (not expired, not past max redemptions). If it's no longer valid, the renewal proceeds without the discount - no error is raised.
A recurring coupon carries over unchanged across a subscription upgrade or downgrade unless a new one is supplied with the change - in which case it replaces the existing one, deferred to take effect together with a downgrade, or immediately with an upgrade. It can also be switched or removed on its own, independent of any plan change, via a dedicated subscription endpoint.
Only a recurring_discount coupon can be attached to a subscription this way; a coupon marked first_order_only never can, since a subscription coupon reapplies on every renewal by definition.
Tax & Discount Interaction
Discounts are applied before tax calculation. Tax is calculated on the total_price_after_discount of each position, not the original price.
For a gross AMOUNT coupon, the gross discount is first converted to its net equivalent (using the position's tax rate) before being subtracted - tax is then calculated on the reduced net price as usual. See Gross vs. Net Discount Amounts.
Applied Coupons
When a coupon is applied to an order, TiruPay creates an Applied Coupon record that snapshots the discount values at the time of application. This means:
- If the coupon's discount percentage changes later, already-applied orders are not affected.
- The
total_discount_grantedfield records the actual discount amount across all positions. - Applying the same coupon to the same order again recalculates the discount (idempotent).
- Applying a different coupon requires removing the existing one first.
Good to know
One Per Order
Only one coupon can be applied per order.
Coupon Codes Are Service-Scoped
The same coupon code can exist in different services. Codes are unique within a service, not globally.
Removing a Coupon
When a coupon is removed from an order, all position discounts are reset to zero and the order totals are recalculated.
Min Order Amount Required for Fixed Discounts
When creating a coupon with a fixed discount_amount, you must also set min_order_amount - and it must be greater than the discount amount. This prevents discounts that exceed the order total.
Relationships
- Orders - Coupons are applied to orders, creating an Applied Coupon record.
- Articles - Coupon availability targets articles, extensions, or article categories.
- Services - Coupons and coupon categories are scoped to a service.
- Referrals - Referral codes are applied and removed through the same endpoint as coupons; a coupon and a referral code can both be active on one order at once.