Subscription management


A customer buys or subscribes to a product and has one or more Contracts. The Customer contains information such as:

  • Email address,
  • Postal address,
  • VAT-ID (optional),
  • Company details (optional),
  • Language,
  • Dispatch bearer for documents.

The data structure of the Customer can be freely extended by configurable additional fields called Custom fields. Learn more about Customer management here.


A Contract establishes a connection between a Customer and a product, including various subscription details such as:

  • The referenced Plan variant,
  • Component postings of periodic components,
  • Use of consumption components,
  • Information on the means of payment,
  • Data on the contract phases,
  • Start time, End time and the Time up to which pre-paid billing was performed.

The Contract represents an active association within the Billwerk+ Transform system. We provide comprehensive support for all processes related to contract creation, modification, or termination.

To dive deeper into Contract management, please click here for more information.

Contracts have distinct Phases, each representing a specific period and a set of conditions.


Understanding the concept of Phases is essential. Within the Contract are Phases, each with its own Start Date and a sequential series of various statuses shown below. These Phases are integral elements of the Contract.

There are three types of Phases:

  • Normal
    Defines normal operation. A Plan Variant is referenced, and billing is processed based on contract periods

  • Trial
    After a subscription, a trial period might be granted to the customer. This trial period is represented by a phase of the type "trial".

  • Inactive
    Subscription is inactive. This can be a pause or a regular termination. Phase does not have an End Date. It is specified by the Start Date of its successor.



There is only one active Phase at one time!

Within the GET /api/v1/contracts/{id} endpoint, you can always get to know what your current Phase of a given Contract

One of the Contract's Component types is Metered usage. To understand how it functions in practice, please read the paragraph below.

Metered Usage

In subscription management, metered usage refers to a pricing model where customers are billed based on their actual consumption or usage of a product or service. Instead of paying a fixed monthly or annual fee, customers are charged for the quantity or volume of the product or service they use during a specific billing period.

Metered usage is a pricing strategy that aligns costs with actual usage, providing greater flexibility for providers and customers in subscription-based business models.

Example of metered usage components:

  • telephone call minutes to be charged,
  • additional hardware,
  • transaction fees.


Metered usage in a Billwerk+ Transform context:

Merchant's ProductCloud Storage Service
Metered usage metricData storage
Billing periodMonthly
Billing rate0.10$ per gigabyte (GB) of stored data per month
  • Measurement
    The merchant offers a cloud storage service where customers can store their data, such as files, documents, images and videos, in the cloud.
    Billwerk+ continuously measures the total amount of data each customer has stored in their cloud storage account.
  • Billing Period
    The billing period is set on a monthly basis, meaning that at the end of each month, the customer will be billed for their data storage usage during that month.
  • Billing Rate
    Billwerk+ charges customers at a rate of $0.10 per gigabyte of monthly data stored in their account.
  • Invoicing
    At the end of the month, the provider generates an invoice for each customer based on the total gigabytes of data they have stored in their account during that month.
    The customer is billed accordingly, and the invoice includes a breakdown of the charges based on their storage usage.

Here is how exactly the metered usage example works in practice:

  • Customer A has 500 GB of data stored in their cloud storage account at the end of the month.
    Their monthly charge is $0.10/GB * 500 GB = $50.
  • Customer B, on the other hand, has 1,000 GB (1 terabyte) of data stored.
    Their monthly charge is $0.10/GB * 1,000 GB = $100.

This model allows customers to pay for the exact amount of storage they use each month. Customers can increase or decrease their storage usage, and their bills will reflect these changes accordingly.

Please read this article to use metered components in our software.