Skip to main content
Habilitado por organizaciónLa facturación basada en el 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 donde no está habilitada devuelven 403 PRODUCT_NOT_ENABLED.
Las suscripciones cobran un precio fijo con una periodicidad fija. La facturación basada en el uso agrega una parte variable encima: le indicas a Yuno qué contar (un medidor), cuánto de eso incluye un plan y cuánto cuestan las unidades adicionales (un precio medido), y luego reportas cuánto consumió cada suscriptor (eventos de uso). Yuno agrega el uso por suscripción y ciclo de facturación, y cobra lo que supere la cuota incluida junto con el cargo de renovación habitual de la suscripción. Usos típicos: un producto de IA que incluye 10,000 tokens al mes y cobra el resto por token, una API que incluye 1,000 solicitudes y cobra cada llamada adicional, un producto de almacenamiento que se cobra por gigabyte almacenado.

Cómo encajan las piezas

  1. Medidor: una acción con nombre y contable: ai_tokens, api_request, storage_gb. Define el event_name que envían tus sistemas y la agregación (SUM, COUNT o LAST). Un medidor no tiene precio propio, como máximo un default_price en USD que los planes pueden heredar. Consulta El objeto Meter.
  2. Precio medido: el medidor asociado a un plan: cuántas unidades se incluyen por ciclo (credits) y cuánto cuesta cada unidad adicional (price_per_credit, opcionalmente por país). Un plan puede tener cualquier cantidad de precios medidos junto a su precio fijo. Consulta El objeto Metered Price.
  3. Suscripción: se crea en ese plan como de costumbre. Hereda todos los precios medidos; nada cambia en Crear suscripción.
  4. Eventos de uso: una llamada por unidad de trabajo, con el event_name, el subscription_id, un value y tu propio event_id para la idempotencia. Consulta Reportar evento de uso.
  5. Renovación: al final del ciclo de facturación, Yuno calcula la cantidad facturable (max(0, usage − credits)) y suma billable × price_per_credit al cargo de renovación de la suscripción.
Los medidores son genéricosNada de esto es específico de la IA. Un medidor puede contar entregas, minutos, mensajes, asientos o gigabytes igual que tokens: unit_label / plural_unit_label del medidor son las etiquetas con las que se muestra el uso.

Inicio rápido

El ejemplo crea un plan “Max” de $200 al mes que incluye 10,000 tokens de IA y cobra $0.002 por cada token adicional. Las solicitudes usan los encabezados estándar public-api-key / private-secret-key. X-Idempotency-Key se acepta en todas las solicitudes, como en el resto de la API de Yuno, pero los eventos de uso tienen su propia clave de deduplicación dedicada: consulta Idempotencia y marcas de tiempo.
1

Crea el medidor

Elige un event_name que enviarán tus sistemas (minúsculas, se permiten _ y .) y la agregación. default_price es opcional y debe estar en USD; te evita repetir el precio unitario en cada plan en USD.
La respuesta es 201 con el medidor, siempre ACTIVE. Conserva su id: lo necesitas para asociar el medidor a un plan.
2

Asócialo a un plan

Crea el plan con el medidor en línea, o asócialo a un plan que ya existe. Ambos reciben el mismo cuerpo de precio medido: meter_id, credits (unidades incluidas por ciclo), pricing_strategy y, si no se hereda, price_per_credit.
En el ejemplo “New plan” se omite price_per_credit: el plan es en USD y el medidor tiene un default_price, por lo que se aplica $0.002 y el precio medido se devuelve con price_per_credit: null. La respuesta del plan y Consultar plan ahora incluyen el precio medido en meters[] (un arreglo vacío en los planes sin medidores).
Asociar un medidor a un plan activo no cambia el precio fijo del plan ni el monto base de ningún suscriptor existente: solo agrega una línea variable para el uso que supere credits. Enviar { "meters": [ ... ] } a PATCH /subscriptions/plans/{plan_id} hace lo mismo para varios medidores a la vez, de forma atómica (si una entrada es incorrecta, no se asocia ninguna), e ignora todos los demás campos del plan.
3

Suscribe a tus clientes al plan

No hay nada nuevo aquí: llama a Crear suscripción con el plan_id. La suscripción hereda los precios medidos del plan. Guarda el id de la suscripción: todos los eventos de uso lo referencian.
4

Reporta el uso a medida que ocurre

Envía un evento por unidad de trabajo. event_id es tu clave de idempotencia; value es obligatorio para los medidores SUM y LAST, y su valor predeterminado es 1 para COUNT. La suscripción debe estar ACTIVE, TRIALING o PAST_DUE.
Una respuesta 201 confirma que el evento se validó y se almacenó:
Reintentar la misma solicitud (mismo event_id) devuelve esta misma respuesta y nunca cuenta los 1,500 tokens dos veces: aunque el reintento lleve un value distinto, se conserva el original.

