Offers & Pricing

Si sólo necesitás actualizar una integración existente, usá la skill de migración. Seguí leyendo para entender qué cambió y cómo funcionan juntas las nuevas piezas.

Pricing define el monto y el paquete que puede comprar un customer. Offers define cómo cambia ese precio a lo largo del tiempo. Se mantienen separados en el catálogo y se combinan cuando el customer se suscribe.

Pricing

Partí de un único plan Pro. Puede conservar su precio mensual estándar, mostrar un precio local en Argentina y ofrecer un paquete de lanzamiento seleccionable sin duplicar el plan.

• Currency Pricing define un valor para una moneda.
• Markets agrupa países que deben ver un precio y una moneda específicos.
• Variantes seleccionables representan paquetes que el customer puede elegir y heredan el precio base en todos los demás casos.

Un Market es reutilizable entre precios y no requiere un plan al crearlo:

const argentina = await commet.pricing.createMarketGroup({
  name: 'Argentina',
  countryCodes: ['AR'],
})

Una variante seleccionable se vincula con su precio base mediante inheritsFromPriceId. Pasá su priceId público cuando el customer elija ese paquete; omitilo cuando Commet deba resolver el precio normal a partir del país de facturación.

La suscripción recuerda esa elección. Las renovaciones futuras usan el valor actual del catálogo para el paquete seleccionado. Una vez elegido el precio, una Offer puede cambiar sus términos a lo largo del tiempo sin duplicar la configuración de pricing.

Offers

Pricing responde “¿cuánto?”. Una Offer responde “¿cómo cambia ese monto en el tiempo?”. Puede agregar un trial, un descuento durante varios ciclos o un precio introductorio fijo sin crear otro paquete.

const launchOffer = await commet.offers.create({
  name: 'Launch pricing',
  purpose: 'promotional',
  planPriceIds: ['pp_pro_monthly'],
  phases: [
    { type: 'percentage', durationCycles: 2, percentage: 5000 },
    { type: 'percentage', durationCycles: 2, percentage: 2500 },
  ],
})

Cuando un customer acepta una Offer, Commet guarda esas fases como los términos acordados. Editar o archivar la Offer del catálogo cambia aplicaciones futuras, no el acuerdo que un customer existente ya aceptó.

Combinalos al crear la suscripción

La suscripción es donde se encuentran ambas decisiones: el precio selecciona el paquete y la Offer define su cronograma promocional. En la API, priceId y offerId hacen explícitas esas elecciones.

await commet.subscriptions.create({
  customerId: 'user_123',
  planCode: 'pro',
  priceId: 'pp_pro_launch',
  offerId: 'ofr_launch_2026',
})

Las variantes heredan la elegibilidad de Offers desde su precio base. Si omitís offerId, Commet mantiene la selección automática de la Introductory Offer. Un offerId Promotional explícito no puede combinarse con promoCode, customTrialDays ni skipTrial: true.

Esa combinación explícita también le da a cada cohorte del experimento un resultado de billing estable.

Experimentos A/B

Por ejemplo, el grupo de control puede recibir el paquete mensual estándar mientras la variante recibe un paquete de lanzamiento con una Promotional Offer. Asigná cada customer a una cohorte estable desde tu aplicación o sistema de experimentos y pasá los términos elegidos:

const selection =
  experimentVariant === 'control'
    ? { priceId: 'pp_pro_monthly' }
    : {
        priceId: 'pp_pro_launch',
        offerId: 'ofr_launch_2026',
      }

await commet.subscriptions.create({
  customerId: 'user_123',
  planCode: 'pro',
  ...selection,
})

Commet cobra y renueva los términos seleccionados. Tu aplicación sigue siendo responsable de asignar las cohortes y medir la conversión.

Todos los cambios de v8

Pricing, Offers y su composición explícita llegaron con la versión de API 2026-07-24, SDK v8 y CLI v4. El mismo release alinea el resto del contrato público alrededor de resultados directos, alternativas exactas de requests y la API de uso actual.

