Alterar o preço de assinaturas existentes

Saiba como fazer upgrade e downgrade de assinaturas com alteração do preço.

Quando um cliente altera a assinatura, você precisa alterar o item de assinatura para refletir a nova seleção. Por exemplo, um cliente pode fazer upgrade para um nível premium ou downgrade para um nível básico. Consequentemente, você precisa substituir o preço associado a esse item de assinatura. Isso pode ser feito usando alguns métodos diferentes.

Recuperar os identificadores

Para qualquer método escolhido, é necessário fornecer identificadores para os objetos que estão sendo atualizados. Use o método listar assinaturas com um filtro apropriado (como o ID do cliente) para localizar a assinatura e o item que precisam ser atualizados.

Retorna o conjunto de assinaturas para o cliente especificado, do qual você pode recuperar o ID da assinatura (id), qualquer ID de item de assinatura (items.data.id) e o ID dos preços dos itens de assinatura (items.data.price.id).

Retrieve subscriptions response sample
{
  "object": "list",
  "url": "/v1/subscriptions",
  "has_more": false,
  "data": [
    {
      "id": "su_1NXPiE2eZvKYlo2COk9fohqA",
      "object": "subscription",
      "application": null,
      "application_fee_percent": null,
      "automatic_tax": {
        "enabled": false
      },
      "items": {
        "object": "list",
        "data": [
          {
            "id": "si_OK3pbS1dvdQYJP",
            "object": "subscription_item",
            "billing_thresholds": null,
            "created": 1690208774,
            "metadata": {},
            "price": {
              "id": "price_1NOhvg2eZvKYlo2CqkpQDVRT",
              "object": "price"
            }
          }
        ]
      }
    }
  ]
}

Atualizar a assinatura

Atualize uma assinatura incluindo os seguintes parâmetros:

item ID: especifique o item de assinatura para substituir o preço atual pelo novo preço. Caso contrário, atualizar a assinatura com um novo preço adiciona um novo item de assinatura de modo que os dois preços fiquem ativos para a assinatura.
item price: informe o identificador do preço de substituição.
item quantity: a atualização do preço de uma assinatura reverte automaticamente a quantidade para o valor padrão de 1. Se a quantidade da assinatura existente for diferente de 1 e você quiser manter esse valor, inclua-o na atualização.

Erro comum

Você precisa especificar o item de assinatura cujo preço atual será substituído pelo novo. Se não fizer isso, o novo preço será adicionado e a assinatura ficará com dois preços ativos.

Como alternativa, você pode excluir o item de assinatura atual e criar outro com o preço atualizado.

Atualizar o item de assinatura

Atualize uma assinatura usando o seguinte parâmetro:

item price: informe o identificador do preço de substituição.
item quantity: a atualização do preço de uma assinatura reverte automaticamente a quantidade para o valor padrão de 1. Se a quantidade da assinatura existente for diferente de 1 e você quiser manter esse valor, inclua-o na atualização.

Use essa opção se não precisar fazer nenhuma outra alteração no nível da assinatura.

Períodos de faturamento

Quando o período de faturamento (combinação de interval e interval_count) dos dois preços é o mesmo, a assinatura mantém as datas de faturamento. Caso contrário, o novo preço é faturado usando o novo intervalo a partir do dia da alteração. Por exemplo, a mudança de uma assinatura mensal de um cliente para outra também mensal não altera as datas de faturamento. Já a mudança dessa assinatura para uma assinatura anual altera a data de faturamento para a data da mudança. A mudança de uma assinatura mensal para outra também mensal, mas com período de avaliação, também altera a data de faturamento para a data de término da avaliação.

Cronogramas de assinatura

If you’re changing a subscription at the end of its billing cycle, consider using a subscription schedule to manage the transition. When using subscription schedules, be sure to follow best practices to prevent unexpected subscription overwrites.

Cobrança por consumo com medidores de cobrança

Os detalhes sobre atualizações de ciclo intermediário para preços associados a um medidor de cobrança são descritos na seção Modelos de preços. Passar clear_usage ao atualizar um preço com um medidor de cobrança não tem efeito.

Cobrança medida com registros de uso Legacy

Se você tiver um preço medido respaldado por registros de uso antigos e atualizar para um novo preço de registros de uso, o uso é transmitido para o novo preço.

Pro rata

Geralmente, a alteração de uma assinatura resulta em uma cobrança pro rata para aplicar o novo preço aos dias restantes do período de faturamento. Você pode preparar o cliente para eventuais despesas extras decorrentes de uma alteração de preço exibindo uma visualização das cobranças pro rata. Você também pode desativar as cobranças proporcionais.

Pagamento imediato

A Stripe tenta cobrar imediatamente o pagamento nestas alterações de assinatura:

De uma assinatura que não exige pagamento (por exemplo, avaliação ou gratuita) para uma assinatura paga
Quando o período de faturamento muda

Quando a cobrança é feita imediatamente, mas o pagamento falha, a solicitação de alteração da assinatura é concluída e a assinatura passa para o status past_due.

Para cobrar imediatamente um cliente por uma alteração em uma assinatura no mesmo ciclo de faturamento, defina proration_behavior como always_invoice. O pro rata será calculado e uma fatura será gerada imediatamente após a alteração. Combine essa configuração com atualizações pendentes para que a assinatura somente seja atualizada após a conclusão do pagamento da nova fatura.

Créditos para downgrades

Ao faturar imediatamente para um downgrade, o cliente pode receber um crédito, que é adicionado ao seu saldo de crédito para ser aplicado a faturas futuras. Para reembolsar seu cliente, emita reembolsos e depois ajuste o saldo da conta de volta para zero. Saiba mais sobre os reembolsos do cliente na nossa página de suporte exclusiva.

Gerenciar preços e quantidades com valor zero

Se você assinou um cliente com um preço com valor zero (por exemplo, uma avaliação), alterar o preço para um valor diferente de zero gera uma fatura e redefine o período de faturamento para a data da mudança.

Se você assinou um cliente com um preço com um valor diferente de zero e uma quantidade de valor zero, alterar a quantidade para um valor diferente de zero não gera uma fatura nem redefine o período de faturamento.