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

# Create a Usage Record

> Registra uso em um subscription item medido.

Cria um usage record para um `subscription_item` com `usage_type: "metered"`.
O `timestamp` deve estar dentro do período atual de uso do item.

<ParamField body="subscription_item" type="string" required>
  Item medido (`si_*`).
</ParamField>

<ParamField body="quantity" type="integer" required>
  Quantidade de uso.
</ParamField>

<ParamField body="action" type="string">
  `increment` ou `set`. Padrão: `increment`.
</ParamField>

<ParamField body="timestamp" type="string">
  Timestamp ISO 8601 ou Unix seconds. Padrão: agora.
</ParamField>

<ParamField body="metadata" type="object">
  Metadata livre.
</ParamField>

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/subscription-item-usage-records" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "quantity": 42,
      "subscription_item": "si_123"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response 200 theme={}
  {
    "id": "ur_123",
    "object": "subscription_item_usage_record",
    "action": "increment",
    "created_at": "2026-05-20T12:00:00Z",
    "livemode": true,
    "metadata": {},
    "period_end": "2026-06-19T18:00:00Z",
    "period_start": "2026-05-19T18:00:00Z",
    "quantity": 42,
    "subscription": "sub_123",
    "subscription_item": "si_123",
    "timestamp": "2026-05-20T12:00:00Z",
    "updated_at": null
  }
  ```
</ResponseExample>