Subscriptions - Dodo Payments Documentation

Subscriptions let you sell ongoing access with automated renewals. Use flexible billing cycles, free trials, plan changes, and add‑ons to tailor pricing for each customer.

Upgrade & Downgrade

Control plan changes with proration and quantity updates.

On‑Demand Subscriptions

Authorize a mandate now and charge later with custom amounts.

Customer Portal

Let customers manage plans, billing, and cancellations.

Subscription Webhooks

React to lifecycle events like created, renewed, and canceled.

What Are Subscriptions?

Subscriptions are recurring products customers purchase on a schedule. They’re ideal for:

SaaS licenses: Apps, APIs, or platform access
Memberships: Communities, programs, or clubs
Digital content: Courses, media, or premium content
Support plans: SLAs, success packages, or maintenance

Key Benefits

Predictable revenue: Recurring billing with automated renewals
Flexible cycles: Monthly, annual, custom intervals, and trials
Plan agility: Proration for upgrades and downgrades
Add‑ons and seats: Attach optional, quantifiable upgrades
Seamless checkout: Hosted checkout and customer portal
Developer-first: Clear APIs for creation, changes, and usage tracking

Creating Subscriptions

Create subscription products in your Dodo Payments dashboard, then sell them through checkout or your API. Separating products from active subscriptions lets you version pricing, attach add‑ons, and track performance independently.

Subscription product creation

Configure the fields in the dashboard to define how your subscription sells, renews, and bills. The sections below map directly to what you see in the creation form.

Product details

Product Name (required): The display name shown in checkout, customer portal, and invoices.
Product Description (required): A clear value statement that appears in checkout and invoices.
Product Image (required): PNG/JPG/WebP up to 3 MB. Used on checkout and invoices.
Brand: Associate the product with a specific brand for theming and emails.
Tax Category (required): Choose the category (for example, SaaS) to determine tax rules.

Pick the most accurate tax category to ensure correct tax collection per region.

Pricing

Tipo de preço: Escolha Subscription (este guia). As alternativas são Pagamento único e Cobrança baseada em uso.
Preço (obrigatório): Preço recorrente base com moeda. O preço deve ser de pelo menos $1 (ou o equivalente na moeda escolhida). Valores abaixo desse mínimo não são compatíveis e a assinatura não funcionará.
Desconto aplicável (%): Desconto percentual opcional aplicado ao preço base; refletido no checkout e nas faturas.
Repetir pagamento a cada (obrigatório): Intervalo para renovações, por exemplo, a cada 1 mês. Selecione a periodicidade (meses ou anos) e a quantidade.
Período da assinatura (obrigatório): Prazo total durante o qual a assinatura permanece ativa (por exemplo, 10 anos). Após o término desse período, as renovações param, a menos que sejam estendidas.
Dias do período de teste (obrigatório): Defina a duração do teste em dias. Use 0 para desativar os testes. A primeira cobrança ocorre automaticamente quando o teste termina.
Valor do teste: Cobrança inicial opcional para um teste pago. Deixe sem definir para um teste gratuito. Consulte Testes pagos.
Selecionar adicional: Anexe até 10 adicionais que os clientes podem comprar junto com o plano base.

Changing pricing on an active product affects new purchases. Existing subscriptions follow your plan‑change and proration settings.

Add‑ons are ideal for quantifiable extras such as seats or storage. You can control allowed quantities and proration behavior when customers change them.

Advanced settings

Tax Inclusive Pricing: Display prices inclusive of applicable taxes. Final tax calculation still varies by customer location.
Generate license keys: Issue a unique key to each customer after purchase. See the License Keys guide.
Digital Product Delivery: Deliver files or content automatically after purchase. Learn more in Digital Product Delivery.
Metadata: Attach custom key–value pairs for internal tagging or client integrations. See Metadata.

Use metadata to store identifiers from your system (e.g., accountId) so you can reconcile events and invoices later.

Subscription Trials

Os testes permitem que os clientes avaliem uma assinatura antes de pagar o preço recorrente integral. Um teste pode ser gratuito, quando nada é cobrado até o fim do teste, ou pago, quando um valor reduzido é cobrado antecipadamente. Em ambos os casos, o preço integral começa na primeira renovação após o término do teste.

Configuring Trials

Set Trial Period Days in the product pricing section (use 0 to disable). You can override this when creating subscriptions:

// Via subscription creation
const subscription = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_monthly',
  quantity: 1,
  trial_period_days: 14  // Overrides product's trial period
});

// Via checkout session
const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_monthly', quantity: 1 }],
  subscription_data: { trial_period_days: 14 }
});

The trial_period_days value must be between 0 and 10,000 days.

