Documentation
Documentation
Billing and Charging

1Billing and Charging

Billing includes everything that is related to how much should be charged. Charging is the process of actually collecting the money from the subscriber. Those two processes are decoupled in our system. This means that the charging does not require to be executed directly after the billing. This step can be delayed (see Charge Strategies). Also the amount which should be charged does not only rely upon the calculated amount from the billing process. It can be different.

Once the subscription is active we carry a subscription ledger for every subscriber. During the period you can add entries onto the ledger of the subscriber by providing usage reports or adding additional ledger entries for services you want to bill your subscriber. Once the period has elapsed the subscriber’s token will be charged and a period invoice will be created and sent to your subscriber.

There are different tyes of charges that will automatically be booked to the ledger of the subscriber by the system. However, you do also have the option to create ledger entries manually. In case you use a metered fee, you need to create Metric Usage Reports, which give information that the consumed units can be charged.

2Metric Usage Reports

The Metric Usage Reports are used to charge your subscribers for the consumed units in case you are using metered fees on your product.

2.1Creating Metric Usage Reports

Metric usage reports are used to bill metered usage on your products with a metered price. You can create the metric usage report in the backend via Space > Subscription > Metric Usage Reports.

Metric Usage Reports are generally created via the web service api. You can also use the create operation on the Subscription Metric Usage Service to create an usage report.

Request

{
    "consumedUnits": "150",
    "description": "Transaction usage subscription 101",
    "externalId": "15-04-transaction-usage",
    "metric": {
        "id": 1
    },
    "subscription": {
        "id": 3
    }
}

2.2Charging Metric Usage Reports

All metric usage reports will be automatically charged to your subscriber at the end of the period. We sum all the metric usage reports for a subscriber and apply the metered fee that is defined in the product automatically.

3Ledger Entries

In case you want to add charges or credits to your subscriber you can do this via ledger entries.

3.1Create Ledger Entries

Ledger Entries can be added manually. Open the subscription and switch into the tab ledger entries to add positions.

You can also add ledger entries over the API by using the create operation on the Subscription Ledger Entry Service

Note
 Negative Amounts are equal to credits.

Request

{
    "amountIncludingTax": "55",
    "externalId": "subscriber-101-consulting-service",
    "quantity": "1",
    "subscriptionVersion": {
        "id": 3
    },
    "taxes": [
        {
            "rate": "8",
            "title": "VAT Switzerland"
        }
    ],
    "title": "Consulting Services"
}

3.2Charging Ledger Entries

Once the ledger entries are created they will be in the state open. Open ledger entries are charged automatically once the next period is due. Alternatively you can also charge ledger entries manually by creating a charge for the subscription.

Charges can be created via the backend by navigating to the Charges Tab in the subscription. A charge contains of a planned execution date and a reference. Once the panned execution date is reached all open ledger entries will be charged. Alternatively, you can also create charges via the web service API by using the create operation on the Subscription Charge Service.

Request

{
    "externalId": "1-charge-subscription-101",
    "plannedExecutionDate": "2017-04-25T07:50:15.596Z",
    "processingType": "SYNCHRONOUS",
    "reference": "1-charge-subscription-101",
    "subscription": {
        "id": 3
    }
}

4Charge Strategies

Charges are normally carried out automatically once the period is finished. However, you do have the option to configure special charge strategies when the charging of your subscriber should happen. This is done under Space > Subscriptions > Configuration > Strategies. Here you can select a charge strategy.

You can also configure multiple charge strategies and apply conditions to them how they are selected. Strategy Conditions can be defined under Space > Subscriptions > Strategy Conditions.

For example if the total amount which should be charged is lower than 5 EUR the charge may make no sense because the fees are too high. As such a charge strategy can be defined which skips the charging for this specific period. The amount will be carried over to the next period.

Another use case could be that the charging should always happen at the beginning of the month because you expect that the subscriber has enough money on the bank account then. So you can configure a charge strategy which delays the charging until the next start of the month.