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

# Adjust a Usage Event

> Corrects a usage event you already recorded, by its event_id. Send the actual amount the customer used (not a delta) and Metrifox handles the difference:

- **Less than recorded** → the difference is refunded.
- **More than recorded** → the difference is charged.
- **Leave both amounts out** → the event is undone completely.

Sending the same value again does nothing, so retries are safe.

> Usage endpoints are served from [https://api-meter.metrifox.com](https://api-meter.metrifox.com). Other API calls stay on [https://api.metrifox.com](https://api.metrifox.com).

For example, if you recorded 5 image generations but the customer only used 4, send the actual
amount and the difference is refunded.


## OpenAPI

````yaml POST /usage/events/adjust
openapi: 3.0.1
info:
  title: Metrifox API Documentation
  version: v1
  description: >-
    Welcome to Metrifox Platform's API documentation. This comprehensive API
    suite enables seamless integration with our platform, providing secure and
    efficient access to our services.
servers:
  - url: https://{defaultHost}
    variables:
      defaultHost:
        default: api.metrifox.com
security:
  - api_key: []
paths:
  /usage/events/adjust:
    servers:
      - url: https://api-meter.metrifox.com
    post:
      tags:
        - Usage
      summary: Adjust a recorded usage event
      description: >-
        Corrects a usage event you already recorded, by its event_id. Send the
        actual amount the customer used (not a delta) and Metrifox handles the
        difference:


        - **Less than recorded** → the difference is refunded.

        - **More than recorded** → the difference is charged.

        - **Leave both amounts out** → the event is undone completely.


        Sending the same value again does nothing, so retries are safe.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_key:
                  type: string
                  description: The unique customer identifier in your application.
                event_id:
                  type: string
                  description: The event_id of the original usage event to adjust.
                actual_quantity:
                  type: number
                  nullable: true
                  description: >-
                    The true quantity the customer used. Omit to leave quantity
                    unchanged.
                actual_credit_used:
                  type: number
                  nullable: true
                  description: >-
                    The true credits the customer used (prepaid features). Leave
                    out to keep credits unchanged.
                reason:
                  type: string
                  nullable: true
                  description: >-
                    Optional human-readable note stored on the adjustment for
                    audit.
              required:
                - customer_key
                - event_id
            examples:
              correct_down:
                summary: They used less than recorded (refund)
                value:
                  customer_key: cust-6d11ca90
                  event_id: evt_12345
                  actual_quantity: 4
                  reason: customer cancelled one item
              correct_up:
                summary: They used more credits than recorded (deduct the difference)
                value:
                  customer_key: cust-6d11ca90
                  event_id: evt_12345
                  actual_credit_used: 250
                  reason: actual token usage was higher than estimated
              full_revert:
                summary: Undo the event entirely
                value:
                  customer_key: cust-6d11ca90
                  event_id: evt_12345
                  reason: duplicate request
      responses:
        '200':
          description: Adjustment applied (or a no-op if already at the requested amount).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      event_id:
                        type: string
                        description: The original event_id that was adjusted.
                      adjusted:
                        type: boolean
                        description: >-
                          false when the event was already at the requested
                          amount (no-op).
                      actual_quantity:
                        type: number
                        description: The event's quantity after the adjustment.
                      actual_credit_used:
                        type: number
                        description: The event's credit usage after the adjustment.
                      refunded_quantity:
                        type: number
                        description: Quantity refunded when the actual amount was lower.
                      refunded_credit:
                        type: number
                        description: Credits refunded when the actual amount was lower.
                      deducted_quantity:
                        type: number
                        description: >-
                          Additional quantity charged when the actual amount was
                          higher.
                      deducted_credit:
                        type: number
                        description: >-
                          Additional credits charged when the actual amount was
                          higher.
                      message:
                        type: string
              examples:
                refunded:
                  summary: Downward correction refunded
                  value:
                    data:
                      event_id: evt_12345
                      adjusted: true
                      actual_quantity: 4
                      actual_credit_used: 0
                      refunded_quantity: 1
                      refunded_credit: 0
                      deducted_quantity: 0
                      deducted_credit: 0
                      message: Usage adjusted
                charged:
                  summary: Upward credit correction deducted
                  value:
                    data:
                      event_id: evt_12345
                      adjusted: true
                      actual_quantity: 5
                      actual_credit_used: 250
                      refunded_quantity: 0
                      refunded_credit: 0
                      deducted_quantity: 0
                      deducted_credit: 50
                      message: Usage adjusted
                no_change:
                  summary: Already at the requested amount (idempotent no-op)
                  value:
                    data:
                      event_id: evt_12345
                      adjusted: false
                      actual_quantity: 4
                      actual_credit_used: 0
                      refunded_quantity: 0
                      refunded_credit: 0
                      deducted_quantity: 0
                      deducted_credit: 0
                      message: No change; event already at the requested amount
        '400':
          description: >-
            Bad request - negative value, or quantity and credit moving in
            opposite directions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: >-
                  cannot increase one dimension while decreasing the other in a
                  single adjustment
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unauthorized
        '404':
          description: Usage event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: 'Usage event not found: evt_12345'
      x-codeSamples:
        - lang: curl
          label: cURL — correct down (refund)
          source: |
            curl -X POST "https://api-meter.metrifox.com/usage/events/adjust" \
              -H "x-api-key: your_api_key" \
              -H "Content-Type: application/json" \
              -d '{
                "customer_key": "cust-6d11ca90",
                "event_id": "evt_12345",
                "actual_quantity": 4
              }'
        - lang: curl
          label: cURL — correct up (deduct)
          source: |
            curl -X POST "https://api-meter.metrifox.com/usage/events/adjust" \
              -H "x-api-key: your_api_key" \
              -H "Content-Type: application/json" \
              -d '{
                "customer_key": "cust-6d11ca90",
                "event_id": "evt_12345",
                "actual_credit_used": 250
              }'
        - lang: curl
          label: cURL — full revert
          source: |
            curl -X POST "https://api-meter.metrifox.com/usage/events/adjust" \
              -H "x-api-key: your_api_key" \
              -H "Content-Type: application/json" \
              -d '{
                "customer_key": "cust-6d11ca90",
                "event_id": "evt_12345"
              }'
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
        errors:
          type: object
          additionalProperties: true
          description: Detailed error information
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

````