Testes pagos

Os testes não precisam ser gratuitos. Defina um Valor do teste no preço recorrente de um produto de assinatura para cobrar uma taxa inicial reduzida durante o período de teste. O preço recorrente integral passa a ser cobrado na primeira renovação.

Formulário de preços de assinatura com duração do teste e um valor de teste opcional para um teste pago

Os testes pagos são configurados no preço do produto, não por assinatura ou sessão de checkout:

Campo	Tipo	Descrição
`trial_amount`	inteiro	Valor cobrado hoje pelo teste, nas unidades menores da moeda do preço (por exemplo, `500` para $5,00). Requer `trial_period_days > 0`. Omita ou defina como `null` para um teste gratuito.
`trial_apply_discounts`	booleano	Indica se os códigos de desconto do checkout reduzem a cobrança do teste. O padrão é `false`, portanto o valor do teste é cobrado integralmente mesmo quando um desconto se aplica ao preço recorrente.

const product = await client.products.create({
  name: 'Pro Plan',
  tax_category: 'saas',
  price: {
    type: 'recurring_price',
    price: 2900,                      // $29.00 per month after the trial
    currency: 'USD',
    discount: 0,
    purchasing_power_parity: false,
    payment_frequency_count: 1,
    payment_frequency_interval: 'Month',
    subscription_period_count: 1,
    subscription_period_interval: 'Year',
    trial_period_days: 14,            // A paid trial requires a positive trial period
    trial_amount: 500,                // $5.00 charged today
    trial_apply_discounts: false      // Discounts apply to the recurring price only
  }
});

Os testes pagos também passam pelo checkout. O valor do teste é tributado, aparece nos cálculos da sessão de checkout e nos preços do link de pagamento, e o markup do Adaptive Currency é aplicado por moeda. O endpoint de visualização retorna trial_amount e trial_period_days para que você possa mostrar o valor devido hoje antes de a assinatura ser criada.

Os testes gratuitos permanecem inalterados. Deixar o Valor do teste sem definir mantém o comportamento existente, no qual a primeira cobrança é 0 e o preço integral é cobrado quando o teste termina.

Evitando o uso indevido de testes

Evitar uso indevido de testes impede que os clientes reivindiquem repetidamente testes para a mesma empresa. Quando ativado, um cliente que já resgatou um teste é automaticamente convertido em uma compra paga sem teste, em vez de receber um novo teste.

Alternância de prevenção de uso indevido de testes na aba de configurações de assinaturas

Ative essa opção na aba Subscriptions em Settings. Depois de ativada:

Os clientes são associados por e-mail normalizado, com os aliases contendo sinal de mais removidos, portanto user+trial@example.com e user@example.com são considerados a mesma pessoa.
Os resgates são registrados na ativação do teste, portanto um cliente que cancela no mesmo dia ainda consumiu o teste.
Os clientes existentes são preenchidos retroativamente a partir de seus testes históricos por e-mail, portanto usuários de testes anteriores são reconhecidos imediatamente.

A configuração fica desativada por padrão. Consulte Configurações de assinatura para ver a lista completa de controles de assinatura no nível da empresa.

Detectando o status do teste

Atualmente, não há um campo direto para detectar o status do teste. A solução alternativa a seguir exige consultar pagamentos, o que é ineficiente. Estamos trabalhando em uma solução mais eficiente.

Para determinar se uma assinatura de teste gratuito está em período de teste, recupere a lista de pagamentos da assinatura. Se houver exatamente um pagamento com valor 0, a assinatura está no período de teste:

const subscription = await client.subscriptions.retrieve('sub_123');
const payments = await client.payments.list({
  subscription_id: subscription.subscription_id
});

// Check if subscription is in trial
const isInTrial = payments.items.length === 1 && 
                  payments.items[0].total_amount === 0;

Essa verificação de valor zero funciona apenas para testes gratuitos. Em um teste pago, o primeiro pagamento é igual ao valor do teste, não a 0. Compare o primeiro pagamento com trial_amount da assinatura ou verifique se next_billing_date ainda está dentro do período de teste.

Atualizando o período de teste

Estenda o teste atualizando next_billing_date:

await client.subscriptions.update('sub_123', {
  next_billing_date: '2025-02-15T00:00:00Z'  // New trial end date
});

Não é possível definir next_billing_date para um horário passado. A data deve estar no futuro.

Alterações no plano de assinatura

As alterações de plano permitem fazer upgrade ou downgrade de assinaturas, ajustar quantidades ou migrar para produtos diferentes. Dependendo do modo de rateio selecionado, uma alteração pode gerar uma cobrança imediata, criar um crédito ou não aplicar nenhum ajuste de cobrança.

