Unlike plan variants, metered components are billed based on consumption at a specific point in time. We define these kinds of consumption as metered usage. Metered usage can be added to a contract via the POST / Orders endpoint or through a separate API call. There is also an endpoint to delete unbilled metered usage.

Bill metered usage

When registering metered usage with a contract, you have to provide a dueDate. Metered usage is billed in regular recurring billings. All unbilled entries with dueDate <= NextBillingDate will be billed in this process. Metered usage will be billed even from previous billing periods, so you can simply post it with the correct DueDate, even if far in the past. If DueDate < LastBillingDate, then the free quota defined in the PlanVariant will we not be considered.

Sample request

POST /Orders

{
  "ContractId": "5e563b344de08409ace88ecb",
  "Cart": {
    "MeteredUsages": [
      {
        "ComponentId": "5cb5c38e4de0842368ea6e32",
        "Quantity": 5
      }
    ],
    "ComponentSubscriptions": [],
    "DiscountSubscriptions": [],
    "RatedItems": [],
    "Quantity": 1
  },
  "ChangeDate": null,
  "TriggerInterimBilling": true,
}

By setting TriggerInterimBilling to true, all unbilled metered usage entries with DueDate <= current date/time in the contract will be billed instantly.

POST /Contracts/{contractId}/usage

{
 "DueDate":"2020-02-26T09:32:36.123Z",
 "ComponentId":"5cb5c38e4de0842368ea6e32",
 "Quantity":5
}

Alternatively metered usage can be posted to a contract without an order. When adding metered usage like this, an interim billing has to be triggered separately, if applicable.

Sample response

{
  "Id": "5e56923d9cc9ba14fc9c1e41",
  "ContractId": "5e563b344de08409ace88ecb",
  "TransferredAt": "2020-02-26T15:43:57.0000000Z",
  "ComponentId": "5cb5c38e4de0842368ea6e32",
  "Quantity": 5,
  "Key": "",
  "DueDate": "2020-02-26T09:32:36.1230000Z"
}

Override for metered usage

Override for metered usage is a feature that allows you to overwrite both the price and the description for the metered usage used when you pass a metered usage to billwerk. This gives you more flexibility in structuring your product catalog. Due to security reasons this is REST-API exclusive.

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

{
    "Id": "5ce530b9443e5522685f2e93",
    "ContractId": "5cd186af443e551fe8e4f5dd",
    "TransferredAt": "2019-05-22T11:21:29.0000000Z",
    "ComponentId": "5ce53069443e551b9caccc64",
    "Quantity": 1,
    "Key": "",
    "DueDate": "2019-05-21T06:11:34.0000000Z",
    "ProductOverride": {
        "PricePerUnit": 100,
        "Name": "MeteredUsage2.0",
        "Description": "Hey, I'm an overridden metered usage"
    }
}