Créditos que se acumulan y se recargan, trials sin tarjeta y Dub

Octubre fue de créditos y planes: créditos que se acumulan, se dosifican y se recargan solos, trials que arrancan sin tarjeta, un plan por defecto al que volver y códigos de partners de Dub. Este post también cubre lo que salió desde el SDK 9 y nunca tuvo su anuncio. Cada funcionalidad viene con el caso que resuelve, un antes y después, y el código para activarla.

Las primeras cuatro funcionalidades son para planes de créditos. Los planes de balance siguen con su recarga manual y los planes medidos funcionan como antes. Todo lo que viene después sirve para cualquier plan.

Conservá los créditos que el cliente no usó#

Cuándo sirve: vendés un plan con 1.000 créditos por mes y el uso de tus clientes cambia de un mes a otro. Un cliente que usa 400 ve desaparecer 600 en el reinicio. Acumularlos le conserva lo que pagó, y un máximo limita cuánto saldo sin usar arrastrás.

• Configurá unusedPlanCredits en un plan de créditos como roll_over. Vencer sigue siendo el valor por defecto.

• maxPlanCredits limita el total que tiene una suscripción después del reinicio, incluidos los créditos que ese reinicio otorga. Lo que pasa del máximo vence y dispara credits.expired.

• Las suscripciones existentes aplican el cambio desde su próximo reinicio. Los créditos comprados no vencen nunca.

await commet.plans.update({
  id: "plan_pro",
  unusedPlanCredits: { type: "roll_over", maxPlanCredits: 2000 },
});

Que un mal día no se gaste el mes#

Cuándo sirve: un agente trabado en un loop, una API key filtrada o un script mal escrito pueden gastar los créditos de un mes en una tarde. Un límite diario o semanal dosifica los créditos del plan para que duren el período, y tu app recibe un error claro en vez de un saldo en cero.

• planCreditLimit recibe una cantidad de créditos y un intervalo, day o week. Las ventanas siguen el ciclo de facturación de la suscripción.

• Pasado el límite, el uso devuelve 402 plan_credit_limit_reached hasta la próxima ventana. La verificación de uso informa cuánto se gastó, cuánto queda y cuándo se reinicia la ventana.

• El límite solo cuenta los créditos del plan. Los créditos que el cliente compró siguen funcionando cuando se alcanza el límite.

await commet.plans.update({
  id: "plan_pro",
  planCreditLimit: { credits: 200, interval: "day" },
});

Vendé exactamente los créditos que el cliente necesita#

Cuándo sirve: un cliente necesita 750 créditos para terminar un trabajo y tus paquetes son de 500. O compra dos veces o paga créditos que no necesitaba. Con un precio por crédito en el plan, compra 750.

• Definí un precio por crédito y una cantidad mínima opcional en el plan. El cliente compra cualquier cantidad entera desde el mínimo.

• La compra se cobra al medio de pago guardado y suma créditos comprados, que no vencen. El cliente también puede comprar desde el portal. Los paquetes de créditos siguen funcionando como antes.

await commet.subscriptions.purchaseCredits({
  id: "sub_123",
  quantity: 750,
});

Que los procesos largos no se queden sin créditos#

Cuándo sirve: los agentes y los procesos por lotes corren cuando nadie mira. Si los créditos se terminan a las 2 de la mañana, el proceso se corta y el cliente se entera a la mañana. La recarga automática compra más cuando el saldo baja, dentro de un límite por período.

• Cuando el saldo llega a threshold, Commet compra quantity créditos con el medio de pago guardado, como máximo maxPerPeriod veces por período. Cada compra dispara credits.purchased.

• Usa el precio por crédito y el mínimo del plan. Después de tres pagos fallidos seguidos se pausa; guardarla activada de nuevo la reanuda.

• La configurás por suscripción, y el cliente la puede activar desde el portal.

await commet.subscriptions.updateAutoTopUp({
  id: "sub_123",
  enabled: true,
  threshold: 100,
  quantity: 500,
  maxPerPeriod: 3,
});

const autoTopUp = await commet.subscriptions.getAutoTopUp({ id: "sub_123" });
// autoTopUp.status: "active" | "paused" | "off"

Leé sobre modelos de consumo y compra de créditos.

Que prueben antes de pedirles una tarjeta#

Cuándo sirve: alguien se registra para probar tu producto y la primera pantalla le pide una tarjeta. Ahora un precio puede arrancar su trial sin tarjeta, así la gente prueba primero y decide después.

• Los trials ahora viven en el precio del plan, de 1 a 730 días. Con trialRequiresPaymentMethod: false, la suscripción arranca en trial sin checkout.