Você pode alterar planos de assinatura e atualizar a próxima data de cobrança diretamente no dashboard do Dodo Payments. Isso oferece uma maneira rápida de ajustar assinaturas para solicitações de suporte ao cliente, upgrades promocionais ou migrações de plano sem fazer chamadas de API.

Ative as alterações de plano self-service: Quer que os clientes façam upgrade ou downgrade de suas próprias assinaturas pelo Customer Portal? Adicione seus produtos de assinatura a uma coleção de produtos e ative “Allow Subscription Updates” nas configurações de assinatura.

Product Collections

Agrupe produtos relacionados em coleções para ativar fluxos contínuos de upgrade/downgrade no Customer Portal.

Modos de rateio

Escolha como os clientes serão cobrados ao alterar planos:

Comparação rápida dos quatro modos de rateio:

	`prorated_immediately`	`difference_immediately`	`full_immediately`	`do_not_bill`
Upgrade	Cobrança rateada pelos dias restantes	Diferença total de preço cobrada	Preço total do novo plano cobrado	Sem cobrança — alteração imediata
Downgrade	Crédito rateado pelos dias restantes	Diferença total de preço como crédito	Sem crédito, cobrança integral	Sem crédito — alteração imediata
Ciclo de cobrança	Reinicia hoje	Reinicia hoje	Reinicia hoje	Permanece igual
Ideal para	Cobrança justa baseada no tempo	Alterações simples de nível	Reinicialização do ciclo de cobrança	Migrações gratuitas ou alterações de cortesia

`prorated_immediately`

Cobra um valor rateado com base no tempo restante do ciclo de cobrança atual. Ideal para uma cobrança justa que considera o tempo não utilizado.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

`difference_immediately`

Cobra imediatamente a diferença de preço (upgrade) ou adiciona crédito para renovações futuras (downgrade). Ideal para cenários simples de upgrade/downgrade.

// Upgrade: charges $50 (difference between $30 and $80)
// Downgrade: credits remaining value, auto-applied to renewals
await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Os créditos de downgrades que usam difference_immediately são vinculados à assinatura e aplicados automaticamente a renovações futuras. Eles são diferentes dos benefícios do Credit-Based Billing.

Quando um cliente faz downgrade usando difference_immediately, o valor não utilizado se torna um crédito vinculado à assinatura, que compensa automaticamente renovações futuras:

`full_immediately`

Cobra imediatamente o valor total do novo plano, ignorando o tempo restante. Ideal para reiniciar ciclos de cobrança.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_monthly',
  quantity: 1,
  proration_billing_mode: 'full_immediately'
});

`do_not_bill`

Muda para o novo plano sem nenhum ajuste de cobrança. Não há cobranças de rateio nem créditos — o cliente simplesmente passa para o novo plano. Ideal para migrações de cortesia, alterações gratuitas de plano ou situações em que você deseja absorver a diferença de custo.

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new_plan',
  quantity: 1,
  proration_billing_mode: 'do_not_bill'
});

Example: Prorated upgrade calculation

Cenário: O cliente do plano Basic (

30/mês) faz upgrade para Pro (

80/mês) no dia 16 de um ciclo de 30 dias usando prorated_immediately.

Unused credit from Basic = $30 × (15 remaining / 30 total) = $15.00
Prorated cost of Pro     = $80 × (15 remaining / 30 total) = $40.00
────────────────────────────────────────────────────────────────────
Immediate charge         = $40.00 − $15.00 = $25.00

Próxima renovação em 15 de fevereiro (16 de janeiro + 30 dias): $80,00/mês.

Para exemplos de cálculo e casos extremos mais detalhados, consulte nosso Guia completo de Upgrade e Downgrade.

Example: Downgrade credit calculation

Cenário: O cliente do plano Pro (

80/mês) faz downgrade para Starter (

20/mês) usando difference_immediately.

Credit = Old plan − New plan = $80 − $20 = $60.00

O crédito de $60 é aplicado automaticamente a renovações futuras:

Renovação 1: $20 −$ 20 (crédito) = ** $0,00** (restam$ 40 de crédito)
Renovação 2: $20 −$ 20 (crédito) = ** $0,00** (restam$ 20 de crédito)
Renovação 3: $20 −$ 20 (crédito) = $0,00 (crédito esgotado)
Renovação 4: $20,00 (preço integral)

Saiba mais sobre como os créditos são gerenciados no Guia de Upgrade e Downgrade.

Alterando planos com adicionais

Modifique os adicionais ao alterar planos. Os adicionais são incluídos nos cálculos de rateio:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'difference_immediately',
  addons: [{ addon_id: 'addon_extra_seats', quantity: 2 }]  // Add add-ons
  // addons: []  // Empty array removes all existing add-ons
});