Cómo elegir una agregación

La agregación se fija al crear el medidor y determina qué significa la cantidad de un ciclo:
Suma el value de cada evento. Reporta la cantidad consumida por cada unidad de trabajo.
Tres eventos de 1,280 / 640 / 2,100 tokens → cantidad del ciclo: 4,020 tokens. Úsalo para tokens, minutos transcritos, mensajes enviados, entregas completadas.

Cómo fijar el precio de un medidor en un plan

Un precio medido tiene tres parámetros de precio:
  • credits: las unidades incluidas en el plan en cada ciclo de facturación. Piénsalo como una “cuota”: las primeras credits unidades quedan cubiertas por el precio fijo del plan. 0 factura todas las unidades. credits se mide en la unidad del medidor (tokens, solicitudes, GB) y se reinicia en cada ciclo: no es un saldo prepagado ni una billetera.
  • price_per_credit: el precio de cada unidad que supera credits, en la moneda base del plan. En un plan en USD puedes omitirlo si el medidor tiene un default_price; entonces se aplica el valor predeterminado del medidor y el precio medido se devuelve con price_per_credit: null. En un plan que no está en USD, o cuando el medidor no tiene valor predeterminado, es obligatorio. La moneda siempre debe coincidir con la moneda de base_amount del plan.
  • country_prices: precios por unidad opcionales según el país del suscriptor (una entrada por país), con la misma forma que los country_prices del propio plan. Un suscriptor cuyo país no figura en la lista paga price_per_credit. El país del suscriptor proviene de la suscripción (los eventos de uso no llevan country ni account_id), por lo que country_prices se resuelve automáticamente por suscriptor.
pricing_strategy define cómo se tarifica el excedente, y cada estrategia tiene sus propios campos de configuración al momento de asociar:
Unidades facturables × price_per_credit (o la entrada de country_prices del suscriptor). La opción predeterminada para tokens, solicitudes y minutos.
En las estrategias distintas de PER_UNIT, el medidor debe tener precio en cada moneda que admite el plan: se rechaza un plan con country_prices en monedas que el precio medido no cubre (PLAN_METER_MISSING_CURRENCY), y cada moneda con precio debe coincidir con una que el plan realmente use (PLAN_METER_BASE_CURRENCY_MISMATCH). Todos los montos de uso calculados (con cualquier estrategia) se redondean half-up a 4 decimales.
La configuración de precios se define una sola vez, al asociar. credits, price_per_credit y country_prices se pueden actualizar en un precio medido PER_UNIT activo con Actualizar medidor del plan: los nuevos valores se aplican al uso tarifado a partir del siguiente ciclo de facturación. package_size, package_price, package_country_prices y tiers no se pueden cambiar después de asociar: al cambiar el pricing_strategy de un precio medido se valida que la solicitud incluya la configuración obligatoria de la estrategia de destino y se borran los campos de la estrategia anterior que ya no aplican; un cambio sin configuración, o con la configuración de otra estrategia, se rechaza. No existe un endpoint para desasociar, así que para corregir una configuración PACKAGE/TIERED no puedes volver a asociar el mismo medidor: crea un medidor nuevo con un event_name nuevo, asócialo con la configuración corregida, apunta tu integración al nuevo event_name y archiva el medidor anterior. El precio fijo del plan sigue siendo inmutable como antes.

Qué ocurre en la renovación

El uso se factura en el cargo de renovación de la suscripción, junto con el precio fijo del plan: no hay una factura de uso aparte.
Para cada suscripción y cada precio medido de su plan, al final del ciclo de facturación:
  1. Cantidad: los eventos cuyo occurred_at cae dentro del ciclo se agregan con la aggregation del medidor (SUM / COUNT / LAST).
  2. Unidades facturables: max(0, quantity − credits). Los créditos sin usar no se acumulan.
  3. Monto: billable × price_per_credit (o la entrada de country_prices del suscriptor).
  4. Cargo: el monto se suma al cargo de renovación de la suscripción junto con el precio fijo del plan. Un cargo, un pago, como hasta ahora. Una suscripción con un uso inferior a sus créditos paga solo el precio fijo.
Ejemplo, en el plan Max (10,000 tokens incluidos, $0.002 por token adicional): un suscriptor consume 13,500 tokens en agosto → 3,500 facturables → $7.00 de uso, por lo que la renovación cobra $207.00. Otro suscriptor consume 8,000 → $200.00.

