Send preconfigured and 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.

Important

• You cannot use this combined pricing model method for usage for products configured with volume pricing. Usage for products configured with volume pricing must not be sent in API requests with usage for other pricing models.
• A single edition cannot be configured for both preconfigured and custom metered usage.

Description: Use the API to send, in one call, up to 250 preconfigured and custom metered usage events to the AppDirect marketplace that hosts the user account. For a description of preconfigured and custom metered usage, see Preconfigured and custom metered usage.

The call uses an array to send multiple usage events, which can be a combination of preconfigured and custom usage, with a request body and dataset that meets the mandatory requirements for preconfigured and custom usage respectively. See Send preconfigured metered usage and Send custom metered usage.

note

A single edition cannot be configured for both 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

Example scenario: In the example that follows, usage is sent for subscriptions to two editions, each identified by an accountId. One edition is configured for preconfigured usage measured in gigabytes, and the other for custom usage.

Common mandatory parameters and values for the request:

• idempotencyKey—Unique caller-provided identifier for a metered usage request. Ensures duplicate submissions of the same request can be identified and prevented; an error is returned.
• billable—Indicates usage is billable (true) or estimated (false).

tip

You 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.

Mandatory parameters for preconfigured usage in the request:

• 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.

Mandatory parameters for custom usage in the request:

• 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.
• quantity—Number of units of usage in the stated unit of measure (customUnit) incurred by the user. Maximum 10 decimal digits.

Following is an example JSON request to POST the following usage to a marketplace. It includes:

• Preconfigured usage:

  • When you configured the product edition purchased with the subscription that is identified with accountId d20210429, you preconfigured metered usage for unit type gigabyte and a price.
  • Now, you include information for the event that is identified with eventId "1234567", to tell the marketplace to charge the user for 34 gigabytes that they used on July 22. You can use the eventId that you assigned to distinguish this event from other events.

• Custom usage:

  • When you configured the product edition purchased with the subscription that is identified with accountId d20210430, you configured it for custom metered usage.
  • You do not assign the custom usage event an eventId (not recommended, but valid) so the platform assigns one instead.
  • You include information to tell the marketplace to charge the user 17.30 Euros per hour for 6.5 hours of service that they used on July 3. You include a custom price, unit, and currency, because you did not preconfigure that information when you configured the edition.

JSON example

{
  "idempotencyKey": "1234567ABCDEFG",
  "billable": "true",
  "usages": [
    {
      "accountId": "d20210429",
      "usageList": [
        {
          "eventId": "1234567",
          "eventDate": "2021-07-22T08:37:12.569Z",
          "pricingUnit": "GIGABYTE",
          "quantity": "34"
        }
      ]
    },
    {
      "accountId": "d20210430",
      "usageList": [
        {
          "eventId": "null",
          "eventDate": "2021-07-03T11:07:29.020Z",
          "customUnit": "HOUR",
          "currency": "EUR",
          "unitPrice": "17.30",
          "quantity": "6.5"
        }
      ]
    }
  ]
}

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.