Por padrão (effective_at: 'immediately'), as alterações de plano geram cobranças imediatas. Passe effective_at: 'next_billing_date' para agendar a alteração para a próxima data de cobrança; a alteração pendente é retornada na assinatura como scheduled_change, e você pode cancelá-la com Cancelar alteração de plano agendada. Cobranças com falha podem mover a assinatura para o status on_hold, a menos que você passe on_payment_failure: 'prevent_change', que mantém a assinatura no plano atual até que o pagamento seja bem-sucedido. Acompanhe as alterações por meio de eventos de webhook subscription.plan_changed.

Visualizando alterações de plano

Antes de confirmar uma alteração de plano, visualize a cobrança exata e a assinatura resultante:

const preview = await client.subscriptions.previewChangePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately'
});

// Show customer the charge before confirming
console.log('You will be charged:', preview.immediate_charge.summary);

Preview Change Plan API

Visualize as alterações de plano antes de confirmá-las.

Pausando e retomando assinaturas

Pausar congela uma assinatura em vez de encerrá-la. A cobrança é interrompida, o acesso é revogado e a assinatura mantém seu plano e histórico para que o cliente possa continuar exatamente de onde parou. Use isso como alternativa de retenção ao cancelamento. Abra qualquer assinatura ativa em Sales → Subscriptions e clique em Pause subscription. O status muda para paused e as renovações são interrompidas até que a assinatura seja retomada.

O que acontece quando você pausa

As renovações são interrompidas. Nenhuma invoice é gerada e nenhuma cobrança de renovação é tentada enquanto a assinatura estiver pausada.
O acesso é revogado imediatamente. Pausar revoga todos os entitlement grants entregues e pendentes na assinatura, o que desabilita suas license keys e impede a emissão de novas URLs de download de digital product. Retomar concede esses itens novamente, da mesma forma que a recuperação de on_hold.
O relógio de cobrança congela. next_billing_date e expires_at avançam exatamente pelo tempo que a assinatura ficou pausada, para que o cliente mantenha o período pelo qual já pagou.
Não há limite de duração para a pausa. Uma assinatura pausada permanece assim até que alguém a retome. Você não define antecipadamente a duração da pausa.

A pausa revoga o acesso imediatamente, não ao final do período de cobrança. Se uma assinatura controla o acesso ao seu produto, deixe isso claro para o cliente antes que ele confirme.

Retomar retorna a assinatura para active e restaura seus entitlements. Como o relógio foi congelado, a próxima renovação ocorre após a duração da pausa — uma assinatura pausada por 12 dias é renovada com 12 dias de atraso.

Pausando assinaturas baseadas em uso

Uma assinatura baseada em uso pode ter uso registrado, mas ainda não faturado, no momento em que é pausada. Bill Usage at Pause em Settings → Subscriptions define o que acontece com esse uso:

Configuração	Comportamento
On (padrão)	Dodo Payments gera uma invoice para o uso acumulado desde a última data de cobrança e faz a cobrança imediatamente.
Off	O uso devido é levado adiante e faturado na próxima invoice regular da assinatura.

Somente o uso medido é liquidado dessa forma — a tarifa base recorrente nunca é cobrada no momento da pausa. Assinaturas padrão e on-demand não têm nada a liquidar, portanto essa configuração não as afeta.

Bill Usage at Pause é registrado por ciclo de cobrança. Alterá-lo no meio do ciclo não muda a forma como o ciclo em andamento é liquidado; o novo valor se aplica a partir do próximo ciclo.

A invoice de liquidação é cobrada como qualquer outra invoice e, portanto, pode falhar. Se permanecer inadimplente após o período de carência de dunning, a assinatura muda para on_hold, permanecendo marcada como pausada.

Uma assinatura nesse estado tem duas formas de sair dele, e elas diferem em quem absorve o uso devido:

Saída	Resultado
A invoice de liquidação é paga	A assinatura retorna para `paused`, não para `active`. Retome-a explicitamente quando o cliente estiver pronto.
Você a retoma diretamente	A assinatura vai diretamente para `active` e a invoice de liquidação não paga é anulada, junto com suas tentativas pendentes. O uso devido é baixado.

Retomar é uma saída válida desse bloqueio — você não precisa cobrar a invoice de liquidação primeiro. Apenas tenha em mente que retomar perdoa o uso pendente, em vez de adiá-lo.

Permitindo que os clientes pausem suas próprias assinaturas

