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. When a subscription cancellation is initiated in the marketplace, usage events with a timestamp after the cancellation initiation date are initially rejected. However, if the vendor subsequently accepts the cancellation with a later effective date, usage events falling between the marketplace cancellation time and the vendor confirmed cancellation time will be accepted.

  Below are some scenarios that explain if the usage is going to be accepted or not based on the condition.

  Assuming:

  • Cancellation Initiated by Marketplace: April 10, 2025 10:00 AM

  • ISV Confirms Cancellation: April 12, 2025 6:00 PM

  Scenario	Usage event timestamp	Cancellation status	Expected outcome
  Usage before cancellation initiation	April 9, 2025 8:00 AM	Initiated (not confirmed)	Accepted
  Usage just after cancellation initiation	April 10, 2025 11:00 AM	Initiated (not confirmed)	Rejected
  Usage between initiation and ISV confirmation	April 11, 2025 2:00 PM	Still pending ISV confirmation	Rejected
  Retry same usage after ISV confirms with a later timestamp	April 11, 2025 2:00 PM	ISV confirmed on Apr 12 @ 6:00 PM	Accepted
  Usage after ISV’s confirmed cancellation timestamp	April 13, 2025 9:00 AM	Confirmed	Rejected
  Usage before initiation, but reported after cancellation is confirmed	April 9, 2025 4:00 PM	Confirmed	Accepted

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