Typical API workflow
Many integrations with the tebio API follow a similar basic pattern: an external system transmits customer, order or usage data to tebio. tebio processes this data commercially and then informs the external system about relevant status changes via webhooks or API calls.
This article describes a typical API workflow for companies that want to integrate tebio with their own systems.
Typical integration scenarios are:
- own checkout or own app
- own customer portal
- CRM integration
- ERP or accounting integration
- Provisioning system
- Usage-based billing
- Data synchronization with third-party systems
Basic principle
Section titled “Basic principle”The API is used to technically trigger processes in tebio or to retrieve data from tebio.
Webhooks complement the API by automatically informing external systems of events.
A typical process therefore consists of three parts:
- Preparation in the business portal: Products, prices, payment methods, taxes, invoicing and webhooks are configured.
- API calls by the external system: Customers, orders, subscriptions or usage data are transferred.
- Asynchronous feedback: tebio informs the external system via webhooks or provides status information via API.
Requirements
Section titled “Requirements”Before you start the API integration, the following prerequisites should be met:
- An active tebio account with a booked product Subscription Management
- An API key with the required roles and permissions
- configured products, options and prices
- configured payment methods if payments are to be processed via tebio
- configured taxes and invoice settings
- Set up webhook endpoints for relevant events
- Access to the technical API reference
Many technical settings are not made in the API itself, but are configured in the tebio business portal. The API then uses this configuration for processing.
Typical process at a glance
Section titled “Typical process at a glance”A typical API workflow for a new subscription looks like this:
- Create a customer or identify existing customers
- Determine product, options and prices
- Prepare payment method or payment mandate
- Trigger an order via the API
- Have a subscription, invoice or receipt generated by tebio
- Process webhook events
- Retrieve status, documents or payment information
- Update external system or unlock performance
Depending on the business model, individual steps can be omitted or added.
Step 1: Create or identify customers
Section titled “Step 1: Create or identify customers”Many API processes start with a customer.
An order, subscription, invoice or payment is usually assigned to a customer. Therefore, the external system must either create a new customer in tebio or clearly identify an existing customer.
New customer
Section titled “New customer”If the customer does not yet exist in tebio, the external system creates the customer via the API.
Different data is transmitted depending on the customer type, for example:
- Customer type
- Name or company name
- Email address
- Billing address
- VAT ID for business customers
- external reference from the CRM or ERP system
In response, the external system receives a unique customer identifier, which is used in the following steps.
Existing customer
Section titled “Existing customer”If the customer already exists, the external system should save and reuse the tebio customer ID.
Alternatively, the customer can be identified via search parameters, for example via:
- Email address
- Customer number
- external reference
- CRM ID
- ERP ID
Best practice: Save the tebio customer ID in the leading external system so that later API calls can be clearly assigned.
Step 2: Identify products, options and prices
Section titled “Step 2: Identify products, options and prices”In order for an order to be triggered, the external system must know which product should be booked.
Depending on the integration, product data, options and price lists are retrieved from tebio or stored in advance in the external system.
Typical data is:
- Product ID
- Option ID
- Price list ID
- Duration
- Payment strategy
- Tax category
- allowed payment methods
- external product references
In many integrations, this data is not pulled live for every order. Instead, they are regularly synchronized and stored in the external system.
This is particularly useful if you use your own checkout or app.
Step 3: Prepare payment method
Section titled “Step 3: Prepare payment method”Depending on the product, payment strategy and checkout model, a payment method must be prepared before or during the order.
Postpaid
Section titled “Postpaid”With postpaid models, the service is often provided first and billed later.
Typical payment methods are:
- Invoice with bank transfer
- SEPA direct debit
- external or manually finalized payments
In these cases, a separate payment step is not always required before ordering.
Prepaid
Section titled “Prepaid”With prepaid models, the customer pays in advance. Payment is often a prerequisite for the service to be activated.
Typical payment methods are:
- Credit card
- PayPal
- other direct online payment methods
For payment methods that require active customer confirmation, the checkout process must be designed accordingly. Depending on the payment gateway, payment mandates, tokens, redirects or other payment resources may be involved.
Important: The exact technical implementation depends on the payment method used and the configuration of the payment gateway.
Step 4: Place order
Section titled “Step 4: Place order”Ordering is the central API step in many integrations.
The external system communicates to tebio which customer would like to book which product with which options and references.
Typical components of an order are:
- Customer ID
- Product identifier
- selected options
- Price or price list reference
- Payment method
- Start date
- external order number
- external reference
- additional properties or metadata
tebio validates the order based on the existing platform configuration.
These include, among others:
- Product validity
- Sales period
- allowed payment methods
- Control configuration
- Customer and address data
- Mandatory fields
- Option rules
- Permissions
If the order is successfully processed, it may result in a subscription or other subsequent process.
Step 5: Process subscription and subsequent processes
Section titled “Step 5: Process subscription and subsequent processes”After a successful order, tebio takes over further processing.
Depending on the product and billing model, the following follow-up processes can arise:
- Subscription is created
- Payment is triggered
- Invoice or receipt is generated
- Documents are created
- Messages are sent
- Events are logged
- Webhooks are triggered
Many of these processes run asynchronously. This means: The API response to the order does not necessarily confirm that all subsequent processes have already been completely completed.
Therefore, external systems should not only rely on the immediate API response, but also take webhooks and status queries into account.
Step 6: Process webhooks
Section titled “Step 6: Process webhooks”Webhooks automatically inform external systems about events in tebio.
Typical webhook events are:
- Customer was created or updated
- Order has been recorded or processed
- Subscription has been created
- Subscription has been changed or canceled
- Invoice has been created
- Receipt has been created
- Payment was successful
- Payment failed
- Document was created
- Helpdesk ticket was created or updated
An external system can use these events to trigger subsequent processes.
Examples:
- Unlock access in a SaaS application
- Start provisioning for a service
- Update CRM record
- Inform ERP system
- View document in your own customer portal
- Start support process
- Mark default
Step 7: Retrieve status and documents
Section titled “Step 7: Retrieve status and documents”After a webhook, the external system can retrieve further details via the API if necessary.
Typical calls are:
- Customer details
- Order details
- Subscription status
- Billing details
- Payment status
- Documents
- Event history
This pattern often makes sense:
- tebio sends webhook with event and reference.
- External system checks the signature or origin of the webhook.
- External system retrieves details via API.
- External system updates its own data or starts a follow-up process.
This means the webhook remains slim, while detailed data can be accessed specifically via the API.
Example: Own checkout with tebio in the background
Section titled “Example: Own checkout with tebio in the background”A company operates its own checkout and uses tebio in the background for subscription management, billing and payments.
Typical process:
- Customer registers in their own checkout.
- External system creates the customer via the tebio API.
- External system displays products and options from tebio or from a synchronized catalog.
- Customer selects product, options and payment method.
- External system transmits the order to tebio.
- tebio processes orders, subscriptions, payments and documents.
- tebio sends webhook events to the external system.
- External system activates the service or updates its own status.
This pattern is suitable if the user navigation should remain entirely in your own front end, but tebio takes over the commercial processing.
Example: CRM integration
Section titled “Example: CRM integration”A company uses a CRM system as the leading system for customer data.
Typical process:
- Customer is created or updated in CRM.
- CRM transmits customer data to tebio.
- tebio saves the customer and returns a customer ID.
- CRM stores the tebio customer ID.
- Subsequent orders or subscriptions reference this customer ID.
- tebio informs the CRM about relevant events via webhook.
- CRM displays the current status or relevant documents.
This pattern is suitable if customer data is maintained outside of tebio, but tebio is used for subscription management and billing.
Example: Usage-based billing
Section titled “Example: Usage-based billing”With usage-based billing, consumption data is transferred to tebio from an external system.
Typical process:
- The product and pricing model are prepared as part of the configuration.
- External system measures usage, for example minutes, transactions, data volume or API calls.
- External system regularly transmits consumption data to tebio.
- tebio processes the usage in the appropriate billing period.
- The usage-based items are taken into account in the invoice run.
- Invoice and events are generated.
- External systems can process statuses and documents via API or webhooks.
Usage-based billing should generally be coordinated with tebio as part of a project.
Understanding synchronous and asynchronous
Section titled “Understanding synchronous and asynchronous”A common mistake in API integrations is the assumption that all subsequent processes are completed directly with the API response.
That’s not always the case.
Many processes in tebio can be processed asynchronously, for example:
- Payment processing
- Invoice creation
- Document creation
- Sending messages
- Webhook delivery
- Follow-up processes from orders
Therefore, integrations should be built to handle state changes.
Recommendation:
- Save API response
- Process webhooks
- Check status regularly via API when required
- ensure idempotent processing
- Plan for errors and repetitions
Avoid typical mistakes
Section titled “Avoid typical mistakes”Do not store IDs in the external system
Section titled “Do not store IDs in the external system”If external systems do not store tebio IDs, customers, products or subscriptions must be identified again later using search logic.
It is better to save relevant tebio identifiers directly in the external system.
Respond only to the first API response
Section titled “Respond only to the first API response”The first API response does not always mean that the payment, subscription, invoice or document has already been finally processed.
Use webhooks and status queries.
Process webhooks without idempotence
Section titled “Process webhooks without idempotence”Webhook events may be redelivered or arrive in a different order than expected.
External systems should process events idempotently and use unique event or object identifiers to check whether an event has already been processed.
Not syncing product data
Section titled “Not syncing product data”If product, option or price IDs are missing or out of date in the external system, orders may fail.
Synchronize product data regularly or define clear processes for product changes.
Do not plan for error cases
Section titled “Do not plan for error cases”API integrations should be able to handle validation errors, failed payments, declined orders, or technical timeouts.
To do this, plan logging, retry strategies and manual clarification processes.
API notice
Section titled “API notice”The specific endpoints, request bodies, response bodies, status codes and authentication details can be found in the separate API reference.
The following resources are particularly relevant for typical API workflows:
| Resource | Typical meaning |
|---|---|
| Customer | Create, search or update customers |
| Product | Retrieve or configure products, options and prices |
| Order | Trigger and process orders |
| Subscription | access or manage ongoing services |
| Payment | Start, check or refund payments |
| Invoice / Receipt | Retrieve invoices, receipts and billing documents |
| Document | Retrieve or provide documents |
| Webhook | Inform external systems about events |
| Event history | Track events and status changes |
| Usage/metering | Submit consumption data for usage-based billing |