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"
  }
}

Adding/removing component subscriptions

In-/decreasing quantity of component subscriptions

Overwrite for components

📘Note

📘
Note