# Alterar o preço de assinaturas existentes

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

Este guia é dedicado ao uso da API Subscriptions para gerenciar assinaturas de clientes.

Você também pode implementar o [portal de clientes](https://docs.stripe.com/customer-management.md) para oferecer um Dashboard hospedado pela Stripe onde os clientes podem gerenciar detalhes de suas assinaturas e faturamento.

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.

> #### Use a API Accounts v2 para representar clientes
> 
> Se sua integração usar [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), substitua `Customer` e as referências a eventos nos exemplos de código pelas referências equivalentes da API Accounts v2. Para mais informações, consulte [Representar clientes com objetos Account](https://docs.stripe.com/connect/use-accounts-as-customers.md).

## 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](https://docs.stripe.com/api/subscriptions/list.md) com um filtro apropriado (como o ID do cliente) para localizar a assinatura e o item que precisam ser atualizados.

```curl
curl -G https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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`).

```json
{
  "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](https://docs.stripe.com/api.md#update_subscription) 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
curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "items[0][id]={{SUB_ITEM_ID}}" \
  -d "items[0][price]={{NEW_PRICE_ID}}"
```

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

```curl
curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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](https://docs.stripe.com/api/assinatura_items/update.md) utilizando os parâmetros abaixo:

- [price](https://docs.stripe.com/api/subscription_items/update.md#update_subscription_item-price): Informe o identificador correspondente ao novo preço a ser aplicado.
- [quantity](https://docs.stripe.com/api/subscription_items/update.md#update_subscription_item-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
curl https://api.stripe.com/v1/subscription_items/si_xxxxxxxxx \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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 ao final do período de cobrança, considere usar um [cronograma de assinatura](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#changing-subscriptions) para gerenciar a transição. Ao usar cronogramas de assinatura, siga as [práticas recomendadas](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#subscription-schedule-sub-updates) para evitar substituiçõ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](https://docs.stripe.com/billing/subscriptions/usage-based/manage-billing-setup.md#mid-cycle-updates). 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
curl https://api.stripe.com/v1/subscriptions/sub_xxxxxxxxx \
  -u "<<YOUR_SECRET_KEY>>:" \
  -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](https://docs.stripe.com/billing/subscriptions/prorations.md) 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](https://docs.stripe.com/billing/subscriptions/prorations.md#preview-proration). Você também pode [desativar as cobranças proporcionais](https://docs.stripe.com/billing/subscriptions/prorations.md#disable-prorations).

### 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](https://docs.stripe.com/billing/subscriptions/billing-cycle.md#changing).

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 período de cobrança, defina `proration_behavior` como `always_invoice`. O pro rata será calculado e uma *fatura* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) será gerada imediatamente após a alteração. Combine essa configuração com [atualizações pendentes](https://docs.stripe.com/billing/subscriptions/pending-updates.md) 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](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_mode) da sua assinatura. Consulte [Pro ratas de crédito](https://docs.stripe.com/billing/subscriptions/prorations.md#credit-prorations) 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](https://docs.stripe.com/billing/subscriptions/change-price.md#billing-periods) 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.

## See also

- [Período de cobrança (ciclo)](https://docs.stripe.com/billing/subscriptions/billing-cycle.md)
- [Cancelar e suspender](https://docs.stripe.com/billing/subscriptions/cancel.md)
- [API Update Subscription](https://docs.stripe.com/api.md#update_subscription)