It is essential to understand basic concepts and structures to map it to your use case and find a reasonable approach of integration.
You are running a service you want to provide to your customers. The requirements of your customers might be quite different so you defined different sets of products, each set with a specific currency and tax rate. In billwerk these sets are called Plan Groups. These Plan Groups are organized in Plans and Plan Variants. During integration most of the time you will just have to deal with Plan Variants. These are the objects customers subscribe to. They allow the differentiation of contract terms, fees and other factors.
When a new customer subscribes to a Plan Variant a successful order process will basically generate a Customer and a Contract. The Customer object contains personal data like name and address. The Contract specifies the subscription details like subscribed plan variant, billing period, payment bearer, current balance, and others. A customer might want to subscribe to several independent products. Each subscription will be represented by a separate Contract. Unless there is an initial trial period or the customer subscribed to a freemium plan a subscription triggers an immediate billing. Recurring billing processes will then be triggered periodically based on the plan definition. In case of a trial period initial and recurring billing processes will be shifted accordingly.
Within a subscription it might be possible for your customers to add additional products, services and features that can be billed per period or based on metered usage. In billwerk these are the so called Components. A Component can be assigned to a Plan Variant or added/removed independently. Components that are billed per period behave like an additional contract to the main one and can be added or canceled separately from the chosen plan variant. As a mentioned there can also be components a customer does not order explicitly and will instead be billed based on Metered Usage. This usage can be passed prior to a billing process.
During lifetime of a subscription it is usually possible for a customer to up- or downgrade to another Plan Variant. What concerns Components, they can be added or removed during up- or downgrade. A Contract keeps a history which is represented by a list of Phases. Each Phase has a start date and usually references a Plan Variant. Up- and downgrading creates a new Phase that references the selected Plan Variant.
Understanding the concept of Phases is essential. There are three types of Phases.
- Normal: Defines normal operation. A Plan Variant is referenced, billing is processed based on contract periods
- Trial: After subscription a trial period might be granted to the customer. This trial period is represented by a phase of the type "trial".
- Inactive: In a phase of this type the subscription is inactive. This can be a pause or regular termination. A Phase does not have an end date. It is specified by the start date of its successor.
The lifetime of booked Components is handled separately from the contract's phases in Component Subscriptions. Each object represents the subscription to a specific component. It holds data like component reference, contract reference, quantity, start date and an optional end date.
A TaxPolicy basically describes how a certain type of product or services shall be taxed in a given list of countries. For instance, a tax policy's name could be "e-Books" and contain a tax rate of 19% for Germany and 2.5% for Luxembourg. All products must be mapped to a tax policy through their plan group so billwerk knows which rule to apply when invoicing.
billwerk not only automates recurring invoices but also regular payments. billwerk has integrated various payment service providers (PSP - Payment Service Provider) for this purpose. With this integration billwerk not only triggers payments automatically, but also receives - if the payment providers support this - information about chargebacks or refunds.
You simply configure the payment provider(s) of your choice in your billwerk account and the corresponding means of payment are already available to you. Details on the configuration of the payment providers can be found in the corresponding articles in our Help Center.