Allow Subscription Pause em Settings → Subscriptions controla se os clientes podem pausar e retomar pelo Customer Portal. Essa opção fica desativada por padrão, portanto a pausa self-service é opcional.

Essa configuração se aplica somente ao Customer Portal. Você sempre pode pausar e retomar pelo dashboard ou pela API, independentemente da configuração do toggle. Desativá-la impede novas pausas feitas por clientes, mas não prende um cliente que já está pausado — ele ainda pode retomar uma pausa que iniciou. As pausas iniciadas por você continuam sob seu controle.

Pausing from the Customer Portal

Veja o que o cliente vê, incluindo a caixa de diálogo de confirmação.

Pausando via API

Pausar e retomar são controlados por um único campo pause no endpoint de atualização de assinatura. Não existe um endpoint separado para pausar.

// Pause
await client.subscriptions.update('sub_123', { pause: true });

// Resume
await client.subscriptions.update('sub_123', { pause: false });

pause é exclusivo em relação a todos os outros campos — enviá-lo junto com qualquer outra coisa é rejeitado com 422. Definir status como paused não pausa uma assinatura; use o campo pause.

Pausar emite subscription.paused e retomar emite subscription.unpaused. Ambos contêm o objeto completo da assinatura, com paused_at definido enquanto pausada e null após a retomada.

Pausa e outras ações de assinatura

O cancelamento continua funcionando. Você pode cancelar uma assinatura pausada exatamente como faria com uma assinatura ativa. Qualquer invoice de liquidação aberta resultante da pausa é anulada quando você faz isso.
Alterações de plano agendadas são adiadas, não descartadas. Uma alteração de plano agendada para a próxima data de cobrança permanece intacta enquanto a assinatura está pausada e é aplicada na data de cobrança ajustada após a retomada. Seu scheduled_change.effective_at é um snapshot do momento em que foi agendada e não é ajustado pela pausa, portanto pode mostrar uma data no passado — interprete-o como “estava agendado para”, não como uma data garantida. Para descartar a alteração em vez de mantê-la, use Cancel Scheduled Plan Change.

Estados da assinatura

Uma assinatura passa por um conjunto definido de status durante sua existência. Esta tabela é a referência para cada status, o que o causa e como (ou se) você pode recuperá-lo.

Status	Significado	Recuperável?	Caminho de recuperação / próximo passo
`pending`	A assinatura está sendo criada ou processada	—	Aguarde `subscription.active` (ou `subscription.failed`)
`active`	A assinatura está ativa e será renovada automaticamente	—	Nenhuma ação necessária
`on_hold`	Um pagamento de renovação (ou cobrança de alteração de plano) falhou; as renovações foram interrompidas	Sim	Atualize o método de pagamento para reativar — automaticamente por meio de Payment Retries e Dunning, ou manualmente por meio da Update Payment Method API
`paused`	A assinatura foi pausada deliberadamente por você ou pelo cliente; a cobrança está congelada e o acesso foi revogado	Sim	Retome-a com `pause: false` ou pelo Customer Portal quando a pausa self-service estiver habilitada — consulte Pausando e retomando assinaturas
`cancelled`	A assinatura foi cancelada e não será renovada	Somente recomprável	O cliente deve iniciar uma nova assinatura; Dunning pode solicitar uma recompra
`failed`	A criação da assinatura falhou (o mandato ou pagamento inicial não foi bem-sucedido)	Não — terminal	O cliente deve criar uma nova assinatura com um método de pagamento válido
`expired`	A assinatura chegou ao fim do prazo	—	O cliente deve iniciar uma nova assinatura, se desejar

on_hold e failed são frequentemente confundidos. on_hold é um estado recuperável de uma assinatura já ativa cuja renovação falhou. failed é um estado terminal que ocorre somente quando a criação inicial da assinatura falha — não é possível reativá-lo.

on_hold e paused também são distintos. on_hold é involuntário — um pagamento falhou. paused é deliberado — você ou o cliente escolheram congelar a assinatura, e nenhuma renovação é tentada enquanto ela permanece pausada. Uma assinatura baseada em uso ainda pode ter uma invoice de liquidação única pendente no momento em que é pausada; consulte Pausando assinaturas baseadas em uso.

Máquina de estados

Estado em espera

Uma assinatura entra no estado on_hold quando:

Um pagamento de renovação falha (fundos insuficientes, cartão expirado etc.)
Uma cobrança de alteração de plano falha
A autorização do método de pagamento falha
Uma invoice de liquidação da pausa de uma assinatura baseada em uso não é paga

Quando uma assinatura está no estado on_hold, ela não será renovada automaticamente. Você deve atualizar o método de pagamento para reativá-la.

Reativando a partir do estado em espera

