> ## 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 uma assinatura

A Localpayment permite que você modifique assinaturas existentes para acomodar mudanças nas necessidades dos clientes, como upgrade ou downgrade de planos, atualização das informações de cobrança ou alteração da frequência da assinatura. Este guia detalha o processo de atualização de uma assinatura por meio da API da Localpayment.

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

***

## Etapa 1: Atualizar uma assinatura

Para modificar uma assinatura existente, envie uma solicitação `PATCH` para o endpoint [Atualizar uma assinatura](https://docs.localpayment.com/pt-br/reference/create-a-subscription.md).

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

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

| Parâmetro | Descrição |
| - | - |
| `amount` | Novo valor da assinatura |
| `card` | Objeto de cartão com os dados de pagamento atualizados |
| `autoRecurring` | Configurações de frequência e repetição da cobrança |
| `discount` | Configuração de desconto a aplicar à assinatura |
| `retry` | Configuração de nova tentativa de pagamento para cobranças com falha |
| `dateToUpdate` | Data específica em que as alterações devem entrar em vigor |
| `suspension` | Configurações de suspensão da assinatura |
| `status` | Mudança de status da assinatura (por exemplo, pausar/retomar) |

### Exemplo de solicitação

Abaixo segue um exemplo de uso. `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/payin/subscriptions/{externalId} \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "dateToUpdate": "2025-10-28",
    "amount": 1600.00,

   "autoRecurring": {
        "repetitions": "2",
        "type": "hour"
    },

   "retry": {
    "repetitions": 2,
    "intervalUnit": "day",
    "intervalValue": 1
  }
}
'

```

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

***

## Etapa 2: Lidar com a resposta

### Resposta bem-sucedida

Uma atualização bem-sucedida retorna os detalhes da assinatura modificada:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "564b161a-76ba-4a84-b5cf-583f2df8c377",
  "internalId": "52425bbd-b68b-4abc-9480-5ae88d53adb3",
  "status": {
    "code": "107",
    "description": "APPROVED",
    "detail": "Update subscription success"
  },
  "errors": []
}
```

### Campos de resposta principais

| Parâmetro | Descrição | Caso de uso |
| - | - | - |
| `status.code` | Código de status atual da assinatura. | Monitoramento de status. |

### Resposta de erro

Quando uma solicitação 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": "ERROR",
    "detail": "Invalid operation"
  }
}
```

***

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

Após atualizar uma assinatura, monitore o status dela 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

A API Localpayment fornece vários códigos de status para indicar o progresso e o resultado do pagamento na resposta.

| Código | Status | Descrição |
| :- | :- | :- |
| `107` | `APPROVED` | A atualização foi aprovada e aplicada. |
| `400` | `ERROR` | A atualização da assinatura foi rejeitada. |

> [!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. **Upgrade de plano bem-sucedido**: aumento do nível ou do valor da assinatura.
2. **Downgrade de plano bem-sucedido**: redução do nível ou do valor da assinatura.
3. **Atualização do método de pagamento**: alteração dos dados do cartão.
4. **Atualização das informações do cliente**: modificação dos dados do cliente.
5. **Erros de validação**: valores inválidos, campos obrigatórios ausentes.
6. **Atualizações de status**: gerenciamento de webhooks e consulta de status

***

## Próximos passos

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

> [card] [Cancelar assinatura](https://docs.localpayment.com/pt-br/docs/cancel-a-subscription.md)
>
> Encerre assinaturas ativas quando as atualizações não forem suficientes.

> [card] [Gerenciar webhooks de assinatura](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure webhooks para receber notificações de eventos de atualização de assinatura.

> [card] [Criar planos de assinatura](https://docs.localpayment.com/pt-br/docs/create-a-subscription-plan.md)
>
> Crie novos planos que possam ser usados ao atualizar assinaturas.


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