# Configurar ofertas de prueba en las suscripciones Ofrece pruebas gratuitas o de pago para las partidas de una suscripción. ![](https://b.stripecdn.com/docs-statics-srv/assets/trial-offer.2128af954f90482fce40e29d1604a01b.png) Usa la API [Trial Offer](https://docs.stripe.com/api/product-catalog/trial-offer.md?api-version=2026-03-25.preview) para gestionar los períodos de introducción sin cargo y los pagos de tus [suscripciones](https://docs.stripe.com/subscriptions.md) con una sola integración API. Las ofertas de prueba te permiten calificar a clientes potenciales de alta intención, reducir el abuso de prueba y ofrecer tarifas con descuento a tus clientes por un período limitado (por ejemplo, 1 USD durante la primera semana de una oferta). ## Casos de uso Con las ofertas de prueba, puedes ejecutar experimentos de precios promocionales y ofertas de productos directamente en Stripe. Los casos de uso más comunes para las ofertas de prueba incluyen: | Caso de uso | Descripción | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Pruebas con descuento** | Para mejorar la conversión de prueba a pago y generar ingresos, puedes configurar pruebas con descuento. Por ejemplo, puedes ofrecer un precio introductorio reducido de 4 USD durante 4 semanas o una prueba gratuita de 7 días. | | **Pruebas gratuitas** | Para ofrecer una suscripción gratuita de prueba, incluye una partida en la suscripción. | | **Actualiza las pruebas** | Para ofrecer funcionalidades premium, puedes configurar pruebas de actualización. Por ejemplo, ofreces a un cliente con un plan básico una prueba de 7 días para acceder a funcionalidades premium a la tarifa básica. Luego, cuando finaliza la prueba, lo conviertes automáticamente en la tarifa premium. | | **Pruebas a nivel de partida** | Para vender complementos, paquetes de IA y otros paquetes de funcionalidades, puedes configurar pruebas a nivel de partida. Ofrece a los clientes una prueba solo para una partida de la suscripción, mientras facturas las demás partidas a su precio habitual. | ## Before you begin - Tu integración debe usar la versión preliminar [2026-03-25.preview](https://docs.stripe.com/changelog.md?channel=preview#2026-03-25.preview). Debes especificar esa [versión de Stripe](https://docs.stripe.com/api/versioning.md) en el encabezado de tu solicitud para poder acceder a las funcionalidades de la versión preliminar. - Debes actualizar tu suscripción del [modo de facturación](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-billing_mode) `clásico` al [modo de facturación flexible](https://docs.stripe.com/billing/subscriptions/billing-mode.md) para poder usar las ofertas de prueba. ### Limitaciones - Las ofertas de prueba solo se aplican a las partidas de suscripción recurrentes. Las partidas no recurrentes no son elegibles para pruebas pagas ni para tarifas de prueba con descuento. - El dashboard y el soporte del portal de clientes es limitado durante la versión preliminar pública. Puedes usar tanto el Dashboard como el portal de clientes para ver las ofertas de prueba creadas con la API, pero no puedes usarlas para crear, administrar o modificar partidas de ofertas de prueba. - No puedes modificar la duración de la prueba después de crear la suscripción ni programar extensiones y reducciones de prueba. - [API Test Offer](https://docs.stripe.com/api/product-catalog/trial-offer.md?api-version=2026-03-25.preview) y limitaciones de [trial_end](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-trial_end): - No puedes usar las ofertas de prueba y el parámetro heredado `trial_end` juntos. Te recomendamos usar la API Trial Offer para configurar las pruebas con descuento y gratuitas. - Si usas [Checkout](https://docs.stripe.com/payments/checkout.md), no puedes usar ofertas de prueba. Para crear suscripciones de prueba mediante la confirmación de compra, debes usar pruebas gratuitas heredadas con `trial_end`. Consulta [Configurar pruebas gratuitas](https://docs.stripe.com/payments/checkout/free-trials.md). ## Cómo funcionan las ofertas de prueba Los *productos* (Products represent what your business sells—whether that's a good or a service) describen los bienes o servicios específicos que ofreces a tus clientes, y los *precios* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions) definen el costo unitario. Una suscripción cobra a un cliente por esos productos, al precio especificado, de forma recurrente. Cuando creas una oferta de prueba, especificas un precio de prueba y la duración de la prueba para un producto. Cuando finaliza la prueba, la suscripción vuelve automáticamente al precio regular u otro precio que configures. Las ofertas de prueba no sustituyen a [los productos ni a los precios](https://docs.stripe.com/products-prices/how-products-and-prices-work.md). La `oferta de prueba` es un objeto separado que vincula un precio con descuento o gratuito a una [partida de suscripción](https://docs.stripe.com/api/subscription_items.md) por un tiempo limitado, sin modificar el [precio](https://docs.stripe.com/api/subscription_items/object.md?#subscription_item_object-price) subyacente de la partida. ## Crear una oferta de prueba Para [crear una oferta de prueba](https://docs.stripe.com/api/product-catalog/trial-offer/create.md?api-version=2026-03-25.preview), especifica un [precio](https://docs.stripe.com/api/product-catalog/trial-offer/create.md?api-version=2026-03-25.preview#create_product_catalog_trial_offer-price) con el [price.id](https://docs.stripe.com/api/prices/object.md#price_object-id) a fin de definir el costo durante el período de prueba. Puedes establecerlo en 0 USD para las pruebas sin cargo o en cualquier importe positivo destinado a las pruebas pagas. A continuación, establece el [duration.type](https://docs.stripe.com/api/product-catalog/trial-offer/create.md?api-version=2026-03-25.preview#create_product_catalog_trial_offer-duration-type) de la prueba en `relativa` (en función de los intervalos de facturación) o en `marca de tiempo` (en función de una fecha absoluta). Para la duración relativa, usa [iteraciones](https://docs.stripe.com/api/product-catalog/trial-offer/object.md?api-version=2026-03-25.preview#product_catalog_trial_offer_object-duration-relative-iterations) con el objetivo de definir la cantidad de intervalos de facturación. Luego, define qué sucede cuando finaliza la prueba con el [end_behavior](https://docs.stripe.com/api/product-catalog/trial-offer/create.md?api-version=2026-03-25.preview#create_product_catalog_trial_offer-end_behavior). Usa `transición` con el fin de especificar el [price.id](https://docs.stripe.com/api/prices/object.md#price_object-id) al que pasa la suscripción cuando finaliza la prueba. ### Crear una oferta de prueba con una duración relativa ```curl curl https://api.stripe.com/v1/product_catalog/trial_offers \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "price={{PRICE_ID}}" \ -d "duration[relative][iterations]=1" \ -d "duration[type]=relative" \ -d "end_behavior[transition][price]={{PRICE_ID}}" ``` ### Crear una oferta de prueba con una duración de marca de tiempo ```curl curl https://api.stripe.com/v1/product_catalog/trial_offers \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "price={{PRICE_ID}}" \ -d "duration[type]=timestamp" \ -d "end_behavior[transition][price]={{PRICE_ID}}" ``` ## Adjuntar una oferta de prueba a una suscripción nueva Para adjuntar la oferta de prueba a una [suscripción](https://docs.stripe.com/api/subscriptions/object.md), especifica el [trial_offer.id](https://docs.stripe.com/api/product-catalog/trial-offer/object.md?api-version=2026-03-25.preview#product_catalog_trial_offer_object-id) en el parámetro [items.current_trial.trial_offer](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items-current_trial): #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "billing_mode[type]=flexible" \ -d "items[0][current_trial][trial_offer]=to_123" \ -d "items[0][quantity]=1" ``` #### Cliente v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "customer={{CUSTOMER_ID}}" \ -d "billing_mode[type]=flexible" \ -d "items[0][current_trial][trial_offer]=to_123" \ -d "items[0][quantity]=1" ``` ## Actualizar las suscripciones con una oferta de prueba ### Agregar una oferta de prueba a una suscripción existente Para adjuntar la oferta de prueba a una suscripción existente, especifica el [trial_offer.id](https://docs.stripe.com/api/product-catalog/trial-offer/object.md?api-version=2026-03-25.preview#product_catalog_trial_offer_object-id) en el parámetro [items.current_trial.trial_offer](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items-current_trial): ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "items[0][current_trial][trial_offer]=to_123" ``` ### Agregar una oferta de prueba a una suscripción con partidas existentes Para agregar una oferta de prueba como otra partida a una suscripción que tiene partidas existentes, agrega una partida a la matriz [items](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items) y especifica [trial_offer.id](https://docs.stripe.com/api/product-catalog/trial-offer/object.md?api-version=2026-03-25.preview#product_catalog_trial_offer_object-id) en el parámetro [items.current_trial.trial_offer](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items-current_trial): ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "items[0][id]={{SUBSCRIPTIONITEM_ID}}" \ -d "items[1][current_trial][trial_offer]=to_123" \ -d "items[1][quantity]=1" ``` ### Convertir una partida de suscripción en una oferta de prueba Para convertir una partida existente de una suscripción en una oferta de prueba, incluye [items.id](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items-id) y especifica [trial_offer.id](https://docs.stripe.com/api/product-catalog/trial-offer/object.md?api-version=2026-03-25.preview#product_catalog_trial_offer_object-id) en el parámetro [items.current_trial.trial_offer](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items-current_trial): ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "items[0][id]={{SUBSCRIPTIONITEM_ID}}" \ -d "items[0][current_trial][trial_offer]=to_123" ``` ### Cambiar la cantidad de partidas para una oferta de prueba Para modificar [quantity](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items-quantity) de partidas de una oferta de prueba, actualiza la suscripción: ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "items[0][id]={{SUBSCRIPTIONITEM_ID}}" \ -d "items[0][quantity]=2" ``` ## Agregar una oferta de prueba a un calendario de suscripciones Solo puedes usar ofertas de prueba con marca de tiempo con [calendarios de suscripciones](https://docs.stripe.com/api/subscription_schedules.md). A diferencia de las pruebas de duración relativa, que finalizan después de una cantidad fija de intervalos de facturación, las pruebas con marca de tiempo finalizan en una fecha absoluta. Para crear una, establece [duration.type](https://docs.stripe.com/api/product-catalog/trial-offer/object.md?api-version=2026-03-25.preview#product_catalog_trial_offer_object-duration-type) de la oferta de prueba en `timestamp`: ```curl curl https://api.stripe.com/v1/product_catalog/trial_offers \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "price={{PRICE_ID}}" \ -d "duration[type]=timestamp" \ -d "end_behavior[transition][price]={{PRICE_ID}}" ``` A continuación, usa [phases.items.trial_offer](https://docs.stripe.com/api/subscription_schedules/create.md?api-version=2026-03-25.preview#create_subscription_schedule-phases-items-trial_offer) para adjuntar la oferta de prueba a la [phase](https://docs.stripe.com/api/subscription_schedules/create.md?#create_subscription_schedule-phases) de calendario del suscripciones: #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d start_date=1610403705 \ -d "phases[0][items][0][trial_offer]=to_123" \ -d "phases[0][end_date]=1610403706" ``` #### Cliente v1 ```curl curl https://api.stripe.com/v1/subscription_schedules \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "customer={{CUSTOMER_ID}}" \ -d start_date=1610403705 \ -d "phases[0][items][0][trial_offer]=to_123" \ -d "phases[0][end_date]=1610403706" ``` ## Ver suscripciones con ofertas de prueba Cuando [recuperas una suscripción](https://docs.stripe.com/api/subscriptions/retrieve.md), la respuesta incluye la configuración de cada partida, incluidas las ofertas de prueba: ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" ``` ## Cancela una suscripción al final de una prueba paga Para cancelar la suscripción cuando finalice la prueba paga, crea una suscripción con una oferta de prueba y establece el parámetro [cancel_at](https://docs.stripe.com/api/subscriptions/update.md?#update_subscription-cancel_at) al final del período de prueba. Este patrón admite las renovaciones opcionales y garantiza que los clientes no se conviertan en suscriptores recurrentes de forma predeterminada. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][current_trial][trial_offer]=to_123" \ -d "items[0][quantity]=1" \ -d cancel_at=1610403706 ``` #### Cliente v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][current_trial][trial_offer]=to_123" \ -d "items[0][quantity]=1" \ -d cancel_at=1610403706 ``` ## Usar ofertas de prueba con otras funcionalidades ### Ofertas de prueba con cobro por consumo Al crear un objeto [Price](https://docs.stripe.com/api/prices/object.md), puedes especificar un precio medido en lugar de un precio recurrente y adjuntarlo a una oferta de prueba. Esto te permite ofrecer las mismas funcionalidades del [modelo de cobro por consumo](https://docs.stripe.com/billing/subscriptions/usage-based.md) a un precio con descuento. Para utilizar un precio por uso, establece el [usage_type](https://docs.stripe.com/api/prices/object.md?#price_object-recurring-usage_type) en `metered` y agrega un [meter](https://docs.stripe.com/api/prices/object.md?#price_object-recurring-meter) existente para llevar un registro del consumo. ```curl curl https://api.stripe.com/v1/prices \ -u "<>:" \ -d currency=usd \ -d billing_scheme=per_unit \ -d unit_amount=1 \ -d "recurring[interval]=week" \ -d "recurring[usage_type]=metered" \ -d "recurring[meter]=mtr_123" \ -d "product_data[name]=Trial Period Price" ``` A continuación, adjunta el precio a una oferta de prueba como lo harías con cualquier otro precio recurrente: ```curl curl https://api.stripe.com/v1/product_catalog/trial_offers \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "price={{PRICE_ID}}" \ -d "duration[relative][iterations]=1" \ -d "duration[type]=timestamp" \ -d "end_behavior[transition][price]={{PRICE_ID}}" ``` ## Consideraciones adicionales ### Estado y oferta de prueba de suscripción Cuando se usan ofertas de prueba, el `status` de una suscripción está determinado por el precio de la prueba: - **Pruebas gratuitas ()**: si una suscripción solo contiene ofertas de prueba y todos los precios de las ofertas de prueba se establecen en , el estado de la suscripción es `trialing`. Esto coincide con el comportamiento heredado de `trial_end` y es ideal para flujos de prueba gratuitos estándar o sin tarjeta. - **Pruebas pagas (>)**: si la suscripción tiene una partida regular o las ofertas de prueba tienen un precio distinto de cero, el estado de la suscripción estará `active`, `incomplete` o `past_due`. Este comportamiento imita a otras suscripciones sin ofertas de prueba. Debido a que, para una prueba paga, es necesario un pago exitoso inmediato para comenzar, la suscripción sigue el ciclo de vida estándar `PaymentIntent`. Esto garantiza que tu lógica de facturación actual, como los webhooks para pagos exitosos, siga siendo consistente, ya sea que el cliente esté pagando un precio promocional o el importe recurrente completo. ### Eventos Cada vez que cambia una prueba, activa [Events](https://docs.stripe.com/api.md#event_types). Asegúrate de que tu integración los gestione. Por ejemplo, es posible que desees enviar un correo electrónico a un cliente antes de que finalice una prueba. Obtén más información sobre cómo [gestionar eventos de suscripción](https://docs.stripe.com/billing/subscriptions/webhooks.md#events). La siguiente tabla describe los eventos que se activan antes de que finalice una prueba gratuita, cuando una suscripción de prueba se pausa o cancela, y cuando se reanuda una suscripción y esta pasa a ser activa. | Evento | Descripción | Caso de uso | | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.subscription.deleted` | Se envía cuando finaliza una suscripción. | En respuesta a este evento, deja de proporcionar acceso a tu producto. La suscripción pasa al estado `canceled` y envía este evento después de que finaliza un período de prueba sin cargo sin que haya un método de pago definido y si el comportamiento final `missing_payment_method` de la suscripción se establece en `cancel`. | | `customer.subscription.resumed` | Se envía cuando una suscripción ya no está en pausa. Cuando recibas este evento, otorga al cliente acceso al producto si se revocó el acceso cuando la suscripción estaba en pausa. | Las suscripciones suspendidas se convierten en suscripciones activas que se reanudan. La reanudación de una suscripción puede generar una factura y el Payment Intent correspondiente que deben pagarse antes de que la suscripción pase del estado `paused`. | | `customer.subscription.paused` | Enviado cuando una suscripción está en pausa. La facturación no se producirá hasta que se reactive la suscripción. Cuando recibas este evento, puedes revocar el acceso del cliente al producto hasta que agregue un método de pago y se reactive la suscripción. | En respuesta a este evento, deja de proporcionar acceso a tu producto. La suscripción pasa al estado `paused` y envía este evento después de que finaliza un período de prueba gratuita sin que haya un método de pago definido y si el comportamiento final `missing_payment_method` de la suscripción se establece en `pause`. El estado de la suscripción permanece en `paused` hasta que se reanude en forma explícita. | | `customer.subscription.trial_will_end` | Se envía 3 días antes de que finalice el período de prueba. Si el período de prueba es menor de 3 días, el evento se activa de inmediato. | Configura la suscripción para que se envíe automáticamente un correo electrónico a tu cliente tres días antes de que finalice el período de prueba. | ### Establecer una delimitación de facturación cuando finaliza una oferta de prueba Cuando una oferta de prueba finaliza y pasa al precio recurrente habitual, los clientes deben comenzar de inmediato un nuevo ciclo de facturación. De forma predeterminada, el [billing_cycle_anchor](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-trial_settings-end_behavior-billing_cycle_anchor) de la suscripción se restablece de manera automática cuando finaliza la prueba (ahora). Esto garantiza que se cobre a tus clientes el importe total de su primer intervalo habitual de inmediato, sin generar prorrateos. Si no quieres que cambie tu `Billing_cycle_anchor`, puedes establecerlo como `unchanged`. Las opciones de configuración para `billing_cycle_anchor` incluyen: - `now` (predeterminado): restablece el `billing_cycle_anchor` de la suscripción al momento exacto en que se completa la oferta de prueba. Esto crea un nuevo ciclo de facturación para el precio normal y genera una factura de importe total sin prorrateo. - `unchanged`: mantiene la delimitación original desde la primera vez que se creó la suscripción. El período comprendido entre la finalización de la prueba y la siguiente fecha de delimitación natural se factura como un importe prorrateado. Por ejemplo, si ofreces una prueba de 7 días por y quieres que el primer cargo mensual cubra un mes completo a partir del día 8: 1. 1 de enero: suscripción creada con una oferta de prueba de 7 días. 1. 8 de enero: finaliza la prueba. El `billing_cycle_anchor` se restablece automáticamente al 8 de enero. 1. Factura: Stripe genera una factura por el precio recurrente total de para el período del 8 de enero al 8 de febrero. No se aplica prorrateo. #### Accounts v2 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[0][current_trial][trial_offer]={{TRIAL_OFFER_ID}}" \ -d "trial_settings[end_behavior][billing_cycle_anchor]=unchanged" ``` #### Cliente v1 ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d "items[0][current_trial][trial_offer]={{TRIAL_OFFER_ID}}" \ -d "trial_settings[end_behavior][billing_cycle_anchor]=unchanged" ``` ## See also - [Productos y precios](https://docs.stripe.com/products-prices/overview.md) - [Precios](https://docs.stripe.com/api.md#prices) - [Suscripciones](https://docs.stripe.com/api.md#subscriptions) - [Gestión de los períodos de facturación de suscripciones](https://docs.stripe.com/billing/subscriptions/billing-cycle.md)