Component subscriptions
Just like the fees for plan variants, quantitybased and onoff components are billed based on usage over a time span. We define subscription to these types of components as component subscriptions. Component subscriptions can be added, in- or decreased and removed though the POST /Orders endpoint. To add new component subscriptions, a separate API call can be used.
Adding/removing component subscriptions
Sample request
POST /Orders
{
"TriggerInterimBilling": false,
"ContractId": "5e53dab7443e5516749566e2",
"Cart": {
"InheritStartDate": false,
"ComponentSubscriptions": [
{
"ComponentId": "5e53dab7443e5516749566fb",
"Quantity": 2.0
}
],
"EndComponentSubscriptions": [
"5e53dab7443e551674956702",
"5e53dab7443e551674956703"
]
},
"PreviewAfterTrial": false
}
If you simply want to add /remove component subscriptions and keep the current plan variant you can do so by removing the PlanVariantId from the order. Creating an order this way will keep the NextBillingDate
of the contract unchanged. Fees resulting from adding component subscriptions in this way will be billed with the next regular billing. To instantly bill these fees, you can trigger an interim billing in the order by setting TriggerInterimBilling
to true
, or by triggering a separate interim billing.
Remove ComponentSubscriptions
, EndComponentSubscriptions
from the sample request as required.
Sample response
{
"Id": "5e53dab7443e55167495670e",
"AllowWithoutPaymentData": true,
"ComponentSubscriptions": [
{
"ComponentType": "QuantityBased",
"PreventModification": false,
"VatPercentage": 19.0,
"TotalNet": 2.0,
"TotalVat": 0.38,
"IsQuantityBased": false,
"ComponentId": "5e53dab7443e5516749566fb",
"Quantity": 2.0
}
],
"Total": 7.0,
"TotalVat": 1.33,
"TotalGross": 0.0,
"NextTotalGross": 0.0,
"IsTrial": false,
"TrialEndPolicy": "NoTrial",
"Status": "InProgress",
"OrderType": "Signup",
"TriggerInterimBilling": false,
"CustomerId": "5e53dab7443e55167495670f",
"ContractId": "5e53dab7443e5516749566e2",
"PreviewAfterTrial": false
}
Sample request without order
POST /Contracts/[contractId]/componentSubscriptions
{
"Quantity": 1,
"StartDate": "2020-02-28T09:32:36.123Z",
"ComponentId": "5b9106b581b1f00870b3bca0"
}
When creating a new component subscription in a contract, in this way, no interim billing will be executed, the fees will be billed with the next regular billing.
Sample response without order
{
"Id": "5e58cd9a4de0840bf8ed2e19",
"ContractId": "5e563b344de08409ace88ecb",
"CustomerId": "5e563b344de08409ace88eca",
"ComponentId": "5b9106b581b1f00870b3bca0",
"Quantity": 1,
"StartDate": "2020-02-28T09:32:36.1230000Z"
}
In-/decreasing quantity of component subscriptions
Sample request
POST /Orders
{
"TriggerInterimBilling": false,
"ContractId": "5e53dab7443e5516749566e2",
"Cart": {
"InheritStartDate": false,
"ComponentSubscriptions": [
{
"ComponentId": "5e53dab7443e5516749566fb",
"Quantity": 4.0
}
],
"EndComponentSubscriptions": [
"5e53dab7443e5516749566fb"
]
},
"PreviewAfterTrial": false
}
If you simply want to change the quantity of a subscribed component, there is a shortcut. Subscribe to a component with the new quantity. In EndComponentSubscription
pass the ComponentId
instead of listing ComponentSubscriptionIds
. All corresponding subscriptions will be ended. This way, the new subscription will be the only existing one for the component.
Sample response
{
"Id": "5e53dab7443e551674956710",
"AllowWithoutPaymentData": true,
"ComponentSubscriptions": [
{
"ComponentType": "QuantityBased",
"PreventModification": false,
"VatPercentage": 19.0,
"TotalNet": 4.0,
"TotalVat": 0.76,
"IsQuantityBased": false,
"ComponentId": "5e53dab7443e5516749566fb",
"Quantity": 4.0
}
],
"Total": 7.0,
"TotalVat": 1.33,
"TotalGross": 0.0,
"NextTotalGross": 0.0,
"IsTrial": false,
"TrialEndPolicy": "NoTrial",
"Status": "InProgress",
"OrderType": "Signup",
"TriggerInterimBilling": false,
"CustomerId": "5e53dab7443e551674956711",
"ContractId": "5e53dab7443e5516749566e2",
"PreviewAfterTrial": false
}
Overwrite for components
Override for components is a feature that allows you to overwrite both the price and the description for the component used when you pass a component to billwerk. This gives you more flexibility in structuring your product catalog. For security reasons, components can only be overridden via REST API.
Note
Override componentes only works when the underlying component has the pricing model 'simple'.
Sample request
POST /Contracts/{contractId}/usage
{
"ComponentId": "5ce53069443e551b9caccc64",
"Quantity": 1,
"DueDate": "2019-05-21T06:11:34.0000000Z",
"ProductOverride": {
"PricePerUnit": 100,
"Name": "MeteredUsage2.0",
"Description": "Hey, I'm an overridden metered usage"
}
}
Sample response
{
"ComponentId": "5ce53069443e551b9caccc64",
"Quantity": 1,
"DueDate": "2019-05-21T06:11:34.0000000Z",
"ProductOverride": {
"PricePerUnit": 100,
"Name": "MeteredUsage2.0",
"Description": "Hey, I'm an overridden metered usage"
}
}
Updated 7 months ago