Una integración existente sigue funcionando hasta que actualices el SDK, cambies un header commet-version explícito, actualices la versión de la organización o cambies la versión de un endpoint de webhooks.

Los métodos de lista siguen devolviendo { object, data, hasMore, nextCursor }. La autenticación, la idempotencia de requests, la verificación de firmas de webhooks y los helpers de frameworks siguen siendo capacidades ergonómicas de los SDKs.

Actualizá el SDK

# Node.js
npm install @commet/node@^8

# Python
pip install "commet-sdk>=8,<9"

# Go
go get github.com/commet-labs/commet-go/v8

# PHP
composer require commet/commet-php:^8.0

# Java
# co.commet:commet-java:8.0.0

Eliminá wrappers en resultados individuales

// v7
const { data: customer } = await commet.customers.create({
  id: 'user_123',
  email: 'user@example.com',
})

// v8
const customer = await commet.customers.create({
  id: 'user_123',
  email: 'user@example.com',
})

Conservá data en operaciones de lista:

const { data: customers, hasMore, nextCursor } = await commet.customers.list()

Actualizá el registro de uso

const availability = await commet.usage.check({
  customerId: 'user_123',
  featureCode: 'api_calls',
})

const event = await commet.usage.track({
  customerId: 'user_123',
  featureCode: 'api_calls',
  value: 1,
  eventId: 'request_01JXYZ',
})

eventId identifica el evento de negocio y hace seguros los reintentos. La idempotencia del transporte sigue siendo una opción del request y se envía como header Idempotency-Key.

Actualizá el CLI

CLI v4 agrega Offers, Markets de pricing, variantes de precio seleccionables, flujos de suscripción con Offers y los comandos de uso actuales.

npm install -g commet@^4

commet offers list
commet pricing list-market-groups
commet usage check --customer-id customer_123 --feature-code api_calls

Usá --feature-code en lugar de --feature para registrar uso y pasá el identificador de evento controlado por quien llama con --event-id. usage check reemplaza feature-access can-use. Los comandos de Promo Codes ahora referencian una Promotional Offer con --offer-id.

Usá alternativas exactas de requests

SDK v8 modela los requests mutuamente excluyentes como uniones discriminadas:

• La creación de suscripciones usa exactamente uno entre planId y planCode.
• Las mutaciones de cuota identifican al customer con exactamente uno entre customerId y externalId.
• Los campos de un add-on deben corresponder al consumptionModel seleccionado.
• Las sesiones del portal usan exactamente uno entre email y customerId.
• La verificación de payouts usa el payload de persona o el de empresa.
• Las actualizaciones de Test Clock usan advanceDays o frozenTime.

Las integraciones directas con la API también deben mover las operaciones legacy bajo /manage a sus rutas canónicas, usar PATCH para actualizaciones parciales y enviar Idempotency-Key en escrituras idempotentes. SDK v8 ya usa esas rutas.

Verificá los límites de versión

• Buscá un header commet-version explícito y decidí si debe pasar a 2026-07-24.
• Revisá la versión de la organización en Settings → Development → API Versions.
• Cambiá por separado la versión de cada endpoint de webhooks cuando estés listo para sus payloads v8.
• Probá en sandbox creación, lectura, listas, verificación de uso, registro de uso y verificación de webhooks.

Comportamiento que no cambió

• Currency Pricing existente sigue siendo válido; Markets es una capa aditiva.
• Omitir priceId mantiene la resolución del precio por defecto.
• Archivar un precio seleccionado lo oculta para nuevas selecciones, pero no rompe suscripciones existentes.
• Las fases aceptadas de una Offer siguen siendo snapshots inmutables.
• El tráfico v7 sigue siendo compatible mediante el motor de versiones de API.

Consultá Offers, Introductory Offers, Promotional Offers, Precios regionales y Versionado de API.