Skip to main content

Welcome to our Dev Docs!



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+ Enterprise 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, there 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:

  1. Normal

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

  2. Trial

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

  3. 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 is 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 a 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 both 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+ Subscription Management context:

Merchant's Product

Cloud Storage Service

Metered usage metric

Data storage

Billing period


Billing rate

0.10$ per gigabyte (GB) of stored data per month

  1. Measurement

    The merchant offers a cloud storage service where customers can store their data, such as files, document, images and videos, in the cloud.

    Billwerk+ continuously measures the total amount of data each customer has stored in their cloud storage account.

  2. 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.

  3. Billing Rate

    Billwerk+ charges customers at a rate of $0.10 per gigabyte of data stored in their account for each month.

  4. 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.

Read this article to use metered components in our software.