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

# Record usage event

`POST /meter-event`

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

---

[API](https://skmtc.net/b-cdn/apis/billingserv-api-v2.md) · [All operations](https://skmtc.net/b-cdn/apis/billingserv-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/b-cdn/billingserv-api-v2/revisions/76cfbed5eb40/schema)