Appearance
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
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Display name of the service |
description | string | no | Description of the service |
logo_file_id | string | no | File ID to the service's logo |
color | string | no | Brand color in HEX format (e.g. #FF5733) |
service_code | string | yes | Unique short code used in order number generation (e.g. SVC1, SHOP) |
ext_invoicing_id | string | yes | External ID in your invoicing provider (see Invoicing) |
order_number_template | enum | yes | Template that controls how order numbers are formatted (default: SIMPLE) |
order_custom_text | string | no | Custom text used in order number templates that include {custom_text} |
invoicing_provider_type | enum | no | Which invoicing provider to use (pdf, sevdesk, or noop). Choose it when creating the service - see Invoicing |
invoicing_api_token | string | no | API token for the invoicing provider. Write-only: never returned. Updating the service without it keeps the stored token |
has_invoicing_api_token | boolean | auto | Whether an invoicing API token is stored (read-only) |
default_url | string | no | Your 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.
| Field | Description |
|---|---|
client_id | OIDC client ID (unique per service) |
client_secret | OIDC client secret |
discovery_url | OIDC 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
| Endpoint | Description |
|---|---|
GET /service/customers/{customer_id}/features | Current features of one customer |
GET /service/customers/features | Current 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:
| Parameter | Type | Description |
|---|---|---|
offset | integer | Number of customers to skip (default 0) |
limit | integer | Customers per page, 1-10000 (default 10000) |
updated_since | datetime | Only 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", "...": "..." }
}
}countis the total number of matching customers. Increaseoffsetbylimituntil you have fetchedcountcustomers.- 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
featureslist. featuresdescribes 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:
| Placeholder | Description |
|---|---|
{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
| Template | Pattern | Example |
|---|---|---|
SIMPLE | ORD-{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.