Metered usage V2

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.

AppDirect marketplaces support metered usage billing, also known as usage-based billing, which is how marketplaces or Developers charge users for their variable use of a product during each billing period. Developers configure metered usage through pricing settings for each product edition and add-on product. Typically, you use the unit that you set within the pricing settings to measure and charge for usage, for example each gigabyte, hour, or user license that a user uses.

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 pre-configured 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.

Getting started

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.

Types of metered usage

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.

Using custom requests for 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
         }
             ]
         }
     ]
 }