• Un trial que termina sin tarjeta pasa al plan por defecto del grupo, o se cancela con trial_ended_without_payment_method si el grupo no tiene uno. Cada cliente tiene un trial por plan.

• Las Offers ahora son solo descuentos. Crear una Offer con una fase free_trial devuelve 400; el trial se configura en el precio.

await commet.plans.updatePrice({
  id: "plan_pro",
  priceId: "price_pro_monthly",
  trialDays: 14,
  trialRequiresPaymentMethod: false,
});

Moverse entre planes sin perder clientes#

Cuándo sirve: tenés un plan gratuito y planes pagos en un mismo grupo. Los clientes nuevos tienen que caer en Free sin checkout, y un cliente pago que deja de pagar tiene que volver a Free en vez de perder la cuenta.

• Marcá un plan gratuito como el plan por defecto del grupo. Creá los clientes con planGroupId y arrancan en el plan inicial del grupo: su trial sin tarjeta la primera vez, el plan gratuito por defecto en las siguientes.

• Un plan pago que termina desde el portal, por una autorización de pago revocada o porque se agotaron los reintentos de cobro pasa al plan por defecto en vez de cancelarse.

• Un cambio programado para el fin del período se puede revocar desde la API, el portal ("Keep current plan") o el dashboard ("Revert plan change").

Cuándo se aplica un cambio entre planes del mismo grupo:

await commet.customers.create({
  email: "ana@example.com",
  planGroupId: "pg_main",
});

const preview = await commet.subscriptions.previewChange({
  id: "sub_123",
  planId: "plan_max",
});

await commet.subscriptions.changePlan({ id: "sub_123", newPlanId: "plan_max" });

await commet.subscriptions.revokeScheduledPlanChange({ id: "sub_123" });

Leé sobre grupos de planes y subir y bajar de plan.

Un programa de partners con Dub#

Cuándo sirve: les pagás una comisión a los partners por los clientes que traen. Hasta ahora eso implicaba copiar cada código de partner en tu facturación y reportarle cada venta a Dub a mano.

• Conectá Dub desde Settings → Integrations con una API key de Dub. Hace falta un workspace de Dub en el plan Business.

• Los descuentos de partners de Dub se vuelven Offers y los códigos, promo codes de primera compra, marcados con managedBy: "dub". Los códigos nuevos se sincronizan cuando cargás en Dub la URL de webhook que te muestra Commet.

• Commet le manda a Dub ventas, reembolsos, cancelaciones, inicios de trial y cambios de clientes, y reintenta lo que no llega. Las condiciones se editan en Dub; en Commet podés renombrar una Offer y activar o desactivar un código.

Leé sobre los códigos de partners de Dub.

Promo codes para clientes nuevos y existentes#

Cuándo sirve: un descuento de bienvenida tiene que llegar solo a clientes nuevos, y una campaña para subir de plan, a los clientes que ya tenés.

• firstPurchaseOnly limita un código a clientes sin facturas pagas por más de cero y sin suscripciones pagas.

• changePlan y previewChange aceptan promoCode en cambios inmediatos, validado con las reglas del checkout.

• El comprador puede escribir un código en el checkout de un trial con tarjeta; el descuento arranca con la primera factura después del trial. Un código cuya Offer empieza con ciclos gratis guarda la tarjeta y cierra una primera factura de $0.

await commet.promoCodes.create({
  code: "WELCOME20",
  offerId: "offer_welcome",
  firstPurchaseOnly: true,
});

await commet.subscriptions.changePlan({
  id: "sub_123",
  newPlanId: "plan_pro",
  promoCode: "UPGRADE30",
});

Leé sobre promo codes.

Vendé meses por adelantado#

Cuándo sirve: algunos clientes prefieren pagar varios meses juntos, y los pagos en efectivo como OXXO no se renuevan solos. Vender los meses por adelantado los mantiene en un plan mensual sin cambiar el intervalo.

• El cliente paga de 1 a 60 períodos por adelantado, al crear la suscripción con prepaidPeriods o después con un link de pago. Las renovaciones cubiertas no cobran el plan; el uso, los asientos y los add-ons se siguen cobrando.

• cancelAtPeriodEnd: true termina la suscripción después del último período pago. Los períodos sin usar no se reembolsan.

• Los planes y las suscripciones también se pueden cobrar cada seis meses con el intervalo semiannual.

await commet.subscriptions.createPrepaidPeriodsCheckout({
  id: "sub_123",
  periods: 6,
});

Leé sobre pago por adelantado.

Más formas de pagar#

