---
title: "Billing Usage V2"
method: POST
path: "/integration/v2/billing/usage"
tags: ["Integration"]
---

# Billing Usage V2

`POST /integration/v2/billing/usage`

## Request

- Base URL: `https://marketplace.appdirect.com/api`
- URL: `https://marketplace.appdirect.com/api/integration/v2/billing/usage`
- Auth: none declared
- TypeScript: <https://skmtc.dev/appdirect/apis/companies/docs/integration/v2/billing/usage/post.ts> (a function with typed inputs; its response is checked against the schema)

Submit preconfigured, custom, or volume-priced metered usage data to be billed for a customer account. <br/> <br/> Volume pricing usage is always preconfigured, not custom. It is processed at 6:00 PM UTC, either on the last day of the billing period or, if delayed billing is configured (always recommended for volume pricing), on the last day of a defined number of days after the billing period ends. It must be submitted in requests that do not include other pricing models.

## Request body

- MeteredUsageRequest: Metered usage event submission
  - `idempotencyKey` string: Unique caller-generated identifier for the metered usage that is sent. Ensures duplicate submissions can be identified and an error returned. Required.
  - `requestGroupId` string, nullable: A caller-generated identifier to group related metered usage requests. For example, 'January 2022' to group all requests that include January billing period events.
  - `billable` boolean: Indicates usage is billable (true) or estimated (false). Required.
  - `usages` MeteredUsageItem[]: List of metered usage events.
    - `accountId` string: Unique identifier that associates a vendor (ISV), customer company, and subscription. Represents company entitlement. Provided by vendor (ISV) when subscription purchased. Marketplace Managers can locate it in the user interface Integration Event event logs.
    - `usageList` UsageItem[]: List of metered usage event details.
      - `eventId` string: ID for each metered usage event. When not assigned: null. Required.
      - `eventDate` string, date-time: Date and time the usage event was recorded by the metering system. Format: YYYY-MM-DDTHH:mm:ss.SSSZ. Required.
      - `pricingUnit` string: Unit of measure for reported usage. Associated with a price that will be charged for the usage. Required for preconfigured metered usage.
      - `customUnit` string: Unit of measure for reported custom metered usage. The unit is associated with a price (unitPrice). Required for custom metered usage.
      - `quantity` string: Total usage in the stated unit of measure (pricingUnit or customUnit). Maximum 10 decimal digits. Required.
      - `unitPrice` string: Price for each unit (customUnit) of reported custom usage. x-mimum is the minimum price allowed. Required for custom metered usage.
      - `description` string: Additional description about usage items.
      - `currency` string: Currency in which the custom metered usage price (unitPrice) is reported. Required only for custom metered usage. Empty string is valid for preconfigured metered usage. Format: ISO 4217. For example: USD, EUR
      - `attributes` object: Additional attributes for usage.

## Response `202`

Metered usage report successfully received

- MeteredUsageRequestAccepted: Reported metered usage received and accepted
  - `requestId` string: Unique system-assigned identifier for the metered usage request. Returned with the response.
  - `idempotencyKey` string: Unique caller-generated identifier sent with the metered usage submission.
  - `queryUsageStatus` string: API endpoint to fetch the processing status of all metered usage events submitted with the request.

## Other responses

- `400`: Bad Request
- `404`: Not Found
- `500`: Internal Server Error

## Changes

- **2026-11-06** `1fc240f06971`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/appdirect/apis/companies/changes/integration/v2/billing/usage/post.md)

---

[API](https://skmtc.dev/appdirect/apis/companies.md) - [All operations](https://skmtc.dev/appdirect/apis/companies/llms.txt) - [OpenAPI document](https://skmtc.dev/appdirect/apis/companies/revisions/1fc240f06971?raw)