This topic is about Metered usage V2. Marketplaces use the Metered usage V1 API, Metered usage V2 API, or both, to support metered usage billing. See also: Metered usage V1.
Important: Metered usage v2 is currently in Early Availability status. Features in Early Availability status are only available in production to a limited number of customers based on fit with specific use cases. For more information about Early Availability status, see Product lifecycle phases. If you would like to use the product capabilities described here during the Early Availability phase, contact your AppDirect technical representative.
When you enable metered usage pricing, AppDirect marketplaces expose an API endpoint that you can use to report usage to the marketplace that owns the user's (customer's) account. For example, you can report the number of gigabytes of storage that users use, and the marketplace charges them for it based on the preconfigured or custom price that you define per gigabyte.
You can report usage as often as necessary, with one or more usage events per call. Every usage event is submitted with the date that the usage occurred, which is used to allocate the usage to a billing period so it can be invoiced accordingly. It then adds all the usage that you send, and invoices users for the total number of units used, for each edition or add-on product unit type (such as gigabyte, hour, or user license).
Although you can report usage for suspended and canceled subscriptions, the outcomes differ and some constraints exist:
Suspended subscriptions: When subscriptions are suspended, metered usage can still be submitted. If there is an active contract for the subscription, the submitted usage is invoiced with the next billing cycle. If there is not an active contract for the subscription, the submitted usage is included on the next invoice.
Canceled subscriptions: When a user cancels a subscription during the billing cycle, they are still invoiced on their next scheduled invoice date. You can report usage until the end of the billing period during which the user cancels a subscription, to include it on the invoice.
Important: After the end of the final billing period, any attempts to report usage for a canceled subscription are rejected and not invoiced. Therefore, we strongly recommend that you report usage as soon as possible.
Before you can get started with posting usage data, you must ensure that all the prerequisites are completed. For more information, see Metered usage prerequisites.
There are two types of metered usage, preconfigured and custom, and you can call the API for both of them. See Preconfigured and custom metered usage.
You can also (Marketplace managers) can post usage data for any active metered usage subscriptions with partner credentials and other parameters using the Metered Usage v2 API endpoint—Billing Usage v2. The following examples show requests to send metered usage to a marketplace using a subscription ID and vendor ID:
Request with subscriptionId
{
"idempotencyKey": "{{$guid}}",
"billable": true,
"subscriptionId": "02ab813a-e955-4255-8969-c5329839dd61",
"usages": [
{
"accountId": "1f071a3b-b59e-429d-bb91-c1bbd0ab458d",
"usageList": [
{
"pricingUnit": null,
"customUnit": "USERS",
"quantity": 4,
"unitPrice": 12,
"description": "ABCDEFG ",
"currency": "EUR",
"eventDate": "{{$isoTimestamp}}",
"eventId": null,
"attributes": null
}
]
}
]
}
Request with vendorId
{
"idempotencyKey": "{{$guid}}",
"billable": true,
"vendorId": "202f0f5e-c48a-46e9-bed5-2c1abd4eac33",
"usages": [
{
"accountId": "1f071a3b-b59e-429d-bb91-c1bbd0ab458d",
"usageList": [
{
"pricingUnit": "USER",
"customUnit": null,
"quantity": 10,
"unitPrice": null,
"description": "ABCDEF ",
"currency": "EUR",
"eventDate": "{{$isoTimestamp}}",
"eventId": null,
"attributes": null
}
]
}
]
}
Sample response
{
"requestId": "db0879f1-7a61-4ea3-91ff-4c18047b76fa",
"idempotencyKey": "66c94f03-27ab-428d-8a83-2e8b606f5bbb",
"queryUsageStatus": "/api/integration/v2/billing/usage/requests/db0879f1-7a61-4ea3-91ff-4c18047b76fa"
}