Alterar o preço de assinaturas existentes

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.

curl -G https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer={{CUSTOMER_ID}}

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).

{
  "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.

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][price]"={{NEW_PRICE_ID}}

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

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][deleted]"=true \
  -d "items[1][price]"={{NEW_PRICE_ID}}

Atualizar o item de assinatura

Atualize um item de assinatura utilizando os parâmetros abaixo:

• price: Informe o identificador correspondente ao novo preço a ser aplicado.
• quantity: Modificar o preço de uma assinatura redefine automaticamente a quantidade para o valor padrão de 1. Se a quantidade atual for diferente de 1 e você desejar mantê-la, é necessário incluí-la explicitamente na atualização.

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

curl https://api.stripe.com/v1/subscription_items/si_xxxxxxxxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d price={{NEW_PRICE_ID}}

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

Se você estiver alterando uma assinatura no final do ciclo de cobrança, considere usar um cronograma de assinatura para gerenciar a transição. Quando usar cronogramas de assinatura, siga as práticas recomendadas para evitar sobreposições inesperadas de assinatura.

Cobrança por uso 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 por 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.

curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "items[0][id]"={{SUB_ITEM_ID}} \
  -d "items[0][price]"={{NEW_PRICE_ID}} \
  -d "items[0][clear_usage]"=true

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

O Stripe tenta imediatamente fazer o pagamento quando a âncora do ciclo de faturamento de uma assinatura é redefinida. Saiba mais sobre como redefinir a âncora do ciclo de faturamento de uma assinatura.

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.

Pro ratas de crédito

Os pro rata de crédito são emitidos quando os clientes fazem downgrade de suas assinaturas ou cancelam itens de assinatura antes do final do período de cobrança. O Stripe oferece duas abordagens para calcular os pro rata de crédito, dependendo da configuração modelo_de_faturamento da sua assinatura. Consulte Pro ratas de crédito para mais detalhes.

Lidar com preços e quantidades de 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.

If you’ve subscribed a customer to a price with a non-zero amount and a zero-amount quantity, changing the quantity to a non-zero amount doesn’t generate an invoice or reset the billing period.