Para reativar uma assinatura no estado on_hold, atualize o método de pagamento. Isso automaticamente:

Cria uma cobrança pelos valores pendentes
Gera uma invoice
Processa o pagamento usando o novo método de pagamento
Reativa a assinatura para o estado active após o pagamento bem-sucedido

A única exceção é um bloqueio causado por uma invoice de liquidação da pausa não paga. Liquidar essa invoice retorna a assinatura para paused, não para active, pois a pausa era o estado anterior à falha do pagamento. Retome-a explicitamente depois que a invoice for liquidada.

// Reactivate subscription from on_hold
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
  // Monitor webhooks for payment.succeeded and subscription.active
}

Após atualizar com sucesso o método de pagamento de uma assinatura on_hold, você receberá eventos de webhook payment.succeeded seguidos por subscription.active.

Eventos de webhook por transição

Cada transição emite um webhook para que você possa controlar a lógica de entitlements sem polling:

Transição	Evento
Assinatura ativada	`subscription.active`
Renovação bem-sucedida	`subscription.renewed`
Renovação falha → em espera	`subscription.on_hold`
Assinatura pausada	`subscription.paused`
Assinatura pausada retomada	`subscription.unpaused`
Criação falha	`subscription.failed`
Plano atualizado/rebaixado	`subscription.plan_changed`
Cancelada	`subscription.cancelled`
Prazo encerrado	`subscription.expired`
Qualquer alteração de campo	`subscription.updated`

Subscription Webhook Payloads

Veja o schema completo do payload para eventos do ciclo de vida da assinatura.

Gerenciamento pela API

Create subscriptions

Use POST /checkouts para criar assinaturas programaticamente a partir de produtos, com trials opcionais (subscription_data.trial_period_days) e add-ons (product_cart[].addons).

POST /subscriptions está deprecated. As integrações existentes continuam funcionando, mas novas integrações devem usar Checkout Sessions.

API Reference

Veja a API de criação de sessão de checkout.

Update subscriptions

Use PATCH /subscriptions/{subscription_id} para cancelar na próxima data de cobrança, estender o período da assinatura, atualizar os dados de cobrança ou modificar metadados. Para alterar a quantidade, use a Change Plan API — PATCH não aceita quantity.

API Reference

Saiba como atualizar os detalhes da assinatura.

Pause and resume subscriptions

Pausar e retomar usam o mesmo endpoint PATCH /subscriptions/{subscription_id}, por meio do campo pause: pause: true pausa uma assinatura ativa e pause: false a retoma. O campo não pode ser combinado com nenhum outro campo na mesma solicitação. Para conhecer o comportamento completo, os efeitos na cobrança e as configurações comerciais relacionadas, consulte Pausando e retomando assinaturas.

API Reference

Veja a API de atualização de assinatura, incluindo o campo pause.

Change plans (proration)

Altere o produto ativo e as quantidades com controles de proration.

API Reference

Revise as opções de alteração de plano.

On‑demand charges

Para assinaturas on-demand, cobre valores específicos sob demanda.

API Reference

Cobre uma assinatura on-demand.

List and retrieve

Use GET /subscriptions para listar todas as assinaturas e GET /subscriptions/{id} para recuperar uma.

API Reference

Consulte as APIs de listagem e recuperação.

Usage history

Recupere o uso registrado para modelos de preços medidos ou híbridos.

API Reference

Veja a API de histórico de uso.

Update payment method

Atualize o método de pagamento de uma assinatura. Para assinaturas ativas, isso atualiza o método de pagamento das renovações futuras. Para assinaturas no estado on_hold, isso reativa a assinatura criando uma cobrança pelos valores pendentes.Ao gerar um novo link de método de pagamento (o tipo de solicitação New), você pode passar allowed_payment_method_types para restringir quais métodos de pagamento o cliente vê nessa página. Os clientes nunca verão um método que não esteja na lista, embora incluir um método não garanta que ele aparecerá (a disponibilidade ainda depende de fatores como a localização do cliente e as configurações da sua empresa).

API Reference

Saiba como atualizar métodos de pagamento e reativar assinaturas.

Casos de uso comuns

SaaS e APIs: acesso em níveis com add-ons para assentos ou uso
Conteúdo e mídia: acesso mensal com trials introdutórios
Planos de suporte B2B: contratos anuais com add-ons de suporte premium
Ferramentas e plugins: license keys e versões lançadas

Exemplos de integração

Checkout Sessions (assinaturas)

Ao criar sessões de checkout, inclua seu produto de assinatura e os add-ons opcionais:

const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'pdt_subscription',
      quantity: 1
    }
  ]
});

Alterações de plano com proration

