Subscription charges

Binding the product plan template with the current state

When the subscription has been created it uses the product plan as a reference, and reference each of the product plan charges. This reference is an object called subscription charge.

The Subscription Charges will automatically receive the default quantities and settings from the Product Plan, and depending on your Upodi setup this will often require that you set the appropriate quantities.

Billing cycle

As each billing cycle is run, a new set of subscription charges are created and the former set will be marked as processed. This keeps a reference over time to allow tracking of the subscription lifecycle. When a subscription charge is due, the billing cycle will mark the subscription charge as processed, by setting the field previous charge date, to the time of the billing process, and creates a new version of the subscription charge for future billing by setting the next charge date field; unless the subscription is ended.

The output of a subscription charge is an invoice line. Should a given billing cycle return multiple subscription charges, the generated invoice will include multiple lines.

Aligning on dates

Subscriptions is all about time. Periods and dates. When setting time in Upodi, it is important to understand the different fields that control time.


Multiple charges with different dates

Subscriptions may have multiple charges with different dates. This varies by design of your subscription product, so be aware on the product plan design.

  • Next charge date. The next charge date defines the next event of billing for a subscription charge. The next charge date is the trigger of when we conduct closed-loop billing. For example the next charge date would be November 1st 2020, upon which date the charge is billed.
  • Charge start and end. Normally the charge start is closely aligned (the same) as the next charge date. In the above example, November 1st 2020 will also act as the period start, and if the product plan is designed to be montly the period on the charge start and end would be November 1st 2020 till November 30th 2020.

Previous Amount

Each charge will continuously remember the maximum quantity reached within a billing cycle in the PreviousAmount field. This quantity is reset to the current Quantity on each billing cycle. If you want to be notified when this happens see Webhooks.

Updating a subscription charge via API

To update an individual subscription charge, use the HTTP PUT endpoint as defined here Update subscription charge API.

* If you want to align next charge date and period, you must provide both the *NextChargeDate* and *PeriodDate* fields.
* If you want to set a different next charge date and leave the period, only provide the *PeriodDate* field.
* If you want to keep the next charge date, but change the period, only provide the *NextChargeDate* field.
* Not providing either, will ignore changes to periods.


Forward and backward billing is different

When updating charge start and end via web and API please be aware of the context. Working with forward billing will push periods forward related to the charge start. Working with backward billing will push period backward aligning to the charge date backward.


We're always happy to help with code or other questions you might have! Search our documentation or contact helpdesk. You can also chat live with us using thbe Intercom icon.