Skip to content

Articles & Features ​

An Article is anything a customer can purchase - a one-time product, a subscription plan, documents, or a balance top-up. Articles are organized into Categories, can be extended with Extensions, and grant Features upon purchase.

Example

Your SaaS has a "Pro Plan" (subscription, monthly, 29.99 €) and a "One-Time Setup" (one-time, 99.00 €). Both are articles. The Pro Plan lives in the category "Plans" and grants the features can_export_pdf and max_projects = 10. The Setup article lives in the category "Add-Ons" and grants no features.

Articles ​

An article defines a purchasable item with a net price and optional features. It belongs to exactly one category, which in turn belongs to a service.

Price Changes

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

Feature, PAYG, and Top-Up Changes

The same applies to an article's features, PAYG plan binding, and balance top-ups: updating them directly only affects new purchases. Existing subscriptions keep renewing with whatever they already had. Use Scheduled Article Changes to roll out such a change to existing subscribers in a controlled way.

Article Fields ​

FieldTypeRequiredDescription
namestringyesName of the article. Unique within its category.
descriptionstringnoDescription of the article
net_pricedecimalconditionalNet price. Must be >= 0. Exactly one of net_price/gross_price must be set.
gross_pricedecimalconditionalGross (tax-included) price. Must be >= 0. Exactly one of net_price/gross_price must be set.
is_subscriptionbooleanyesWhether this article is a recurring subscription (default: false)
intervalenumconditionalBilling interval. Required if is_subscription is true (except for a Free Tier), must be empty otherwise.
allow_multiplebooleannoIf false, the article can't be bought more than once. See Single Purchases (default: false)
hiddenbooleannoWhether the article is hidden from listings (default: false)
article_category_idstringyesThe category this article belongs to
is_free_tierbooleannoMakes the article a Free Tier: free, no term, no invoices. Only on create (default: false)
free_tier_fallbackbooleannoFree Tier only. See Free Tier (default: false)
free_tier_requires_payment_detailsbooleannoFree Tier only. See Free Tier (default: false)
trial_enabledbooleannoCustomers can start a Trial of this paid subscription article (default: false)
trial_duration_valueintegernoTrial only. Length of a Trial in trial_duration_unit. Empty: the Trial has no end
trial_duration_unitenumnoTrial only. Same values as interval: day, week, month, quarter, half_year or year. Set together with trial_duration_value
trial_end_actionenumconditionalTrial only, required with trial_enabled. convert continues as paid plan, fallback moves to the category's Free Tier, expire simply ends the trial
trial_requires_payment_detailsbooleannoTrial only. Payment details at the start of a fallback Trial; a convert Trial always requires them (default: false)
trial_reminder_daysintegernoDays before the end of a Trial the customer is reminded. 0 sends no reminder (default: 3)
trial_featureslistnoFeature values that replace the article's values during a Trial. See Trial Values

Single Purchases ​

With allow_multiple: false an article can't be bought more than once:

  • One-time article: an order can hold at most one unit, and a customer can't buy the article again once they own it. Refunded, revoked and withdrawn purchases don't count.
  • Subscription article: a customer can hold only one running (active, paused, cancelled or withdrawal pending) subscription of the article.

Adding a second unit to an order is rejected with 400. Finalizing an order for an article the customer already owns is rejected with 409 Conflict. The rule applies to the customer receiving the order, not to the paying customer, so a paying customer can buy the article for several customers.

An unpaid order (pending or awaiting capture) reserves its article until it is paid or cancelled. Finalizing a second order for the same article is rejected with 409 Conflict and names the unpaid order. Pay or cancel that order first. This also applies to Unique Subscriptions: an unpaid order for one article of the category blocks orders for the other articles.

Paid but not delivered

If an order is paid although the customer already owns what it sells, the order is still completed, but nothing is delivered: no subscription, features, balance top-ups or documents. Admins receive an order_not_delivered notification. Refund the order.

To limit a whole group of subscription articles instead of a single one, use Unique Subscriptions.

Net vs. Gross Pricing ​

Set an article's price as either net_price or gross_price - never both. This lets B2C-oriented services enter and manage prices the way their customers see them (tax-included), while B2B-oriented services keep working in net.

Whichever field isn't set is not returned - TiruPay does not fabricate a value using an assumed tax rate, since the base article has no country of its own to resolve a rate from. Country-specific availabilities always return both, since they have a tax rate to convert with.

Switching modes

Updating an article with gross_price clears any existing net_price (and vice versa). A Scheduled Price Change may also switch an article between net and gross mode - this does not affect country-specific availabilities that already have their own price override, since those are resolved independently.

Subscription Intervals ​

When is_subscription is true, you must set one of these intervals:

IntervalDescription
DAYDaily billing
WEEKWeekly billing
MONTHMonthly billing
QUARTEREvery 3 months
HALF_YEAREvery 6 months
YEARAnnual billing

Categories ​

Categories group articles within a service. Every article must belong to a category.

Beyond organization, categories serve an important role in the feature system: features attached to a category are inherited by all articles in that category. This lets you define a base set of features once and have them apply to every article in the group.

Category Fields ​

FieldTypeRequiredDescription
namestringyesName of the category
descriptionstringnoDescription of the category
service_idstringyesThe service this category belongs to
featureslistnoFeatures to attach to this category (inherited by all articles)
excluded_from_referral_spendbooleannoIf true, orders for articles in this category (and their extensions) never count toward a customer's cumulative spend in the referral program (default: false)
unique_subscriptionbooleannoIf true, a customer can hold only one running subscription of the subscription articles in this category. See Unique Subscriptions (default: false)
trial_oncebooleannoIf true, a customer gets only one Trial in this category, whichever article it is for (default: false)

