> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Atualizar um plano de assinatura

O Localpayment permite que você modifique planos de assinatura existentes para se adequar a mudanças em sua estratégia de preços, ciclos de faturamento ou ofertas de serviços. Este guia detalha como atualizar um plano de assinatura por meio da API do Localpayment, garantindo que as assinaturas existentes possam continuar sob os novos termos ou de acordo com suas políticas configuradas.

## Antes de começar

Certifique-se de ter:

> [card] [Credenciais da API](https://docs.localpayment.com/pt-br/docs/api-keys-and-environments.md)
>
> Credenciais de API e token de acesso válidos para autenticação.

> [card] [Configuração da conta](https://docs.localpayment.com/pt-br/docs/make-your-first-test-payment.md)
>
> Configuração adequada da conta para o país de destino e verificação da empresa.

> [card] [Lista branca de IPs](https://docs.localpayment.com/pt-br/docs/dashboard-whitelist-your-ips.md)
>
> Adicione os endereços IP do seu servidor à lista de permissões para acesso à API.

> [card] [Endpoint do webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure um URL de webhook para receber notificações de pagamento.

***

## Passo 1: Atualizar um plano de assinatura

Para modificar um plano de assinatura existente, envie uma requisição `PATCH` para o endpoint [Update Subscription Plan](https://docs.localpayment.com/pt-br/reference/update-subscription-plan).

### Parâmetros-chave da solicitação

A solicitação requer vários parâmetros-chave:

| Parâmetro | Descrição | Obrigatório |
| - | - | - |
| `amount` | Valor de faturamento atualizado | ❌ |
| `autoRecurring` | Configuração atualizada para cobrança recorrente automática | ❌ |
| `autoRecurring.repetitions` | Número atualizado de ciclos de faturamento (use `0` para recorrência sob demanda) | ❌ |
| `autoRecurring.type` | Unidade atualizada de frequência de faturamento (use `custom` para recorrência sob demanda) | ❌ |

### Frequências de faturamento suportadas

> [card] Diário
>
> Atualização para faturamento diário. Ideal para serviços que estão migrando para padrões de uso diário.
>
> Envie a propriedade `autoRecurring.type` com o valor: `day`

> [card] Mensal
>
> Atualização para faturamento mensal. Prática comum para padronizar os ciclos de faturamento entre as linhas de produtos.
>
> Envie a propriedade `autoRecurring.type` com o valor: `month`

> [card] Personalizado (sob demanda)
>
> Atualização para faturamento sob demanda. Ideal para a transição para modelos de precificação baseados no uso.
>
> Envie a propriedade `autoRecurring.type` com o valor: `custom`

### Exemplo de solicitação

Abaixo está um exemplo usando `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request PATCH \
  --url 'https://api.stage.localpayment.com/api/subscriptions/plan/{internalId}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 150,
    "autoRecurring": {
      "repetitions": 1,
      "type": "month"
    }
  }'
```

Veja todos os [parâmetros disponíveis](https://docs.localpayment.com/pt-br/reference/update-subscription-plan) na solicitação.

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Um plano de assinatura atualizado com sucesso retorna uma confirmação com o status atual:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "internalId": "106e9aff-96da-42e9-a9e1-4dee207e6073",
    "status": {
        "code": "100",
        "description": "ACTIVE",
        "detail": "Subscription plan was update"
    }
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `internalId` | Identificador exclusivo do plano na Localpayment. | Verifique se você atualizou o plano correto. |
| `status.code` | Código de status do plano atual. | Confirme se o plano permanece ativo após as atualizações. |
| `status.description` | Descrição do status em linguagem acessível a humanos. | Exibir o status nas interfaces administrativas. |
| `status.detail` | Informações detalhadas sobre o status. | Confirme se a operação de atualização foi bem-sucedida. |

### Resposta de erro

Quando uma atualização do plano de assinatura falhar, você receberá informações detalhadas sobre o erro:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "400",
    "description": "REJECTED",
    "detail": "amount must be greater than or equal to 1"
  }
}
```

***

## Etapa 3: Rastrear o status da transação

Após atualizar um plano de assinatura, monitore o status dele por meio destes métodos:

> [card] [Webhooks (Recomendado)](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Receba notificações em tempo real quando o status da transação mudar. Ideal para ambientes de produção.

> [card] [Endpoint da API de Status](https://docs.localpayment.com/pt-br/reference/get-transaction-status.md)
>
> Consultar o status da transação programaticamente. Útil para consultar ou recuperar notificações de webhook perdidas.

> [card] [Visualização do Business Portal](https://docs.localpayment.com/pt-br/docs/dashboard-overview.md)
>
> Interface visual para monitoramento de transações. Ideal para supervisão manual e análise detalhada de transações.

### Códigos de status comuns

| Código | Status | Descrição |
| :- | :- | :- |
| `100` | `ACTIVE` | O plano está ativo e disponível para associações assinantes. |
| `400` | `REJECTED` | A atualização do plano falhou devido a erros de validação ou parâmetros inválidos. |

> [!NOTE]
>
> **Referência completa**
>
> Consulte todos os códigos de status em nossa [Documentação de Status da Transação](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes).

***

## Testando sua integração

### Cenários de teste

Verifique se sua integração lida com esses cenários:

1. **Atualização de valor concluída com sucesso**: Modifique o preço do plano com valores válidos.
2. **Alteração da frequência de faturamento**: Atualize de faturamento mensal para diário ou personalizado.
3. **Atualizações parciais**: Modifique apenas campos específicos sem enviar a carga útil completa.
4. **Erros de validação**: Teste com valores inválidos, campos obrigatórios ausentes ou frequências não suportadas.
5. **Plano inexistente**: Tentativa de atualizar um plano que não existe.
6. **Falhas de autenticação**: Teste com tokens de acesso inválidos ou expirados.

***

## Próximos passos

Após atualizar um plano de assinatura, talvez seja necessário realizar ações adicionais:

> [card] [Criar um novo plano de assinatura](https://docs.localpayment.com/pt-br/docs/create-a-subscription-plan.md)
>
> Configure planos de assinatura adicionais para diferentes faixas de preço ou níveis de serviço.

> [card] [Criar assinatura com plano atualizado](https://docs.localpayment.com/pt-br/docs/create-a-subscription.md)
>
> Crie novas assinaturas usando seu plano atualizado para testar as alterações.

> [card] [Confira os detalhes do plano de assinatura](https://docs.localpayment.com/pt-br/docs/get-subscription-plan.md)
>
> Recupere as informações atualizadas do plano para verificar se todas as alterações foram aplicadas corretamente.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.