Idempotencia y marcas de tiempo

  • event_id es obligatorio y es tu clave de idempotencia. Hazlo único por evento (un UUID, o el id de la solicitud, respuesta o tarea de la que proviene) y reutilízalo en cada reintento. Yuno almacena el primer evento con ese id y responde a cada repetición con la misma respuesta, incluido el value original (un value distinto en el reintento se descarta). El uso nunca se cuenta dos veces, sin importar cuántas veces reintentes. Una solicitud sin event_id se rechaza con 400.
  • Reporta lo más cerca posible del tiempo real, aunque puedes registrar eventos con fecha anterior. occurred_at toma por defecto la hora de recepción (devuelta como received_at) y puede ser hasta 35 días anterior; los eventos más antiguos se rechazan con 400. occurred_at (no la hora de recepción) decide en qué ciclo de facturación cae el evento.
  • X-Idempotency-Key se acepta, como en el resto de la API de Yuno (misma clave + mismo cuerpo → misma respuesta), pero aquí es opcional y no es lo que deduplica el uso: event_id es el mecanismo que protege la facturación, y es el único obligatorio.
  • Un evento por solicitud. Agrega en tu lado si generas muchos eventos pequeños (por ejemplo, suma los tokens por respuesta en lugar de por token): un medidor SUM está pensado para eso.
  • La suscripción debe estar activa. Las suscripciones ACTIVE, TRIALING y PAST_DUE aceptan uso (una suscripción en reintentos de pago sigue midiendo); los eventos de una suscripción PAUSED, CANCELED o COMPLETED se rechazan con 400 SUBSCRIPTION_NOT_ACTIVE y no se cuenta nada.

Manejo de errores

La validación es síncrona: un evento rechazado devuelve 400 de inmediato (los fallos de búsqueda también son 400, nunca 404) y no se cuenta, así que trata cualquier respuesta distinta de 201 como “no registrado” y reintenta con el mismo event_id después de corregir la solicitud. Los códigos que encontrarás con más frecuencia: La lista completa, con todos los mensajes, está en Códigos de error de medidores.

Preguntas frecuentes

No. Asocia el medidor al plan activo con Asociar medidor a un plan (o con el PATCH /subscriptions/plans/{plan_id} solo de asociación con meters[]). El precio fijo y el monto base de los suscriptores existentes no cambian; el uso que supere credits empieza a facturarse en su siguiente renovación.
Sí, cualquier cantidad: por ejemplo tokens (SUM) más solicitudes a la API (COUNT) más almacenamiento (LAST), cada uno con sus propios credits y precio unitario. Cada medidor se puede asociar una sola vez a un plan determinado.
Ninguno de los dos. credits se aplica por suscripción, por medidor y por ciclo de facturación. Dos suscriptores del mismo plan reciben cada uno la cuota completa; los créditos sin usar no se acumulan.
El evento se valida solo contra el medidor y la suscripción, por lo que se acepta y se almacena, pero únicamente el uso asociado a un precio medido del plan de la suscripción se tarifica y se factura. Revisa meters[] del plan si el uso no aparece en la renovación.
No: ambos son inmutables porque tus sistemas y los eventos pasados dependen de ellos; un PATCH que los incluya se ignora en silencio. Crea un medidor nuevo (con un event_name nuevo: los nombres quedan reservados incluso después de archivar) y archiva el anterior con Actualizar medidor (status: INACTIVE). Los medidores archivados rechazan eventos nuevos con 400 METER_NOT_FOUND, no se pueden asociar a planes y sus precios medidos existentes quedan congelados; puedes reactivar uno en cualquier momento con status: ACTIVE.
No existe un endpoint para desasociar. Archiva el medidor para detener la ingesta, o aumenta credits para que no se facture excedente.
Sí, por plan. El default_price del medidor es solo en USD, pero un precio medido en un plan en BRL recibe price_per_credit en BRL (obligatorio: no se hereda nada en los planes que no están en USD), y country_prices te permite fijar precios unitarios por país en la moneda de cada país.
El evento se rechaza con 400 SUBSCRIPTION_NOT_ACTIVE y no se cuenta nada: solo las suscripciones ACTIVE, TRIALING y PAST_DUE aceptan uso. Reanuda primero la suscripción (Reanudar suscripción) y luego reporta el uso; puedes registrar occurred_at con fecha anterior hasta 35 días.
No. Cada evento necesita un subscription_id; el uso se factura en la renovación de esa suscripción.

Leer el uso

Llama a Consultar uso de la suscripción para leer lo que una suscripción ha acumulado en su período de facturación actual antes de que la renovación lo tarife: un elemento por medidor, con la cantidad facturable, el precio unitario y el monto resultante, además de un total del período. Una suscripción cuyo plan no tiene medidores devuelve un arreglo items vacío y un total de cero. El reporte de uso es asíncrono, por lo que una lectura realizada poco después de reportar un evento puede ir por detrás.

Referencia