• Google Pay y Pix. Se activan por conexión de dLocal en Settings → Payments. Google Pay guarda la tarjeta para las renovaciones; Pix permite pagar en reales a compradores de Brasil.

• OXXO en México. Quien no tiene tarjeta paga con un voucher en efectivo que aparece en el mismo checkout, con el monto, el vencimiento y el código de barras. La suscripción se activa cuando se confirma el pago.

• Mercado Pago en Argentina. El comprador autoriza una vez en el checkout y las renovaciones se cobran solas.

• Validación de documento antes de pagar. En los checkouts de dLocal, un CPF, RUT o DNI mal escrito muestra un error en el campo en vez de un pago rechazado.

• Portugués. El checkout y el portal están en portugués, además de inglés y español.

• Medios de pago guardados. El cliente guarda varios medios de pago en el portal y elige el principal. Una renovación fallida se reintenta con los otros medios guardados, y actualizar una tarjeta deja la anterior como respaldo.

Para tu equipo de finanzas#

• Una moneda para todas las métricas. El inicio del dashboard se puede personalizar, cada widget explica su cálculo y "All currencies" suma todos los pagos en USD al tipo de cambio del día anterior. Un widget opcional, "MRR after scheduled churn", excluye las suscripciones que ya tienen programada la cancelación.

• Comprobantes y resúmenes mensuales. Con Commet como merchant of record, cada payout pagado tiene su comprobante en PDF, y Settings → Monthly statements tiene un PDF y un CSV por mes para conciliar tu saldo con los depósitos en tu banco.

• Payouts en 88 países. Los payouts como merchant of record pueden ir a una cuenta bancaria local en 88 países, antes eran 15.

• Emails con tu marca. Se rediseñaron los 22 emails transaccionales. Los que reciben tus clientes abren con tu logo o tu nombre.

Para developers#

• SDKs 9.8 en cinco lenguajes. Node, Python, Go, Java y PHP, y la CLI 5.4, cubren todo lo de este post con métodos tipados.

• Una página por código de error. El doc_url de cada error de la API abre una página para ese código, con qué significa, cómo resolverlo y si conviene reintentar.

• Los endpoints de webhooks que fallan se pausan. Cuando las últimas tres entregas fallaron después de todos los reintentos, el endpoint se pausa aunque tenga tráfico constante y te llega un solo email. Se reactiva desde Settings → Webhooks o con isActive: true.

• Solo MCP v2. El primer servidor MCP se retiró. Usá https://commet.co/mcp/v2 con OAuth o una API key, incluidas las restringidas.

• Un reembolso ya no cancela. Un reembolso solo emite payment.refunded; si querés cancelar la suscripción, hacelo aparte.

npm install @commet/node@9.8.0
pip install commet-sdk==9.8.0
go get github.com/commet-labs/commet-go/v9@v9.8.0
composer require commet/commet-php:9.8.0
# Java (Gradle): implementation("co.commet:commet-java:9.8.0")

También desde el SDK 9#

• Plan grants. Dale a un cliente las funcionalidades de un plan superior del mismo grupo por algunos ciclos, hasta una fecha o hasta revocarlo, sin cambiar su precio ni sus facturas. Sirve para que un cliente Pro pruebe Enterprise antes de una llamada de upgrade.

• Créditos de cliente. Otorgá un crédito en dinero, por ejemplo después de una caída del servicio, y se descuenta de las próximas facturas antes de impuestos.

• Offers sobre suscripciones existentes. Aplicá una Offer a un checkout pendiente sin cambiar su link, o a una suscripción activa con el descuento desde el próximo ciclo, por ejemplo para retener a un cliente que pidió cancelar.

• Precios en GBP. Definí precios en libras en un plan y los compradores del Reino Unido pagan en GBP.

• Varias cuentas por proveedor. Conectá más de una cuenta de Stripe o dLocal y asigná países a cada una.

• Promociones por tarjeta. En Enterprise, vinculá una Offer a BINs de tarjetas para que el descuento aplique solo a las tarjetas de un banco aliado.

await commet.customers.createPlanGrant({
  id: "cus_123",
  subscriptionId: "sub_123",
  planId: "plan_enterprise",
  reason: "Enterprise pilot",
  duration: "cycles",
  durationCycles: 1,
});

await commet.customers.createCredit({
  id: "cus_123",
  amount: 2500,
  currency: "usd",
  reason: "Service recovery",
});

await commet.subscriptions.applyOffer({
  id: "sub_123",
  offerId: "offer_retention",
});

Leé sobre plan grants, créditos de cliente y la referencia de los SDKs.