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

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Obtener el uso de la suscripción

> Lee el uso medido que una suscripción ha acumulado en su período de facturación actual, valorizado según los medidores de su plan.

Devuelve el uso medido que una suscripción ha acumulado en su **período de facturación actual**, valorizado según
los medidores asociados a su plan: un elemento por medidor, con la cantidad agregada, la cantidad
que realmente se factura después de consumir los créditos incluidos, el precio unitario y el
monto resultante, además de un total del período. Es una lectura: no activa la facturación por sí misma.
Consulta [Facturación basada en el uso](https://docs.y.uno/es/docs/payment-features/subscriptions/usage-based-billing) para saber cómo una
suscripción acumula medidores, créditos y precios en primer lugar.

## Cómo leer la respuesta

| Campo | Significado |
| - | - |
| `subscription_code` | La suscripción a la que pertenece el uso: el `id` que enviaste en la ruta. |
| `currency` | La moneda de la suscripción: en la que están expresados todos los `unit_price`, `amount` y `total` de esta página. |
| `period.start` / `period.end` | El período de facturación actual de la suscripción: la ventana sobre la que se agrega `items`. |
| `items[].meter_code` | El medidor que agrega este elemento. |
| `items[].event_name` | El `event_name` del medidor: aquello contra lo que reportan tus eventos de uso. |
| `items[].aggregation` | `SUM`, `COUNT` o `LAST`: consulta [Elegir una agregación](https://docs.y.uno/es/docs/payment-features/subscriptions/usage-based-billing#choosing-an-aggregation). |
| `items[].quantity` | La cantidad agregada reportada para este medidor en el período. |
| `items[].credits` | Cuántos de los créditos incluidos del medidor consumió la cantidad de este elemento. |
| `items[].billable_quantity` | La cantidad que realmente se factura después de consumir `credits`. |
| `items[].remaining_credits` | Créditos incluidos que quedan sin usar para este medidor en el período. |
| `items[].unit_price` | El precio de una unidad facturable. |
| `items[].amount` | `billable_quantity` valorizada a `unit_price`. |
| `items[].events_count` | Cuántos eventos de uso se reportaron contra este medidor en el período. |
| `items[].last_event_at` | Cuándo se reportó el más reciente de esos eventos. |
| `total` | La suma del `amount` de todos los elementos del período. Es cero cuando `items` está vacío. |

Toda cantidad y todo monto es un número JSON.

```json A subscription with one metered item theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
{
  "subscription_code": "c2094820-df10-4bd4-b7ef-dbe0d28db857",
  "period": {
    "start": "2026-09-15T15:54:32.436443Z",
    "end": "2026-10-15T15:54:32.272111Z"
  },
  "currency": "COP",
  "items": [
    {
      "meter_code": "b7cb6aad-0fcc-4898-ae8b-f500ee6dfbb3",
      "event_name": "lifecycle_1789487669444",
      "aggregation": "SUM",
      "quantity": 20,
      "credits": 0,
      "billable_quantity": 20,
      "remaining_credits": 0,
      "unit_price": { "currency": "COP", "value": 500 },
      "amount": { "currency": "COP", "value": 10000 },
      "events_count": 2,
      "last_event_at": "2026-09-15T15:54:46.620383Z"
    }
  ],
  "total": { "currency": "COP", "value": 10000 }
}
```

## Cuando no hay nada que facturar

Una suscripción cuyo plan no tiene medidores, o que no tiene ningún plan, devuelve `items: []` y un
`total` en cero en lugar de un error.

> [!NOTE]
>
> **El reporte es asíncrono**
>
> `POST /subscriptions/meters/events` responde `202` una vez que el evento se valida, antes de que se
> almacene. Una lectura de uso que ocurre poco después de reportar un evento todavía puede mostrar el total de
> antes de ese evento: los `items` de una suscripción mantuvieron la misma `quantity` y `events_count` en una
> lectura hecha inmediatamente después de reportar otro evento en stg. Espera un breve tiempo antes de
> confiar en que una lectura refleje el último reporte.

## Errores

| HTTP | `code` | Cuándo |
| - | - | - |
| `401` | `INVALID_CREDENTIALS` | El par `public-api-key` / `private-secret-key` falta o no es válido. |
| `404` | `NOT_FOUND` | La suscripción no existe: `"Subscription not found."` |


## OpenAPI

````yaml openapi/es/subscriptions/retrieve-subscription-usage.json GET /subscriptions/{subscription_id}/usage
openapi: 3.1.0
info:
  title: subscription
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
  - url: https://api.y.uno/v1
security:
  - sec0: []
    sec1: []
paths:
  /subscriptions/{subscription_id}/usage:
    get:
      summary: Retrieve Subscription Usage
      description: >-
        Devuelve el uso medido que una suscripción ha acumulado en su período de
        facturación actual, valorado según los medidores asociados a su plan. Un
        ítem por medidor, con la cantidad agregada, la cantidad que realmente se
        factura después de consumir los créditos incluidos, el precio unitario y
        el monto resultante, más un total del período.
      operationId: retrieve-subscription-usage
      parameters:
        - name: subscription_id
          in: path
          description: El identificador único de la suscripción.
          schema:
            type: string
          required: true
        - in: header
          name: X-Account-Code
          required: true
          schema:
            type: string
          description: >-
            El `account_id` que encuentras en tu [Dashboard de
            Yuno](https://dashboard.y.uno/developers) (UUID).
      responses:
        '200':
          description: '200'
          content:
            application/json:
              examples:
                Result:
                  value:
                    subscription_code: c2094820-df10-4bd4-b7ef-dbe0d28db857
                    period:
                      start: '2026-09-15T15:54:32.436443Z'
                      end: '2026-10-15T15:54:32.272111Z'
                    currency: COP
                    items:
                      - meter_code: b7cb6aad-0fcc-4898-ae8b-f500ee6dfbb3
                        event_name: lifecycle_1789487669444
                        aggregation: SUM
                        quantity: 20
                        credits: 0
                        billable_quantity: 20
                        remaining_credits: 0
                        unit_price:
                          currency: COP
                          value: 500
                        amount:
                          currency: COP
                          value: 10000
                        events_count: 2
                        last_event_at: '2026-09-15T15:54:46.620383Z'
                    total:
                      currency: COP
                      value: 10000
              schema:
                type: object
                properties:
                  subscription_code:
                    type: string
                    example: c2094820-df10-4bd4-b7ef-dbe0d28db857
                  period:
                    type: object
                    description: El período de facturación actual de la suscripción.
                    properties:
                      start:
                        type: string
                        example: '2026-09-15T15:54:32.436443Z'
                      end:
                        type: string
                        example: '2026-10-15T15:54:32.272111Z'
                  currency:
                    type: string
                    example: COP
                  items:
                    type: array
                    description: >-
                      Una entrada por cada medidor asociado al plan de la
                      suscripción. Vacío cuando el plan no tiene medidores o la
                      suscripción no tiene plan.
                    items:
                      type: object
                      properties:
                        meter_code:
                          type: string
                        event_name:
                          type: string
                        aggregation:
                          type: string
                          description: 'SUM, COUNT o LAST: consulta Meters.'
                        quantity:
                          type: number
                          description: >-
                            La cantidad agregada informada para este medidor en
                            el período.
                        credits:
                          type: number
                          description: >-
                            Créditos incluidos consumidos contra la cantidad de
                            este medidor.
                        billable_quantity:
                          type: number
                          description: >-
                            La cantidad que realmente se factura después de
                            consumir los créditos.
                        remaining_credits:
                          type: number
                        unit_price:
                          type: object
                          properties:
                            currency:
                              type: string
                            value:
                              type: number
                        amount:
                          type: object
                          description: billable_quantity valorada a unit_price.
                          properties:
                            currency:
                              type: string
                            value:
                              type: number
                        events_count:
                          type: integer
                          description: >-
                            Cuántos eventos de uso se informaron para este
                            medidor en el período.
                        last_event_at:
                          type: string
                  total:
                    type: object
                    description: >-
                      La suma del monto de todos los ítems del período. Cero
                      cuando items está vacío.
                    properties:
                      currency:
                        type: string
                      value:
                        type: number
        '401':
          description: '401'
          content:
            application/json:
              examples:
                Invalid credentials:
                  value:
                    code: INVALID_CREDENTIALS
                    messages:
                      - Invalid Credentials
                  summary: Invalid credentials
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: INVALID_CREDENTIALS
                  messages:
                    type: array
                    items:
                      type: string
                      example: Invalid Credentials
        '404':
          description: '404'
          content:
            application/json:
              examples:
                NOT_FOUND:
                  value:
                    code: NOT_FOUND
                    messages:
                      - Subscription not found.
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: NOT_FOUND
                  messages:
                    type: array
                    items:
                      type: string
      deprecated: false
components:
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.