Skip to content

Services ​

A Service represents an external application or product that connects to TiruPay. It is the top-level organizational unit - all customers, articles, orders, and features belong to exactly one service. Each service is fully isolated from others, meaning data from one service is never visible to another.

Example

You operate two SaaS products: a project management tool and a design tool. Each product is registered as its own service in TiruPay. They have separate customers, separate articles, separate invoicing - even if the same person uses both products.

Fields ​

FieldTypeRequiredDescription
namestringyesDisplay name of the service
descriptionstringnoDescription of the service
logo_file_idstringnoFile ID to the service's logo
colorstringnoBrand color in HEX format (e.g. #FF5733)
service_codestringyesUnique short code used in order number generation (e.g. SVC1, SHOP)
ext_invoicing_idstringyesExternal ID in your invoicing provider (see Invoicing)
order_number_templateenumyesTemplate that controls how order numbers are formatted (default: SIMPLE)
order_custom_textstringnoCustom text used in order number templates that include {custom_text}
invoicing_provider_typeenumnoWhich invoicing provider to use (pdf, sevdesk, or noop). Choose it when creating the service - see Invoicing
invoicing_api_tokenstringnoAPI token for the invoicing provider. Write-only: never returned. Updating the service without it keeps the stored token
has_invoicing_api_tokenbooleanautoWhether an invoicing API token is stored (read-only)
default_urlstringnoYour service's homepage (HTTPS). Used as the fallback destination when a redirect is blocked - see Redirect Security

Authentication ​

Each service has a Login Information configuration that defines how users authenticate against TiruPay. Two methods are supported:

JWT ​

Your service signs a token with a shared secret (jwt_secret). The user sends this token to TiruPay, which verifies the signature and issues a TiruPay access token in return. This way, your existing user sessions can seamlessly authenticate with TiruPay without requiring users to log in a second time.

OIDC ​

As an alternative to JWT, you can configure OpenID Connect authentication. TiruPay acts as an OIDC client and validates tokens against your identity provider.

FieldDescription
client_idOIDC client ID (unique per service)
client_secretOIDC client secret
discovery_urlOIDC discovery URL for your identity provider

One Auth Method Per Service

A service can only have one authentication method configured at a time (JWT or OIDC). Changing the method replaces the previous configuration entirely.

Features ​

Features are access rights that you define per service. When a customer purchases an article, TiruPay can automatically grant the features attached to that article.

There are two types of features:

  • Boolean - Either granted or not. If any owned article grants this feature, the customer has it.
  • Integer - Accumulates quantity. If a customer owns two articles that each grant 5 units of a feature, the customer has 10 units total.

Each feature has a public_name (shown to customers) and an internal_name (used in your code to check access). The internal_name is globally unique across all services.

Example

Your project management tool defines a feature can_export_pdf (boolean) and max_projects (integer, value 10). When a customer buys the "Pro Plan" article, they receive both features. If they later buy an "Extra Projects" add-on that grants 5 more max_projects, they now have 15 total.

Reading Customer Features ​

EndpointDescription
GET /service/customers/{customer_id}/featuresCurrent features of one customer
GET /service/customers/featuresCurrent features of many customers, up to 10000 per page

Keeping Features in Sync

Don't poll for feature changes. Fetch all customers with the batch endpoint once, for example on first setup or to recover after an outage. After that, listen for the customer_updated webhook and reload only that customer through the single-customer endpoint.

The batch endpoint accepts these query parameters:

ParameterTypeDescription
offsetintegerNumber of customers to skip (default 0)
limitintegerCustomers per page, 1-10000 (default 10000)
updated_sincedatetimeOnly return customers whose features changed at or after this time

The response looks like this:

json
{
  "count": 2,
  "items": [
    {
      "customer_id": "c1",
      "features": [{ "feature_id": "f1", "internal_name": "max_projects", "quantity": 15 }]
    },
    { "customer_id": "c2", "features": [] }
  ],
  "features": {
    "f1": { "id": "f1", "internal_name": "max_projects", "type": "integer", "...": "..." }
  }
}
  • count is the total number of matching customers. Increase offset by limit until you have fetched count customers.
  • Customers are ordered from oldest to newest. New customers are always added to the last page, so the pages you have already fetched stay the same.
  • Customers without any features are included with an empty features list.
  • features describes every feature referenced on the page once, keyed by feature id.
  • With updated_since, customers who lost all their features are returned with an empty list. After missing webhooks (e.g. during downtime), pass the time of your last successful sync to fetch only the changes.

Rate Limit

The batch endpoint has a much lower rate limit than other endpoints and is not meant for regular polling. Fetch large pages instead of many small ones.

Order Numbers ​

TiruPay generates unique order numbers for each order using a configurable template system. The template is set per service and supports the following placeholders:

PlaceholderDescription
{year}Current year (e.g. 2025)
{month}Current month (e.g. 06)
{sequence}Auto-incrementing number per service
{service_code}The service's service_code field
{custom_text}The service's order_custom_text field

Available Templates ​

TemplatePatternExample
SIMPLEORD-{year}-{sequence}ORD-2025-00001
SERVICE{service_code}-{month}-{sequence}SVC1-06-00001
LONG{service_code}-{year}-{month}-{sequence}SVC1-2025-06-00001
CUSTOM_SIMPLE{custom_text}-{year}-{sequence}MYTEXT-2025-00001
CUSTOM_SERVICE{service_code}-{custom_text}-{sequence}SVC1-MYTEXT-00001
CUSTOM_LONG{service_code}-{custom_text}-{year}-{month}-{sequence}SVC1-MYTEXT-2025-06-00001

Each service has its own Order Sequence counter that tracks the next sequence number. You can set a custom starting point - for example, if you're migrating from another system and want to continue from order number 14335.

Changing the Sequence

Be careful when manually updating the order sequence. Setting it to a lower value than previously used numbers can result in duplicate order numbers.

Good to know ​

Service Isolation

All data is scoped to a service. Customers, articles, orders, and features from one service are never visible to another. The same email address can exist as a customer in multiple services.

Service Accounts

Service accounts use the /me shortcut to access their own service data without needing to know the service ID. This is the recommended approach for service-level integrations.

Invoicing Provider

If no invoicing provider is configured (or set to noop), TiruPay will skip invoice generation. This is useful for development or testing environments.

User View

End users only see a limited set of service fields (id, name, description). Service and Admin accounts see the full service details including invoicing configuration.

Relationships ​

A service is the central entity in TiruPay and connects to almost everything:

  • Customers - Each customer belongs to exactly one service.
  • Articles - Articles and article categories are defined per service.
  • Features - Access rights that are defined and managed per service.
  • Orders - All orders are placed within the context of a service.
  • Users - User accounts can be linked to one or more services.
  • Payments - Payment mandates are scoped to a service.
  • Redirect Security - Redirects back to your domain (login, checkout, mandate setup) are validated against a per-service whitelist.