Send custom metered usage

note

This topic is about Metered usage V1. Marketplaces use the metered usage V1 API, metered usage V2 API, or both, to support metered usage billing. See also: Metered usage V2.

Description—Send usage data for custom metered usage to the AppDirect marketplace that hosts the user account. For a description of custom metered usage, see Preconfigured and custom metered usage.

Endpoint URL—{base marketplace URL}/api/integration/v1/billing/usage

The {base marketplace URL} is the base URL for the marketplace that hosts the user account. (See Locate the marketplace base URL.)

Request operation—POST

Mandatory parameters in the request

• account—User account that incurred the usage.
• accountIdentifier—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 accountId that is used in the Metered usage V2 API.
• quantity—Number of units of usage in the stated unit of measure incurred by the user.
• price—Custom price per unit.
• description—Custom description of this charge.

The unit parameter is optional. Whether you send it determines how events appear on invoices (when you send custom units, events are aggregated by unit type on invoices; see the custom metered usage section in Preconfigured and custom metered usage).

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, at a price of $0.15 each, with a custom description. As a best practice, we recommend that you name the unit applicable to the usage in the description.

JSON example

{
  "account": { "accountIdentifier": "MY_ACCOUNT" },
  "items": [
    {
      "quantity": "34",
      "price": "0.15",
      "description": "Aaron, this month you used 34 gigabytes."
    }
  ]
}