Create subscription (deep dive)
The article Create your first subscription in the quick start describes the easiest way to manually create a subscription for a customer. This article explains how subscriptions can be created in the tebio platform.
When do I need this function?
Section titled “When do I need this function?”The most important concept: A subscription is not created in isolation in the standard processes via portal and hosted pages.
Instead, it is always the result of a successful order. Regardless of whether an order is placed in the portal or via a hosted page, an order is created in the background that bundles products, options, discounts and payment data. If this order is processed successfully, tebio creates the subscription from it and starts the billing process.
(Note: An exception via API exists for advanced headless scenarios. See “API Notes” below).
Requirements
Section titled “Requirements”Depending on the path chosen, different framework conditions must be met:
- For the portal (way 1): You need access to the tebio business portal with authorization to create orders. The affected customer must exist as a data record.
- For Hosted Pages (Way 2, 3, 5): The corresponding products must be marked in the system as active for sales (“Shop/Hosted Page”).
- For partners (way 4, 5): The sales partner must be created and activated.
The five paths of creation
Section titled “The five paths of creation”You can initiate subscriptions through various channels. Which method is suitable depends on who books the subscription: a business user, a sales partner or the customer themselves.
Step-by-step instructions
Section titled “Step-by-step instructions”Way 1: Create via the tebio business portal
Section titled “Way 1: Create via the tebio business portal”For customers who have already been created in the system.
[!NOTE] This does not necessarily mean that it has to be an “existing customer” with ongoing contracts. The only important thing for this route is that the person or company exists as a technical customer entity in the system (e.g. a newly created new customer) so that the order can be linked to them.
In this scenario, a subscription is created manually in the tebio Business portal. This is relevant, for example, for telephone sales or B2B sales.
- Starting point: You open the customer file in the portal and switch to the Orders tab.
- Product selection: You can access the product selection using the New order button.
- Configuration: You book options (e.g. weekend package) or devices (hardware) as well as possible discounts.
- Payment & Completion: Since you act as a business user in the portal, you can only select payment methods here that do not require interactive approval from the customer (e.g. existing SEPA mandate or invoice).
- Advanced configuration (optional): Here you can assign properties to the subscription (based on the well-known property metadata templates), specify a desired date for activation and define the billing cycle differently from the standard (configured on the product).
Way 2: Hosted page for new customers
Section titled “Way 2: Hosted page for new customers”For end customers, fully automated checkout on your website.
This is the classic e-commerce route. You link from your marketing website directly to the order page (hosted page) provided by tebio.
- Branding: The page appears in your company’s design (logo, colors, fonts).
- Process: Since the system does not yet know the customer, the customer fills out a complete contact and address form.
- Payment: The customer chooses his payment method (including interactive methods such as credit card, PayPal or Klarna) and agrees to the terms and conditions.
- Automation: tebio creates the order and subscription in the background. Depending on the configuration, the customer record and a user account are also created.
Way 3: Self-care portal for existing customers
Section titled “Way 3: Self-care portal for existing customers”For logged in customers who book upgrades or new subscriptions independently.
If you offer your customers a self-care / customer portal, the ordering process can be simplified.
- The customer is already logged in to the portal.
- If they click on Add subscription, a product selection opens in your company’s branding.
- Advantage: All contact and address fields are no longer required in the checkout process because the system already knows the customer.
- Existing payment data (e.g. a credit card stored in the wallet) can be reused with one click.
Way 4: Create via the sales partner portal
Section titled “Way 4: Create via the sales partner portal”For resellers, agencies and intermediaries.
If you work with external partners, they receive access to the tebio sales partner portal. Here, resellers can book subscriptions completely independently for end customers they have recruited.
- The sales partner logs in to the sales partner portal and enters an order on behalf of the customer.
- The process is very similar to checkout, but takes place in a safe environment for the partner.
- Important: The subscription is ultimately assigned to the customer, but the system automatically notes the sales partner on the order. This means that later commission accounting can access the assignment to the sales partner.
Way 5: Affiliate Order Page (Hosted Page)
Section titled “Way 5: Affiliate Order Page (Hosted Page)”For end customers who come via a partner’s affiliate link.
This is a hybrid form of Way 2 and Way 4. In the sales partner portal, your resellers will find an affiliate link for every product.
- The partner copies this link and puts it on their own website or sends it via email to interested parties.
- If an end customer clicks on the link, they end up on a regular new customer hosted page (visually absolutely identical to path 2).
- The assignment: An invisible tracking ID (sales partner) is tied to the session through the special link.
- If the customer completes the order, tebio creates the subscription and links the resulting order with the agent - here too, the commission is later billed fully automatically.
[!TIP] Ways 2, 3 and 5 all use the concept of Hosted Pages. You don’t need to provide your own interface for this checkout. tebio takes care of the entire checkout.
Result
Section titled “Result”No matter which of the 5 ways the subscription was created, your configured automatisms will automatically take effect after successful booking:
- Depending on the configuration, tebio generates an initial invoice or a payment receipt.
- tebio triggers webhooks to inform third-party systems (e.g. your shipping tool).
- It sends notifications (like the order confirmation) based on your message templates configured in the variable reference.
Notes and typical errors
Section titled “Notes and typical errors”- Failed payment: If the customer chooses a payment method such as credit card and the payment provider reports an error (e.g. card declined), the order remains in the “Payment Pending” status or is canceled. In this case the subscription will not be created!
- Different start date: If a start date in the future is specified when entering data (desired date), only the customer and the order will initially be created. The subscription and the user account will only be created and activated on the desired date.
API Notes
Section titled “API Notes”If you do not want to use tebio’s hosted pages (e.g. because you want to deeply integrate the checkout into your own mobile app), the platform offers extensive REST interfaces.
[!IMPORTANT] Order vs. Direct Investment As mentioned above, portal and hosted pages exclusively use the route via an order. However, via the API you have the flexibility to create a subscription completely separate from an order (direct creation). This is helpful if, for example, you are migrating old data or an external ERP system has already processed the order and tebio is used as a billing platform.
Here are the relevant endpoints for managing subscriptions and orders:
| End point | Method | Description | OperationId |
|---|---|---|---|
/v1/subscription | GET | Search subscriptions | searchSubscription |
/v1/subscription | POST | Create subscription | createSubscription |
/v1/subscription/{uuid}/deactivate | POST | Deactivate subscription | deactivateSubscription |
/v1/subscription/{uuid}/status | POST | Set subscription status | setSubscriptionStatus |
/v1/subscription/{uuid} | GET | Get subscription | getSubscription |
/v1/subscription/{uuid} | PATCH | Update subscription | updateSubscription |
/v1/subscription/{uuid}/options | POST | Change subscription options | changeSubscriptionOptions |
/v1/subscription/{uuid}/product-change | POST | Product change for subscription | subscriptionProductChange |
/v1/subscription/extstatus | POST | Set external status of the subscription | setSubscriptionExtStatus |
/v1/subscription/event-history/{uuid} | GET | Retrieve a subscription’s event history | getSubscriptionEventHistory |
/v1/subscription/event-history | GET | Search event history | searchSubscriptionEventHistory |
/v1/order/new-subscription | POST | Create order for new subscription | createNewSubscriptionOrder |
/v1/order/new-subscription/{uuid} | PATCH | Update order for new subscription | updateNewSubscriptionOrder |
/v1/order/change-subscription | POST | Create order for subscription change | createChangeSubscriptionOrder |
/v1/order/{uuid}/cancel | POST | Cancel order | cancelOrder |
/v1/order/{uuid} | GET | Retrieve order | getOrder |
/v1/order | GET | Search orders | searchOrder |