> ## Documentation Index
> Fetch the complete documentation index at: https://www.billingserv.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Record usage 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.



## OpenAPI

````yaml /api-reference/openapi.json post /meter-event
openapi: 3.1.0
info:
  title: BillingServ API V2
  description: >-
    Resources and tools for developers to integrate with the BillingServ v2 API.
    v1 is deprecated; use the v2 base URL and bearer-token authentication unless
    an endpoint states otherwise.
  version: '2.0'
servers:
  - url: https://demo.onlinebillingform.com/api/v2
    description: BillingServ demo API
security:
  - bearerAuth: []
tags:
  - name: Customer
  - name: Package
  - name: Group
  - name: Country
  - name: County
  - name: VPN
  - name: Invoice
  - name: Order
  - name: Module
  - name: Report
  - name: Marketing
  - name: Setting
  - name: Checkout
  - name: Usage
paths:
  /meter-event:
    post:
      tags:
        - Usage
      summary: Record usage event
      description: >-
        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.
      operationId: POST_meter_event
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageEventRequest'
            example:
              customer_id: 4
              order_id: 13
              name: Bandwidth
              qty: 25
              payload:
                resource_id: server-123
                source: provisioning-system
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UsageEventRequest'
      responses:
        '200':
          description: Usage event recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageEventResponse'
              example:
                success: true
                data:
                  id: 481
                  metric: Bandwidth
                  qty: 25
                  unit_price: '0.050000'
                  billable_qty: 5
                  free_qty: 20
                  amount: 0.25
                  usage:
                    used: 105
                    remaining_free: 0
                    remaining_free_percent: 0
                    overage_qty: 5
                    billable_qty: 5
                    current_unbilled_amount: '0.2500'
                    threshold:
                      level: warning
                      threshold: 10
                      message: Free usage is below 10%.
                  meter:
                    id: 7
                    name: Bandwidth
                    unit_label: GB
                    included_allowance: 100
                    unit_price: '0.050000'
                    usage:
                      used: 105
                      remaining_free: 0
                      remaining_free_percent: 0
                      overage_qty: 5
                      billable_qty: 5
                      current_unbilled_amount: '0.2500'
                      threshold:
                        level: warning
                        threshold: 10
                        message: Free usage is below 10%.
                  data:
                    resource_id: server-123
                    source: provisioning-system
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                errors: Invalid API Key
        '403':
          description: Authenticated key does not have permission for this endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                errors: Insufficient permissions for this endpoint.
        '404':
          description: Order or usage metric not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidOrder:
                  summary: Invalid order
                  value:
                    success: false
                    message: Invalid order.
                metricNotFound:
                  summary: Metric not found
                  value:
                    success: false
                    message: Usage metric not found.
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                success: false
                errors:
                  customer_id:
                    - The customer id field is required.
                  order_id:
                    - The order id field is required.
                  name:
                    - The name field is required.
                  qty:
                    - The qty field is required.
      security:
        - bearerAuth: []
components:
  schemas:
    UsageEventRequest:
      type: object
      properties:
        customer_id:
          type: integer
          description: Customer ID that owns the order.
        order_id:
          type: integer
          description: Order ID to record usage against.
        name:
          type: string
          description: Usage metric name configured on the order package.
        qty:
          type: number
          minimum: 1
          description: Usage quantity to add. Must be at least 1.
        payload:
          oneOf:
            - type: object
              additionalProperties: true
            - type: array
              items: {}
            - type: string
            - type: number
            - type: boolean
            - type: 'null'
          description: >-
            Optional metadata stored with the usage event. Non-object values are
            wrapped by the API under `value`.
      required:
        - customer_id
        - order_id
        - name
        - qty
      additionalProperties: true
    UsageEventResponse:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          $ref: '#/components/schemas/UsageEvent'
      additionalProperties: true
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        errors:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
            - type: object
              additionalProperties: true
      additionalProperties: true
    ValidationErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        errors:
          oneOf:
            - type: array
              items:
                type: string
            - type: object
              additionalProperties: true
            - type: string
      additionalProperties: true
    UsageEvent:
      type: object
      properties:
        id:
          type: integer
          description: Recorded usage event ID.
        metric:
          type: string
          description: Usage metric name.
        qty:
          type: number
          description: Quantity recorded by this event.
        unit_price:
          type: string
          description: Overage unit price formatted with six decimal places.
        billable_qty:
          type: number
          description: >-
            Portion of this event that became billable after allowance was
            applied.
        free_qty:
          type: number
          description: Portion of this event deducted from the remaining free allowance.
        amount:
          type: number
          description: Incremental billable amount created by this event.
        usage:
          oneOf:
            - $ref: '#/components/schemas/UsageStatus'
            - type: 'null'
        meter:
          oneOf:
            - $ref: '#/components/schemas/UsageMeter'
            - type: 'null'
        data:
          type: object
          additionalProperties: true
          description: Stored payload metadata for the event.
      additionalProperties: true
    UsageStatus:
      type: object
      properties:
        used:
          type: number
          description: Total unbilled usage recorded for this metric.
        remaining_free:
          type: number
          description: Remaining included allowance before overage billing applies.
        remaining_free_percent:
          oneOf:
            - type: number
            - type: 'null'
          description: >-
            Percentage of included allowance remaining. Null when the metric has
            no included allowance.
        overage_qty:
          type: number
          description: Quantity above the included allowance.
        billable_qty:
          type: number
          description: Quantity currently billable in arrears.
        current_unbilled_amount:
          type: string
          description: >-
            Current unbilled amount for this metric, formatted with four decimal
            places.
        threshold:
          oneOf:
            - $ref: '#/components/schemas/UsageThreshold'
            - type: 'null'
          description: >-
            Warning information when free allowance is below 25% or 10%;
            otherwise null.
      additionalProperties: true
    UsageMeter:
      type: object
      properties:
        id:
          type: integer
          description: Package usage metric ID.
        name:
          type: string
          description: Usage metric name. Use this value as `name` when recording usage.
        unit_label:
          type: string
          description: Display label for the usage unit.
        included_allowance:
          type: number
          description: Included free quantity for this metric.
        unit_price:
          type: string
          description: Overage unit price formatted with six decimal places.
        usage:
          $ref: '#/components/schemas/UsageStatus'
      additionalProperties: true
    UsageThreshold:
      type: object
      properties:
        level:
          type: string
          example: warning
        threshold:
          type: integer
          enum:
            - 10
            - 25
        message:
          type: string
          example: Free usage is below 10%.
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Use `Authorization: Bearer <live_api_key>`.'

````