Skip to main content
POST
Habilitado por organizaciónLa 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.
Dos formas de asociar
  • Al crear: envía meters[] (con la misma estructura que el cuerpo de esta solicitud) a Crear plan. 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[].
Herencia de precioSi 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.
Configuración de pricing_strategyPER_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.
Consulta El objeto de precio medido para ver todos los campos. Revisa Códigos de error de medidores para conocer los posibles resultados de error.

Authorizations

public-api-key
string
header
default:<Your public-api-key>
required
private-secret-key
string
header
default:<Your private-secret-key>
required

Headers

X-Account-Code
string
required

El account_id que se encuentra en tu Yuno Dashboard (UUID). Obligatorio: si lo omites, se devuelve 400 BAD_REQUEST ("Invalid x-account-code header.").

X-Idempotency-Key
string
required

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.

Path Parameters

plan_id
string
required

El identificador único del plan.

Body

application/json
meter_id
string
required

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
integer
required

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
enum<string>
required

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

Available options:
PER_UNIT,
PACKAGE,
TIERED
price_per_credit
object
country_prices
object[]

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.

package_size
number<float>

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
object

Solo para pricing_strategy: PACKAGE. El precio por paquete. Mismo formato que price_per_credit. Obligatorio cuando pricing_strategy es PACKAGE.

package_country_prices
object[]

Solo para pricing_strategy: PACKAGE. Precio opcional por paquete según el país del suscriptor. Mismo formato que country_prices.

tiers
object[]

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

Response

201

id
string

El identificador único del precio medido (la relación plan-medidor).

plan_id
string
meter_id
string
credits
integer

Unidades incluidas en el plan por ciclo de facturación.

pricing_strategy
enum<string>
Available options:
PER_UNIT,
PACKAGE,
TIERED
price_per_credit
object | null

null cuando se hereda del default_price del medidor (planes en USD).

country_prices
object[]
created_at
string

Lo establece Yuno al crearlo.

updated_at
string

Lo establece Yuno en cada actualización.

package_size
integer | null

null cuando el medidor no se vende en paquetes

package_price
number | null

null cuando el medidor no se vende en paquetes

package_country_prices
object[]

Precios por país del paquete.

tiers
any[]

Niveles.