Faça upgrade ou downgrade de uma assinatura e controle o comportamento de proration:

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_new',
  quantity: 1,
  proration_billing_mode: 'difference_immediately'
});

Cancelar na próxima data de cobrança

Agende um cancelamento que entre em vigor ao final do período de cobrança atual:

await client.subscriptions.update('sub_123', {
  cancel_at_next_billing_date: true
});

Estender o período da assinatura

Estenda a duração de uma assinatura passando um novo subscription_period_count e subscription_period_interval para PATCH /subscriptions/{subscription_id}. A data de expiração da assinatura é recalculada a partir da nova quantidade e do intervalo — por exemplo, para conceder tempo adicional a um cliente em seu plano atual:

await client.subscriptions.update('sub_123', {
  subscription_period_count: 5,
  subscription_period_interval: 'Month'
});

O período de uma assinatura só pode ser aumentado, nunca reduzido.

Assinaturas on-demand

Crie uma assinatura on-demand e faça a cobrança posteriormente, conforme necessário:

const onDemand = await client.subscriptions.create({
  customer: { customer_id: 'cus_123' },
  billing: { country: 'US' },
  product_id: 'pdt_on_demand',
  quantity: 1,
  on_demand: { mandate_only: true }
});

await client.subscriptions.charge(onDemand.subscription_id, {
  product_price: 4900,
  product_currency: 'USD',
  product_description: 'Extra usage for September'
});

Atualizar o método de pagamento de uma assinatura ativa

Atualize o método de pagamento de uma assinatura ativa:

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

// Or use existing payment method
await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'existing',
    payment_method_id: 'pm_abc123'
  }
});

Reativar uma assinatura a partir de on_hold

Reative uma assinatura que entrou em espera devido a um pagamento malsucedido:

// Update payment method - automatically creates charge for remaining dues
const response = await client.subscriptions.updatePaymentMethod('sub_123', {
  payment_method: {
    type: 'new',
    return_url: 'https://example.com/return'
  }
});

if (response.payment_id) {
  // Charge created for remaining dues
  // Redirect customer to response.payment_link
  // Monitor webhooks: payment.succeeded → subscription.active
}

Assinaturas com mandatos em conformidade com o RBI

As assinaturas de UPI e cartões indianos operam sob os regulamentos do RBI (Reserve Bank of India), com requisitos específicos de mandato:

Limites de mandato

O tipo e o valor do mandato dependem da cobrança recorrente da assinatura:

Cobranças abaixo do limite mínimo do mandato (₹15.000 por padrão): Criamos um mandato on-demand no valor do limite mínimo. O valor da assinatura é cobrado periodicamente de acordo com a frequência da assinatura, até o limite do mandato.
Cobranças iguais ou superiores ao limite mínimo do mandato: Criamos um mandato de assinatura (ou mandato on-demand) para o valor exato da assinatura.

O limite mínimo do mandato pode ser configurado por merchant ou por solicitação via mandate_min_amount_inr_paise (paise de INR). O valor registrado no banco é max(mandate_floor, billing_amount) — portanto, o limite mínimo se torna efetivamente o teto de autorização apresentado ao cliente sempre que a cobrança for menor. Para obter informações detalhadas sobre mandatos em conformidade com o RBI e o limite mínimo configurável para métodos de pagamento indianos, consulte a página India Payment Methods.

Considerações sobre upgrade e downgrade

Importante: Ao fazer upgrade ou downgrade de assinaturas, considere cuidadosamente os limites do mandato:

Se um upgrade/downgrade resultar em um valor de cobrança superior a Rs 15.000 e ultrapassar o limite de pagamento on-demand existente, a cobrança da transação poderá falhar.
Nesses casos, o cliente poderá precisar atualizar seu método de pagamento ou alterar novamente a assinatura para estabelecer um novo mandato com o limite correto.

Autorização para cobranças de alto valor

Para cobranças de assinatura de Rs 15.000 ou mais:

O banco solicitará que o cliente autorize a transação.
Se o cliente não autorizar a transação, ela falhará e a assinatura será colocada em espera.

Atraso de processamento de 48 horas

Cronograma de processamento: As cobranças recorrentes em cartões indianos e assinaturas UPI seguem um padrão de processamento específico:

As cobranças são iniciadas na data agendada, de acordo com a frequência da assinatura.
A dedução efetiva da conta do cliente ocorre somente após 48 horas do início do pagamento.
Essa janela de 48 horas pode se estender por até 2–3 horas adicionais, dependendo das respostas da API do banco.

Janela de cancelamento do mandato

Durante a janela de processamento de 48 horas:

Os clientes podem cancelar o mandato pelos aplicativos bancários.
Se um cliente cancelar o mandato durante esse período, a assinatura permanecerá ativa (este é um caso extremo específico de assinaturas Indian card e UPI AutoPay).
No entanto, a dedução efetiva poderá falhar e, nesse caso, colocaremos a assinatura em espera.

Tratamento de casos extremos: Se você fornecer benefícios, créditos ou uso da assinatura aos clientes imediatamente após o início da cobrança, será necessário tratar essa janela de 48 horas adequadamente na sua aplicação. Considere:

Adiar a ativação dos benefícios até a confirmação do pagamento
Implementar períodos de carência ou acesso temporário
Monitorar o status da assinatura para detectar cancelamentos de mandato
Tratar estados de assinatura em espera na lógica da sua aplicação

Monitore os webhooks de assinatura para acompanhar alterações no status do pagamento e tratar casos extremos em que os mandatos são cancelados durante a janela de 48 horas.

Práticas recomendadas

Comece com níveis claros: 2–3 planos com diferenças evidentes
Comunique os preços: mostre totais, proration e a próxima renovação
Use trials com critério: converta com onboarding, não apenas com tempo
Aproveite os add-ons: mantenha os planos base simples e faça upsell de extras
Teste as alterações: valide alterações de plano e proration no modo de teste

As assinaturas são uma base flexível para receita recorrente. Comece de forma simples, teste cuidadosamente e faça iterações com base nas métricas de adoção, churn e expansão.

Última modificação em 23 de agosto de 2026

Upgrade & Downgrade

On‑Demand Subscriptions

Customer Portal

Subscription Webhooks

​What Are Subscriptions?

​Key Benefits

​Creating Subscriptions

​Subscription product creation

​Product details

​Pricing

​Advanced settings

​Subscription Trials

​Configuring Trials

​Testes pagos

​Evitando o uso indevido de testes

​Detectando o status do teste

​Atualizando o período de teste

​Alterações no plano de assinatura

Product Collections

​Modos de rateio

​prorated_immediately

​difference_immediately

​full_immediately

​do_not_bill

​Alterando planos com adicionais

​Visualizando alterações de plano

Preview Change Plan API

​Pausando e retomando assinaturas

​O que acontece quando você pausa

​Pausando assinaturas baseadas em uso

​Permitindo que os clientes pausem suas próprias assinaturas

Pausing from the Customer Portal

​Pausando via API

​Pausa e outras ações de assinatura

​Estados da assinatura

​Máquina de estados

​Estado em espera

​Reativando a partir do estado em espera

​Eventos de webhook por transição

Subscription Webhook Payloads

​Gerenciamento pela API

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

API Reference

​Casos de uso comuns

​Exemplos de integração

​Checkout Sessions (assinaturas)

​Alterações de plano com proration

​Cancelar na próxima data de cobrança

​Estender o período da assinatura

​Assinaturas on-demand

​Atualizar o método de pagamento de uma assinatura ativa

​Reativar uma assinatura a partir de on_hold

​Assinaturas com mandatos em conformidade com o RBI

​Limites de mandato

​Considerações sobre upgrade e downgrade

​Autorização para cobranças de alto valor

​Atraso de processamento de 48 horas

​Janela de cancelamento do mandato

​Práticas recomendadas

What Are Subscriptions?

Key Benefits

Creating Subscriptions

Subscription product creation

Product details

Pricing

Advanced settings

Subscription Trials

Configuring Trials

Testes pagos

Evitando o uso indevido de testes

Detectando o status do teste

Atualizando o período de teste

Alterações no plano de assinatura

Modos de rateio

`prorated_immediately`

`difference_immediately`

`full_immediately`

`do_not_bill`

Alterando planos com adicionais

Visualizando alterações de plano

Pausando e retomando assinaturas

O que acontece quando você pausa

Pausando assinaturas baseadas em uso

Permitindo que os clientes pausem suas próprias assinaturas

Pausando via API

Pausa e outras ações de assinatura

Estados da assinatura

Máquina de estados

Estado em espera

Reativando a partir do estado em espera

Eventos de webhook por transição

Gerenciamento pela API

Casos de uso comuns

Exemplos de integração

Checkout Sessions (assinaturas)

Alterações de plano com proration

Cancelar na próxima data de cobrança

Estender o período da assinatura

Assinaturas on-demand

Atualizar o método de pagamento de uma assinatura ativa

Reativar uma assinatura a partir de on_hold

Assinaturas com mandatos em conformidade com o RBI

Limites de mandato

Considerações sobre upgrade e downgrade

Autorização para cobranças de alto valor

Atraso de processamento de 48 horas

Janela de cancelamento do mandato

Práticas recomendadas