Example

You create a category "Premium Plans" with the feature can_export_pdf = true. Every article you add to this category automatically grants that feature - no need to set it on each article individually.

Unique Subscriptions ​

Set unique_subscription on a category to make its subscription articles mutually exclusive. A customer then holds at most one running subscription across all subscription articles in the category. This also applies when the category's articles allow multiple subscriptions individually (allow_multiple).

  • Active, paused, cancelled (they run until the end of their period) and withdrawal-pending subscriptions count as running.
  • A purchase of a second subscription in the category is rejected with 409 Conflict.
  • To move a customer to a different article in the category, change the existing subscription instead. A change onto an article in the category is rejected if the customer already holds another subscription there.
  • One-time articles in the category are not affected.
  • The rule applies to the customer receiving the subscription, not to the paying customer. A paying customer can pay for subscriptions in the category for any number of different customers.
  • Turning the flag on does not touch existing subscriptions. It only applies to new purchases and changes.
  • A category that contains a Free Tier or an article with a Trial must keep the flag on.

Example

The category "Licenses" contains the subscription articles "Small", "Medium" and "Large" and has unique_subscription: true. A customer with a running "Small" subscription cannot buy "Medium" in addition, but can upgrade the "Small" subscription to "Medium".

Extensions ​

An Extension is an add-on that can only be attached to a subscription article. Extensions let customers upgrade or expand their subscription without changing the base plan.

Extensions have their own price and can grant additional features or balance top-ups. Unlike article features, extension features use delta values for integer features - they add to the customer's existing feature quantity rather than setting an absolute value.

Extension Fields ​

FieldTypeRequiredDescription
namestringyesName of the extension. Unique within its article.
descriptionstringnoDescription of the extension
net_pricedecimalconditionalNet price. Must be >= 0. Exactly one of net_price/gross_price must be set.
gross_pricedecimalconditionalGross (tax-included) price. Must be >= 0. Exactly one of net_price/gross_price must be set.
allow_multiplebooleannoIf false, at most one unit of the extension per order and per subscription (default: false)
hiddenbooleannoWhether the extension is hidden from listings (default: false)
article_idstringyesThe subscription article this extension belongs to

Example

Your "Pro Plan" subscription includes max_projects = 10. You create an extension "Extra Projects" (5.00 €/month) that grants max_projects +5. A customer who buys the Pro Plan and two Extra Projects extensions gets max_projects = 20 (10 + 5 + 5) for 39.99 €/month (29.99 € + 5.00 € + 5.00 €).

Features ​

Features define access rights that are granted when a customer purchases an article. They are defined at the service level and linked to categories, articles, or extensions.

There are two types:

  • Boolean - Granted or not. Value is true or false.
  • Integer - A numeric quantity. Values accumulate across purchases.

Feature Inheritance ​

Features flow through a clear hierarchy:

  1. Category features are inherited by all articles in that category.
  2. Article features can override category features or add new ones.
  3. Extension features add delta values on top of the article's features.

When you update the features on a category, the change is automatically propagated to all articles in that category.

Feature Overrides

If a category defines max_projects = 5 and an article in that category defines max_projects = 10, the article-level value wins. Category features act as defaults, article features act as overrides.

Trial Values ​

An article can grant different feature values while a customer is in a Trial of it, e.g. 10 members instead of 100. Send them as trial_features, in the same format as features. Responses return them as trial_feature_links.

json
{
  "features": [{ "kind": "integer", "feature_id": "members", "value": 100 }],
  "trial_features": [{ "kind": "integer", "feature_id": "members", "value": 10 }]
}
  • Features without a Trial value apply in full during the Trial.
  • Each Trial value must belong to one of the article's features and have the same kind. Otherwise the request is rejected with 400.
  • An update with trial_features replaces all Trial values of the article. Leave the field out to keep them, e.g. when you only change features.
  • Trial values are kept when you turn trial_enabled off, so they apply again once you turn it back on.
  • A Trial value whose feature the article no longer has, or has with a different kind, is not granted.

Balance Top-Ups ​

Articles and extensions can be configured to grant balance when purchased. Each top-up specifies a balance type and an amount.

This is useful for prepaid or credit-based systems: a customer buys a "100 Credits" article, and their balance is automatically topped up.

Multiple Top-Ups

A single article can grant multiple different balance types. For example, one article could add both API credits and storage quota.

Good to know ​

Hidden Articles

Hidden articles (hidden: true) are not returned in standard listings but can still be purchased if you know the article ID. Use this for internal or promotional items.

Name Uniqueness

Article names are unique within their category, not globally. Extension names are unique within their article. You can have articles with the same name in different categories.

Extensions Are Subscription-Only

Extensions can only be created for subscription articles. Attempting to add an extension to a non-subscription article will fail. This is enforced at every level.

No Deletion via API

Articles, categories, and extensions do not have delete endpoints in the API. They are removed via cascade when their parent entity is deleted.

Relationships ​

  • Categories - Every article belongs to exactly one category.
  • Extensions - Subscription articles can have extensions.
  • Features - Categories, articles, and extensions can grant features.
  • Balance Top-Ups - Articles and extensions can grant balance when purchased.
  • Article Documents - Articles and extensions can unlock downloadable documents when purchased.
  • Scheduled Article Changes - Changes to features, PAYG binding, top-ups, or document links can be rolled out to existing subscribers in a controlled way.
  • Orders - Articles and extensions appear as positions in orders.
  • Services - Categories (and thus articles) are scoped to a service.
  • Free Tier - A free subscription article without a term.
  • Trial - A free phase at the start of a paid subscription.