Send custom 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 custom metered usage events to the AppDirect marketplace that hosts the user account. For a description of custom 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.

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 identifier 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.
• customUnit—Unit of measure for reported custom usage. The unit is associated with a price (unitPrice).
• currency—Currency in which the custom metered usage price (unitPrice) is reported. Format: ISO 4217( for example: USD, EUR)
• unitPrice—Price for each unit (customUnit) of reported custom usage.
• quantity—Number of units of usage in the stated unit of measure (customUnit) incurred by the user. Maximum 10 decimal digits.

The following example JSON request illustrates how to send custom metered usage to a marketplace. In this example, the marketplace is notified to charge the user for a quantity of 34 gigabytes that they used on July 22, at a price of $0.15 USD each. You chose to assign the event a unique identifier to easily distinguish it from other events. An optional custom description for the charge is included.

JSON example

{
  "idempotencyKey": "1234567ABCDEFG",
  "billable": "true",
  "usages": [
    {
      "accountId": "d20210429",
      "usageList": [
        {
          "eventId": "1234567",
          "eventDate": "2021-07-22T08:37:12.569Z",
          "customUnit": "GIGABYTE",
          "currency": "USD",
          "unitPrice": "0.15",
          "quantity": "34",
          "description": "Aaron, this month you used 34 gigabytes"
        }
      ]
    }
  ]
}

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.