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

# Asociar medidor al plan

> Asocia un medidor a un plan existente como precio medido: créditos incluidos por ciclo más el precio por unidad adicional.

> [!NOTE]
>
> **Habilitado por organización**
>
> La facturación basada en uso debe estar habilitada para tu organización antes de que estos endpoints acepten solicitudes. Contacta a tu gerente de cuenta de Yuno para habilitarla. Las solicitudes de una organización que no la tiene habilitada devuelven `403 PRODUCT_NOT_ENABLED`.

El precio fijo del plan y el monto base de los suscriptores existentes nunca cambian cuando asocias un medidor. Cada suscripción del plan hereda el precio medido y puede empezar a reportar uso de inmediato.

> [!NOTE]
>
> **Dos formas de asociar**
>
> * **Al crear:** envía `meters[]` (con la misma estructura que el cuerpo de esta solicitud) a [Crear plan](https://docs.y.uno/es/reference/plans/create-plan.md). Las entradas de `meter_id` duplicadas se rechazan con `409`.
> * **En un plan activo:** llama a este endpoint una vez por medidor, o envía `{ "meters": [ ... ] }` a `PATCH /subscriptions/plans/{plan_id}`: ese PATCH solo permite asociar y es atómico: si alguna entrada de la lista no es válida (ya asociada, medidor desconocido o inactivo, precio incorrecto), no se asocia nada. Cualquier otro campo del plan en ese cuerpo (`name`, `base_amount`, …) se ignora sin aviso: los planes siguen siendo inmutables fuera de `meters[]`.

> [!NOTE]
>
> **Herencia de precio**
>
> Si la moneda base del plan es `USD` y el medidor tiene un `default_price`, puedes omitir `price_per_credit`: se aplica el valor predeterminado del medidor y el precio medido se devuelve con `price_per_credit: null`. En cualquier otro caso (la moneda de `price_per_credit` siempre debe ser igual a la moneda base del plan), envíalo de forma explícita. Solo se pueden asociar medidores `ACTIVE`; un medidor archivado se rechaza con `400 METER_NOT_FOUND`.

> [!NOTE]
>
> **Configuración de `pricing_strategy`**
>
> `PER_UNIT` usa `price_per_credit`/`country_prices`. `PACKAGE` usa `package_size`, `package_price` y, de forma opcional, `package_country_prices`. `TIERED` usa `tiers[]` (límites `up_to` ascendentes, el último nivel con `up_to: null`). Enviar campos de configuración de una estrategia distinta de la que seleccionaste se rechaza con `400 PLAN_METER_PRICING_CONFIG_UNSUPPORTED`. Una vez asociada, la configuración `PACKAGE`/`TIERED` no se puede cambiar: consulta [Actualizar medidor del plan](https://docs.y.uno/reference/meters/update-plan-meter).

Consulta [El objeto de precio medido](https://docs.y.uno/reference/meters/the-metered-price-object) para ver todos los campos. Revisa [Códigos de error de medidores](https://docs.y.uno/reference/meters/meter-error-codes) para conocer los posibles resultados de error.


## OpenAPI

````yaml openapi/es/meters/attach-meter-to-plan.json POST /subscriptions/plans/{plan_id}/meters
openapi: 3.1.0
info:
  title: meters
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /subscriptions/plans/{plan_id}/meters:
    post:
      summary: Asociar medidor a un plan
      description: >-
        La facturación por uso debe estar habilitada para tu organización antes
        de que este endpoint acepte solicitudes (de lo contrario, `403
        PRODUCT_NOT_ENABLED`). Asocia un medidor a un plan existente como precio
        medido: cuántas unidades se incluyen por ciclo (`credits`) y cuánto
        cuesta cada unidad adicional. Asociarlo no cambia el precio fijo del
        plan ni el monto base de ningún suscriptor existente. También puedes
        asociar medidores en línea con `meters[]` al llamar a Create Plan.
      operationId: attach-meter-to-plan
      parameters:
        - in: header
          name: X-Account-Code
          required: true
          schema:
            type: string
          description: >-
            El `account_id` que se encuentra en tu [Yuno
            Dashboard](https://dashboard.y.uno/developers) (UUID). Obligatorio:
            si lo omites, se devuelve `400 BAD_REQUEST` ("Invalid x-account-code
            header.").
        - name: plan_id
          in: path
          required: true
          description: El identificador único del plan.
          schema:
            type: string
        - in: header
          name: X-Idempotency-Key
          required: true
          schema:
            type: string
          description: >-
            Identificador único usado en los encabezados HTTP para garantizar
            que una solicitud se procese una sola vez, incluso si se reintenta
            por problemas de red o tiempos de espera agotados. Es opcional,
            igual que en el resto de la API de Yuno.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                meter_id:
                  type: string
                  description: >-
                    El identificador único del medidor que se va a asociar (MAX
                    64; MIN 36). Debe ser un medidor `ACTIVE` existente de la
                    cuenta: un medidor desconocido o `INACTIVE` se rechaza con
                    `400 METER_NOT_FOUND`. Un medidor solo se puede asociar a un
                    plan una vez; de lo contrario, `409
                    PLAN_METER_ALREADY_ASSIGNED`.
                credits:
                  type: integer
                  description: >-
                    Unidades incluidas en el plan por ciclo de facturación: la
                    cantidad que un suscriptor puede consumir antes de que se
                    facture cualquier uso. Debe ser >= 0. `0` significa que se
                    factura cada unidad.
                pricing_strategy:
                  type: string
                  enum:
                    - PER_UNIT
                    - PACKAGE
                    - TIERED
                  description: >-
                    Cómo se calcula el precio del uso que excede `credits`:
                    `PER_UNIT` (unidades facturables × `price_per_credit`),
                    `PACKAGE` (paquetes de N unidades; un paquete parcial cuenta
                    como uno completo) o `TIERED` (niveles graduados, cada tramo
                    con su propia tarifa).
                price_per_credit:
                  type: object
                  required:
                    - currency
                    - value
                  properties:
                    currency:
                      type: string
                      description: >-
                        MAX 3; MIN 3. Debe ser igual a la moneda de
                        `base_amount` del plan; de lo contrario, `400
                        INVALID_PARAMETERS`.
                    value:
                      type: number
                      format: float
                      description: >-
                        Precio por unidad por encima de los créditos incluidos
                        (múltiplo de 0.0001). Es opcional solo cuando la moneda
                        base del plan es `USD` y el medidor tiene un
                        `default_price`: en ese caso se aplica el valor por
                        defecto del medidor y el precio medido se devuelve con
                        `price_per_credit: null`. En los demás casos es
                        obligatorio.
                country_prices:
                  type: array
                  description: >-
                    Precio explícito opcional por unidad para cada país. Una
                    entrada por país: un país repetido se rechaza con `400
                    INVALID_PARAMETERS`. Un país que no figure en la lista usa
                    `price_per_credit`.
                  items:
                    type: object
                    required:
                      - country
                      - amount
                    properties:
                      country:
                        type: string
                        description: >-
                          MAX 2; MIN 2; [ISO
                          3166-1](/es/reference/country-reference).
                      amount:
                        type: object
                        required:
                          - currency
                          - value
                        properties:
                          currency:
                            type: string
                            description: >-
                              MAX 3; MIN 3; [ISO
                              4217](/es/reference/country-reference).
                          value:
                            type: number
                            format: float
                            description: Múltiplo de 0.0001.
                package_size:
                  type: number
                  format: float
                  description: >-
                    Solo para `pricing_strategy: PACKAGE`. El tamaño del
                    paquete: las unidades facturables se redondean hacia arriba
                    al múltiplo entero más cercano. Debe ser > 0; se aceptan
                    decimales y notación científica (`1e3`) y se convierten. Se
                    almacena redondeado a 4 decimales. Obligatorio cuando
                    `pricing_strategy` es `PACKAGE`; se rechaza con `400
                    PLAN_METER_PRICING_CONFIG_UNSUPPORTED` para cualquier otra
                    estrategia.
                package_price:
                  type: object
                  description: >-
                    Solo para `pricing_strategy: PACKAGE`. El precio por
                    paquete. Mismo formato que `price_per_credit`. Obligatorio
                    cuando `pricing_strategy` es `PACKAGE`.
                  properties:
                    currency:
                      type: string
                      description: >-
                        MAX 3; MIN 3. Debe ser igual a la moneda de
                        `base_amount` del plan.
                    value:
                      type: number
                      format: float
                package_country_prices:
                  type: array
                  description: >-
                    Solo para `pricing_strategy: PACKAGE`. Precio opcional por
                    paquete según el país del suscriptor. Mismo formato que
                    `country_prices`.
                  items:
                    type: object
                    properties:
                      country:
                        type: string
                        description: MAX 2; MIN 2; ISO 3166-1.
                      amount:
                        type: object
                        properties:
                          currency:
                            type: string
                          value:
                            type: number
                            format: float
                tiers:
                  type: array
                  description: >-
                    Solo para `pricing_strategy: TIERED`. Tramos de precio
                    graduados y ordenados. Obligatorio cuando `pricing_strategy`
                    es `TIERED` (al menos una entrada). Cada nivel, excepto el
                    último, necesita un `up_to` estrictamente ascendente; el
                    `up_to` del último nivel debe ser `null` (sin límite). Todos
                    los niveles deben compartir la misma moneda (y los mismos
                    países de `country_rates`, si se usan).
                  items:
                    type: object
                    properties:
                      up_to:
                        type: number
                        format: float
                        description: >-
                          Límite superior inclusivo del tramo de unidades
                          facturables de este nivel, o `null` en el último nivel
                          (sin límite).
                      rate:
                        type: object
                        description: >-
                          Precio por unidad dentro de este tramo. Mismo formato
                          que `price_per_credit`.
                        properties:
                          currency:
                            type: string
                          value:
                            type: number
                            format: float
                      country_rates:
                        type: array
                        description: >-
                          Reemplazo opcional de `rate` por país para este nivel.
                          Mismo formato que `country_prices`.
                        items:
                          type: object
                          properties:
                            country:
                              type: string
                            amount:
                              type: object
                              properties:
                                currency:
                                  type: string
                                value:
                                  type: number
                                  format: float
              required:
                - meter_id
                - credits
                - pricing_strategy
            examples:
              Metered price:
                value:
                  meter_id: 66666666-6666-6666-6666-666666666666
                  credits: 100
                  pricing_strategy: PER_UNIT
                  price_per_credit:
                    currency: USD
                    value: 0.05
                  country_prices:
                    - country: US
                      amount:
                        currency: USD
                        value: 0.06
              Inherit meter default_price (USD plan):
                summary: >-
                  USD plan — price inherited from the meter's default_price
                  (returned as null)
                value:
                  meter_id: 55555555-5555-5555-5555-555555555555
                  credits: 10000
                  pricing_strategy: PER_UNIT
      responses:
        '201':
          description: '201'
          content:
            application/json:
              examples:
                Result:
                  value:
                    id: 77777777-7777-7777-7777-777777777777
                    plan_id: 00000000-0000-4000-8000-000000000001
                    meter_id: 66666666-6666-6666-6666-666666666666
                    credits: 100
                    pricing_strategy: PER_UNIT
                    price_per_credit:
                      currency: USD
                      value: 0.05
                    country_prices:
                      - country: US
                        amount:
                          currency: USD
                          value: 0.06
                    created_at: '2026-08-18T09:00:04.000000Z'
                    updated_at: '2026-08-18T09:00:04.000000Z'
                    package_size: null
                    package_price: null
                    package_country_prices: []
                    tiers: []
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: >-
                      El identificador único del precio medido (la relación
                      plan-medidor).
                  plan_id:
                    type: string
                  meter_id:
                    type: string
                  credits:
                    type: integer
                    description: Unidades incluidas en el plan por ciclo de facturación.
                  pricing_strategy:
                    type: string
                    enum:
                      - PER_UNIT
                      - PACKAGE
                      - TIERED
                  price_per_credit:
                    type: object
                    nullable: true
                    description: >-
                      `null` cuando se hereda del `default_price` del medidor
                      (planes en USD).
                    properties:
                      currency:
                        type: string
                      value:
                        type: number
                  country_prices:
                    type: array
                    items:
                      type: object
                      properties:
                        country:
                          type: string
                        amount:
                          type: object
                          properties:
                            currency:
                              type: string
                            value:
                              type: number
                  created_at:
                    type: string
                    description: Lo establece Yuno al crearlo.
                  updated_at:
                    type: string
                    description: Lo establece Yuno en cada actualización.
                  package_size:
                    type: integer
                    nullable: true
                    description: null cuando el medidor no se vende en paquetes
                  package_price:
                    type: number
                    nullable: true
                    description: null cuando el medidor no se vende en paquetes
                  package_country_prices:
                    type: array
                    items:
                      type: object
                      properties:
                        country:
                          type: string
                        amount:
                          type: object
                          properties:
                            currency:
                              type: string
                            value:
                              type: number
                    description: Precios por país del paquete.
                  tiers:
                    type: array
                    items: {}
                    description: Niveles.
        '400':
          description: '400'
          content:
            application/json:
              examples:
                Currency mismatch:
                  summary: Currency mismatch
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The price_per_credit currency must match the plan base
                        currency
                Missing price on non-USD plan:
                  summary: Missing price on non-USD plan
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        A price_per_credit is required when the plan base
                        currency is not USD
                Missing price and no default:
                  summary: Missing price and no default
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        A price_per_credit is required when the meter has no
                        default_price
                Negative credits:
                  summary: Negative credits
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The meter credits must be greater than or equal to 0
                Invalid strategy:
                  summary: Invalid strategy
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - >-
                        The meter pricing_strategy must be one of PER_UNIT,
                        PACKAGE, TIERED
                Duplicate country:
                  summary: Duplicate country
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The country_prices must not contain duplicate countries
                Unknown or inactive meter:
                  summary: Unknown or inactive meter
                  value:
                    code: METER_NOT_FOUND
                    messages:
                      - >-
                        The meter does not exist, is inactive or is not linked
                        to this account.
                Unknown plan:
                  summary: Unknown plan
                  value:
                    code: PLAN_NOT_FOUND
                    messages:
                      - >-
                        The plan does not exist or is not linked to this
                        account.
              schema:
                type: object
                properties:
                  code:
                    type: string
                  messages:
                    type: array
                    items:
                      type: string
        '403':
          description: '403'
          content:
            application/json:
              examples:
                Product not enabled:
                  summary: Product not enabled
                  value:
                    code: PRODUCT_NOT_ENABLED
                    messages:
                      - Usage-based billing is not enabled for this organization
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: PRODUCT_NOT_ENABLED
                  messages:
                    type: array
                    items:
                      type: string
        '409':
          description: '409'
          content:
            application/json:
              examples:
                Result:
                  value:
                    code: PLAN_METER_ALREADY_ASSIGNED
                    messages:
                      - >-
                        The meter 66666666-6666-6666-6666-666666666666 is
                        already assigned to this plan
              schema:
                type: object
                properties:
                  code:
                    type: string
                  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.