---
title: "Record usage event"
method: POST
path: "/meter-event"
tags: ["Usage"]
---

# Record usage event

`POST /meter-event`

## Request

- Base URL: `https://demo.onlinebillingform.com/api/v2`
- URL: `https://demo.onlinebillingform.com/api/v2/meter-event`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/billingserv/apis/billingserv-api-v2/docs/meter-event/post.ts> (a function with typed inputs; its response is checked against the schema)

Records bill-in-arrears usage for a configured package usage metric on a customer order. The authenticated API key must own the order, and `name` must match a usage metric configured on the order's package.

## Request body

- UsageEventRequest
  - `customer_id` integer, required: Customer ID that owns the order.
  - `order_id` integer, required: Order ID to record usage against.
  - `name` string, required: Usage metric name configured on the order package.
  - `qty` number, required: Usage quantity to add. Must be at least 1.
  - `payload` union: Optional metadata stored with the usage event. Non-object values are wrapped by the API under `value`.
    - object
    - unknown[]
      - unknown
    - string
    - number
    - boolean

## Response `200`

Usage event recorded

- UsageEventResponse
  - `success` true
  - `data` UsageEvent
    - `id` integer: Recorded usage event ID.
    - `metric` string: Usage metric name.
    - `qty` number: Quantity recorded by this event.
    - `unit_price` string: Overage unit price formatted with six decimal places.
    - `billable_qty` number: Portion of this event that became billable after allowance was applied.
    - `free_qty` number: Portion of this event deducted from the remaining free allowance.
    - `amount` number: Incremental billable amount created by this event.
    - `usage` UsageStatus
      - `used` number: Total unbilled usage recorded for this metric.
      - `remaining_free` number: Remaining included allowance before overage billing applies.
      - `remaining_free_percent` number, nullable: Percentage of included allowance remaining. Null when the metric has no included allowance.
      - `overage_qty` number: Quantity above the included allowance.
      - `billable_qty` number: Quantity currently billable in arrears.
      - `current_unbilled_amount` string: Current unbilled amount for this metric, formatted with four decimal places.
      - `threshold` UsageThreshold
        - `level` string
        - `threshold` 10 | 25
        - `message` string
    - `meter` UsageMeter
      - `id` integer: Package usage metric ID.
      - `name` string: Usage metric name. Use this value as `name` when recording usage.
      - `unit_label` string: Display label for the usage unit.
      - `included_allowance` number: Included free quantity for this metric.
      - `unit_price` string: Overage unit price formatted with six decimal places.
      - `usage` UsageStatus
        - `used` number: Total unbilled usage recorded for this metric.
        - `remaining_free` number: Remaining included allowance before overage billing applies.
        - `remaining_free_percent` number, nullable: Percentage of included allowance remaining. Null when the metric has no included allowance.
        - `overage_qty` number: Quantity above the included allowance.
        - `billable_qty` number: Quantity currently billable in arrears.
        - `current_unbilled_amount` string: Current unbilled amount for this metric, formatted with four decimal places.
        - `threshold` UsageThreshold
          - `level` string
          - `threshold` 10 | 25
          - `message` string
    - `data` object: Stored payload metadata for the event.

## Other responses

- `401`: Missing or invalid API key
- `403`: Authenticated key does not have permission for this endpoint
- `404`: Order or usage metric not found
- `422`: Validation error

## Changes

- **2026-08-22** `6b9208b64456`: 8 info
  - added the optional property `code` to the response with the `401` status
  - added the optional property `code` to the response with the `403` status
  - added the optional property `code` to the response with the `404` status
  - added the optional property `code` to the response with the `422` status
  - …4 more

[Operation history](https://skmtc.dev/billingserv/apis/billingserv-api-v2/changes/meter-event/post.md)

---

[API](https://skmtc.dev/billingserv/apis/billingserv-api-v2.md) - [All operations](https://skmtc.dev/billingserv/apis/billingserv-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/billingserv/apis/billingserv-api-v2/revisions/232ab5ca8413?raw)