amount/frequency en cada suscripción que creas, suscribe al cliente a un plan y Yuno resuelve automáticamente el precio para su país.
Planes frente a suscripciones sin planLas suscripciones sin plan (
amount + frequency, sin plan_id) siguen siendo totalmente compatibles: los planes son un complemento, no un reemplazo. Una suscripción creada sin plan simplemente omite los campos del plan (plan_id, billing_phases, current_phase, …) de sus respuestas: están ausentes, no son null.Crear y usar un plan
Supón que lanzas un nivel “Streaming Pro” que cuesta $20/mes en Estados Unidos, pero quieres cobrar R$99.90 en Brasil en lugar de una conversión directa de moneda. Este es el flujo completo:- Crea el plan una sola vez. Llama a Create a Plan con un nombre, un
base_amount(el precio por defecto, $20 USD en nuestro ejemplo), unafrequency(mensual) y, si necesitas precios específicos por país, una listacountry_prices(BR→ R$99.90). Esto te devuelve unplan_id. - Suscribe a tantos clientes como quieras. Cuando llames a Create Subscription, envía ese
plan_iden lugar de unamount. Yuno busca elcountrydel suscriptor y le cobra automáticamente el precio correcto, sin que tengas que calcular ni enviar el monto en cada suscripción. - El precio se resuelve por suscriptor, en este orden: ¿el plan tiene un precio explícito para su país? Se usa ese. Si no, se recurre a
base_amount. Así, en nuestro ejemplo, un cliente de Estados Unidos paga $20, un cliente de Brasil paga R$99.90 y un cliente de cualquier otro lugar también paga $20 (elbase_amountde respaldo cubre todos los países que no listaste explícitamente).
Los planes son inmutables: por qué es importante
No puedes editar el precio de un plan después de crearlo: no existe un endpoint de actualización. Esto es deliberado: significa que cada suscriptor conserva para siempre el precio exacto con el que se suscribió, incluso si más adelante cambias tus precios. Nadie recibe un aumento de precio inesperado porque modificaste el plan. En la práctica, esto significa que un “cambio de precio” es en realidad “crear un nuevo plan”: si Streaming Pro pasa de $20 a $25/mes, creas un nuevo plan por $25 y diriges a él las nuevas altas; tus suscriptores actuales de $20 siguen pagando $20 hasta que los migres o cancelen. Para migrar a los suscriptores existentes al nuevo plan, usa Change Subscription Plan (inmediato, pero reemplaza la suscripción con un nuevoid) o el objeto plan_change en Update Subscription, que conserva el mismo id: se programa para la próxima renovación por defecto, o se aplica de inmediato con "effective": "IMMEDIATE", y opcionalmente reinicia el ancla de facturación con billing_cycle_behavior: RESTART. Cuando estés listo para dejar de ofrecer el precio anterior por completo, consulta Cancelar un plan más abajo.
Fases de prueba: ofrece un período inicial con descuento o gratuito
Si quieres que los nuevos suscriptores paguen menos (o nada) durante un tiempo antes de que entre en vigor el precio regular, como una prueba gratuita de 14 días o $9.99/mes durante los primeros 3 meses antes de pasar a $20/mes, para eso sirven lasphases del plan.
Piénsalo como una escalera corta que recorre el suscriptor: uno o más pasos TRIAL (con el precio que quieras, incluido $0), seguidos de exactamente un paso REGULAR al final, que siempre se cobra según el base_amount/country_prices normales del plan. Por ejemplo, un plan de 3 meses y luego regular tiene dos fases: la fase 1 es TRIAL, 3 meses, $9.99; la fase 2 es REGULAR sin duración definida: simplemente se ejecuta al precio normal del plan a partir de ese momento.
Mientras un suscriptor está dentro de una fase TRIAL, el status de su suscripción es TRIALING (en lugar de ACTIVE) y current_phase es TRIAL, así puedes saber de un vistazo que todavía está en el período con descuento. En cuanto llega a la fase REGULAR, ambos cambian automáticamente: status pasa a ACTIVE y current_phase pasa a REGULAR, sin que tengas que hacer nada.
Si no necesitas una prueba ni un descuento inicial, simplemente omite phases: el plan cobra su precio regular desde la primera factura.
Consulta The Plan Object para ver todos los campos de una fase y The Subscription Object para ver cómo una suscripción informa en qué fase está (plan_id, billing_phases, current_phase). Para ver qué se cobró realmente en cada fase (proveedor, montos por cobro, a qué fase pertenecía un pago), usa List Subscription Payments.
Cancelar un plan
Esto cancela de inmediato a todos los suscriptores del plan: no hay forma de evitarlo.Llamar a Cancel Plan hace dos cosas a la vez, de forma síncrona, en la misma solicitud:
- Impide que nuevos clientes se suscriban a este plan.
- Cancela todas las suscripciones que tiene actualmente, ahora mismo. No “en su próxima renovación”, ni “después de un período de gracia”: de inmediato, como parte de esta misma llamada a la API.
subscribers_count del plan (mediante List Plans; este campo no está en la respuesta de Retrieve Plan de un solo plan) para saber exactamente cuántas suscripciones activas están a punto de cancelarse. La respuesta también devuelve affected_subscriptions para que puedas confirmar después que el número coincide con lo que esperabas.
Si no estás seguro de que una llamada de cancelación anterior haya terminado de cancelar a todos los suscriptores, puedes volver a llamarla sin riesgo: volver a cancelar un plan ya cancelado vuelve a ejecutar la cascada y devuelve
200, no genera un error.