# Configure ofertas de teste em assinaturas Ofereça testes gratuitos ou pagos para itens em uma assinatura. ![](https://b.stripecdn.com/docs-statics-srv/assets/trial-offer.2128af954f90482fce40e29d1604a01b.png) Use a API [Trial Offer](https://docs.stripe.com/api/product-catalog/trial-offer.md?api-version=2026-03-25.preview) para gerenciar períodos introdutórios gratuitos e pagos para suas [assinaturas](https://docs.stripe.com/subscriptions.md) com uma única integração de API. As ofertas de teste permitem qualificar leads com alta intenção, reduzir o abuso de testes e oferecer tarifas com desconto aos seus clientes por um período limitado (por exemplo, 1 USD na primeira semana de uma oferta). ## Casos de uso Com ofertas de teste, você pode executar experimentos de precificação promocional e de oferta de produtos diretamente na Stripe. Casos de uso comuns para ofertas de teste incluem: | Caso de uso | Descrição | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Testes com desconto** | Para melhorar a conversão de teste para pago e gerar receita, você pode configurar testes com desconto. Por exemplo, você oferece um preço introdutório reduzido de 4 USD por 4 semanas ou um teste gratuito de 7 dias. | | **Testes gratuitos** | Para oferecer uma assinatura com teste gratuito, inclua um item de 0 USD na assinatura. | | **Testes de upgrade** | Para venda adicional de recursos premium, você pode configurar testes de upgrade. Por exemplo, você oferece a um cliente em um plano básico um teste de 7 dias para acessar recursos premium com a tarifa do plano básico. Em seguida, quando o teste termina, você o converte automaticamente para a tarifa premium. | | **Testes em nível de item** | Para vender complementos, pacotes de IA e outros conjuntos de recursos, você pode configurar testes no nível do item. Você pode oferecer aos clientes um teste para um único item de linha em uma assinatura, enquanto fatura os demais itens pelo preço normal. | ## Before you begin - Sua integração deve estar em [2026-03-25.preview](https://docs.stripe.com/changelog.md?channel=preview#2026-03-25.preview). Você deve especificar essa [versão da Stripe](https://docs.stripe.com/api/versioning.md) no cabeçalho da sua solicitação para acessar recursos em pré-visualização. - Você deve atualizar sua assinatura do [modo de faturamento](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-billing_mode) `clássico` para o [modo de faturamento flexível](https://docs.stripe.com/billing/subscriptions/billing-mode.md) para usar ofertas de teste. ### Limitações - As ofertas de teste se aplicam apenas a itens recorrentes de assinatura. Itens não recorrentes não são elegíveis para testes pagos ou preços com desconto em período de teste. - O suporte ao dashboard e ao portal do cliente é limitado durante a pré-visualização pública. Você pode usar tanto o dashboard quanto o portal do cliente para visualizar ofertas de teste criadas usando a API, mas não pode usá-los para criar, gerenciar ou modificar itens de oferta de teste. - Você não pode modificar a duração do teste após criar a assinatura nem agendar extensões ou reduções do período de teste. - Limitações da [Trial Offer API](https://docs.stripe.com/api/product-catalog/trial-offer.md?api-version=2026-03-25.preview) e do [trial_end](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-trial_end): - Não é possível usar as ofertas de avaliação e o parâmetro `trial_end` antigo em conjunto. Recomendamos usar a API Trial Offer para configurar avaliações com desconto e avaliações gratuitas. - Se você usar o [Checkout](https://docs.stripe.com/payments/checkout.md), não poderá usar ofertas de teste. Para criar assinaturas com teste por meio do Checkout, você deve usar testes gratuitos legados com `trial_end`. Consulte [Configurar testes gratuitos](https://docs.stripe.com/payments/checkout/free-trials.md). ## Como as ofertas de teste funcionam *Products* (Products represent what your business sells—whether that's a good or a service) descrevem os bens ou serviços específicos que você oferece aos seus clientes e *Prices* (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) definem o custo unitário. Uma assinatura cobra do cliente por esses produtos, no preço especificado, de forma recorrente. Quando você cria uma oferta de teste, você define um preço de teste e a duração do teste para um produto. Quando o teste termina, a assinatura é automaticamente convertida para o preço padrão ou para outro preço que você configurar. As ofertas de teste não substituem [produtos ou preços](https://docs.stripe.com/products-prices/how-products-and-prices-work.md). `Trial Offer` é um objeto separado que associa um preço com desconto ou gratuito a um [item de assinatura](https://docs.stripe.com/api/subscription_items.md) por um período limitado, sem modificar o [preço](https://docs.stripe.com/api/subscription_items/object.md?#subscription_item_object-price) subjacente do item. ## Criar uma oferta de avaliação Para [criar uma oferta de teste](https://docs.stripe.com/api/product-catalog/trial-offer/create.md?api-version=2026-03-25.preview), passe um [preço](https://docs.stripe.com/api/product-catalog/trial-offer/create.md?api-version=2026-03-25.preview#create_product_catalog_trial_offer-price) usando o [price.id](https://docs.stripe.com/api/prices/object.md#price_object-id) para definir o custo durante o período de teste. Você pode definir como 0 USD para testes gratuitos ou qualquer valor positivo para testes pagos. Em seguida, defina [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) do período de teste como `relative` (com base nos intervalos de faturamento) ou `timestamp` (com base em uma data absoluta). Para duração relativa, use [iterations](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) para definir o número de intervalos de cobrança. Depois, defina o que acontece quando o teste termina usando [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). Use `transition` para especificar o [price.id](https://docs.stripe.com/api/prices/object.md#price_object-id) para o qual a assinatura será convertida quando o teste terminar. ### Crie uma oferta de teste com duração 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}}" ``` ### Crie uma oferta de teste com duração baseada em data e hora ```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}}" ``` ## Associe uma oferta de teste a uma nova assinatura Para associar uma oferta de teste a uma [assinatura](https://docs.stripe.com/api/subscriptions/object.md), especifique o [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) no 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" ``` #### Customer 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" ``` ## Atualize assinaturas com uma oferta de teste ### Adicione uma oferta de teste a uma assinatura existente Para adicionar uma oferta de teste a uma assinatura existente, especifique o [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) no 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" ``` ### Adicione uma oferta de teste a uma assinatura com itens existentes Para adicionar uma oferta de teste como outro item a uma assinatura que possui itens existentes, adicione um item ao array [items](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items) e especifique o [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) no 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" ``` ### Converta um item de assinatura em uma oferta de teste Para converter um item de assinatura existente em uma oferta de teste, inclua o [items.id](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items-id) e especifique o [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) no 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" ``` ### Altere a quantidade do item para uma oferta de teste Para modificar a [quantidade](https://docs.stripe.com/api/subscriptions/update.md#update_subscription-items-quantity) do item em uma oferta de teste, atualize a assinatura: ```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" ``` ## Adicione uma oferta de teste a um cronograma de assinatura Você só pode usar ofertas de teste com timestamp em [cronogramas de assinatura](https://docs.stripe.com/api/subscription_schedules.md). Diferentemente dos testes com duração relativa, que terminam após um número definido de intervalos de faturamento, os testes com timestamp terminam em uma data absoluta. Para criar um, defina [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) da oferta de teste como `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}}" ``` Em seguida, use [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 associar a oferta de teste à [phase](https://docs.stripe.com/api/subscription_schedules/create.md?#create_subscription_schedule-phases) do cronograma de assinatura: #### 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" ``` #### Customer 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" ``` ## Veja assinaturas com ofertas de avaliação Quando você [recupera uma assinatura](https://docs.stripe.com/api/subscriptions/retrieve.md), a resposta inclui a configuração de cada item, incluindo ofertas de avaliação: ```curl curl https://api.stripe.com/v1/subscriptions/{{SUBSCRIPTION_ID}} \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview" ``` ## Cancelar uma assinatura ao final de um teste pago Para cancelar a assinatura quando o teste pago terminar, crie uma assinatura com uma oferta de teste e defina o parâmetro [cancel_at](https://docs.stripe.com/api/subscriptions/update.md?#update_subscription-cancel_at) para o final do período de teste. Esse padrão oferece suporte a renovações por opt-in, garantindo que os clientes não sejam convertidos para uma assinatura recorrente por padrão. #### 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 ``` #### Customer 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 ``` ## Use ofertas de teste com outros recursos ### Ofertas de teste com cobrança por uso Ao criar um objeto [Price](https://docs.stripe.com/api/prices/object.md), você pode especificar um preço medido em vez de um preço recorrente e associá-lo a uma oferta de teste. Isso permite oferecer a mesma funcionalidade de [cobrança por uso](https://docs.stripe.com/billing/subscriptions/usage-based.md) com um preço com desconto. Para usar um preço medido, defina [usage_type](https://docs.stripe.com/api/prices/object.md?#price_object-recurring-usage_type) como `metered` e adicione um [meter](https://docs.stripe.com/api/prices/object.md?#price_object-recurring-meter) existente para rastrear o uso. ```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" ``` Em seguida, associe o “price” a uma oferta de teste como faria com qualquer outro preço recorrente: ```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}}" ``` ## Considerações adicionais ### Status de avaliação de assinatura e oferta de avaliação Ao usar ofertas de teste, o `status` de uma assinatura é determinado pelo preço do teste: - **Testes gratuitos (0 USD)**: Se uma assinatura contiver apenas ofertas de teste e todos os preços das ofertas de teste estiverem definidos como 0 USD, o status da assinatura será `trialing`. Isso corresponde ao comportamento legado de `trial_end` e é ideal para fluxos de teste gratuito padrão ou “sem necessidade de cartão”. - **Testes pagos (>0 USD)**: Se a assinatura tiver um item com preço regular ou se as ofertas de teste tiverem um preço diferente de zero, o status da assinatura será `active`, `incomplete` ou `past_due`. Esse comportamento é semelhante ao de outras assinaturas sem ofertas de teste. Como um teste pago exige um pagamento bem-sucedido imediato para começar, a assinatura segue o ciclo de vida padrão do `PaymentIntent`. Isso garante que sua lógica de faturamento existente — como webhooks para pagamentos bem-sucedidos — permaneça consistente, independentemente de o cliente estar pagando um preço promocional ou o valor recorrente completo. ### Eventos Sempre que um teste é alterado, isso aciona [Events](https://docs.stripe.com/api.md#event_types). Certifique-se de que sua integração os trate. Por exemplo, você pode querer enviar um e-mail ao cliente antes que o teste termine. Saiba mais sobre o [tratamento de eventos de assinatura](https://docs.stripe.com/billing/subscriptions/webhooks.md#events). A tabela a seguir descreve os eventos que são acionados antes do término de um teste gratuito, quando uma assinatura em teste é pausada ou cancelada e quando uma assinatura é retomada e se torna ativa. | Evento | Descrição | Caso de uso | | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.subscription.deleted` | Enviado quando uma assinatura termina. | Interrompa o acesso ao seu produto em resposta a este evento. A assinatura passa para o status `canceled` e envia este evento após o término de um teste gratuito sem uma forma de pagamento, e se o comportamento de término `missing_payment_method` da assinatura estiver definido como `cancel`. | | `customer.subscription.resumed` | Enviado quando uma assinatura não está mais pausada. Ao receber este evento, conceda ao cliente acesso ao produto caso ele tenha perdido o acesso enquanto a assinatura estava pausada. | Assinaturas suspensas são convertidas em assinaturas ativas quando são retomadas. Retomar uma assinatura pode gerar uma fatura e o Payment Intent correspondente, que deve ser pago antes que a assinatura saia do status `paused`. | | `customer.subscription.paused` | Enviado quando uma assinatura é totalmente suspensa. O faturamento também fica suspenso até o reinício da assinatura. Quando você recebe esse evento, pode revogar o acesso do cliente ao produto até que uma forma de pagamento seja adicionada e a assinatura seja reiniciada. | Pare de fornecer acesso ao seu produto em resposta a este evento. A assinatura muda para o status `paused` e envia este evento quando uma avaliação gratuita termina sem forma de pagamento e se o comportamento final de `missing_payment_method` da assinatura estiver definido como `pause`. A assinatura permanece `paused` até que seja explicitamente retomada. | | `customer.subscription.trial_will_end` | Enviado 3 dias antes do término do período de teste. Se o teste for inferior a 3 dias, este evento é acionado imediatamente. | Configure a assinatura para enviar automaticamente um e-mail ao seu cliente 3 dias antes do final do período de avaliação. | ### Definir uma âncora de faturamento quando uma oferta de teste termina Quando uma oferta de teste termina e é convertida para o preço recorrente padrão, os clientes precisam iniciar um novo ciclo de faturamento imediatamente. Por padrão, o [billing_cycle_anchor](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-trial_settings-end_behavior-billing_cycle_anchor) da assinatura é redefinido automaticamente para o momento em que o teste termina (agora). Isso garante que seus clientes sejam cobrados pelo valor integral no primeiro intervalo regular imediatamente, sem gerar cobranças pro rata. Se você não quiser que o `billing_cycle_anchor` seja alterado, pode defini-lo como `unchanged`. As opções de configuração para `billing_cycle_anchor` incluem: - `now` (padrão): redefine o `billing_cycle_anchor` da assinatura para o momento exato em que a oferta de teste termina. Isso cria um novo ciclo de cobrança para o preço padrão e gera uma fatura com o valor integral, sem cobrança pro rata. - `unchanged`: mantém a âncora original desde quando a assinatura foi criada. O período entre o término do teste e a próxima data natural de ancoragem é faturado como um valor pro rata. Por exemplo, se você oferecer um teste de 7 dias por 1 USD e quiser que a primeira cobrança mensal de 20 USD cubra um mês completo a partir do dia 8: 1. 1º de jan.: assinatura criada com uma oferta de teste de 7 dias. 1. 8 de jan.: o teste termina. O `billing_cycle_anchor` é redefinido automaticamente para 8 de jan. 1. Fatura: a Stripe gera uma fatura pelo preço recorrente integral de 20 USD para o período de 8 de jan. a 8 de fev. Nenhuma cobrança pro rata é aplicada. #### 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" ``` #### Customer 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 - [Produtos e preços](https://docs.stripe.com/products-prices/overview.md) - [Preços](https://docs.stripe.com/api.md#prices) - [Assinaturas](https://docs.stripe.com/api.md#subscriptions) - [Gerenciamento dos períodos de cobrança da assinatura](https://docs.stripe.com/billing/subscriptions/billing-cycle.md)