Send preconfigured metered usage

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.

Description: Send up to 250 preconfigured metered usage events to the AppDirect marketplace that hosts the user account. For a description of preconfigured metered usage, see Preconfigured and custom metered usage.

Optional parameters are defined in the API reference documentation. One example is the Request Group Identifier (requestGroupId). You can use it to group usage requests, for example, by billing period, with an identifier of your choice. When you send a Request Group Identifier with requests, the Metered Usage page in the user interface displays the requests together.

The call results in a system-assigned request identifier (requestId) that uniquely identifies the request, and the response includes a request-specific endpoint that includes it. You can use the endpoint to confirm whether the usage events sent with the request were successfully processed: see Fetch usage processing status.

Important

Usage for products configured with volume pricing must not be sent in API requests with usage configured for other pricing models.

Endpoint URL: {base marketplace URL}/api/integration/v2/billing/usage

The {base marketplace URL} is the base URL for the marketplace that hosts the user account.

Request operation: POST

Mandatory parameters in the request:

• idempotencyKey—Unique caller-provided identifier for a metered usage request. Ensures duplicate submissions of the same usage can be identified and prevented; an error is returned.
• billable—Indicates usage is billable (true) or estimated (false).
• accountId—Unique identifier that associates a vendor (ISV), customer company, and subscription. Represents company entitlement. Provided by the vendor when the subscription is purchased. Marketplace Managers can locate it in the user interface Integration Event logs; for SUBSCRIPTION_ORDER events, it is the account ID that appears in the Identifiers column (see View integration events). This is the same as the accountIdentifier that is used in the Metered usage V1 API.
• eventId—Unique caller-provided ID for each metered usage event. When not assigned: null. If you send the eventId as null, the platform assigns an eventId.
• eventDate—Date and time the usage event was recorded by the metering system. Format: YYYY-MM-DDTHH:mm:ss.SSSZ.
• pricingUnit—Unit type that you preconfigured, for which you are sending metered usage. For supported units, see Supported metered usage units.
• quantity—Number of units of usage in the stated unit of measure (pricingUnit) incurred by the user. Maximum 10 decimal digits.

Following is an example JSON request to send preconfigured metered usage to a marketplace. In this example scenario, you configured metered usage for unit type gigabyte, and unit type hour, and a price for each when you configured the product edition. Now, you POST the following JSON to tell the marketplace to charge the user for 34 gigabytes that they used on July 22, and the three hours of service they used on July 24. You chose to assign both events a unique identifier to easily distinguish them from other events.

tip

ou must associate every usage event with an accountId. When you submit multiple events for the same accountId, you must repeat the accountId for every event that appears in the request, as shown in the JSON example.

JSON request example

{
  "idempotencyKey": "1234567ABCDEFG",
  "billable": "true",
  "usages": [
    {
      "accountId": "d20210429",
      "usageList": [
        {
          "eventId": "1234567",
          "eventDate": "2021-07-22T08:37:12.569Z",
          "pricingUnit": "GIGABYTE",
          "quantity": "34",
        },
      ],
    {
      "accountId": "d20210429",
      "usageList": [
        {
          "eventId": "12345678",
          "eventDate": "2021-07-24T11:02:41.380Z",
          "pricingUnit": "HOUR",
          "quantity": "3"
        }
      ]
    }
  ]
}

Response

The call results in a system-assigned request identifier (requestId) that uniquely identifies the request, and the response includes a request-specific endpoint that includes it. You can use the endpoint to confirm whether the usage events sent with the request were successfully processed: see Fetch usage processing status.