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

# Gerenciamento

> Pausar, retomar, cancelar, trocar plano, atualizar cartão, antecipar cobrança e aplicar cupons.

## Pausar

`PATCH /api/v1/subscriptions/{uuid}/pause` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "paused_until": "2026-09-01"
}
```

`paused_until` é opcional. Se informado, a assinatura retoma automaticamente nessa data via cron. Caso contrário, permanece pausada até um `resume` explícito.

Apenas assinaturas em `active` ou `trialing` podem ser pausadas.

***

## Retomar

`PATCH /api/v1/subscriptions/{uuid}/resume` — requer `X-Client-ID` + `X-API-Key`.

Corpo vazio. Recalcula `next_billing_at` a partir da data atual, respeitando o `billing_day`.

***

## Cancelar

`DELETE /api/v1/subscriptions/{uuid}` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "at_period_end": true
}
```

| `at_period_end`  | Comportamento                                                     |
| ---------------- | ----------------------------------------------------------------- |
| `false` (padrão) | Cancela imediatamente — sem cobrança do período em andamento      |
| `true`           | Agenda para o fim do período atual — cliente mantém acesso até lá |

Quando `at_period_end: true`, a assinatura continua `active` mas exibe `cancel_at_period_end: true` e `cancel_at` com a data de expiração. O cancelamento é executado automaticamente pelo cron.

***

## Trocar plano

`PATCH /api/v1/subscriptions/{uuid}/plan` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "new_plan_uuid": "018f9z8y-7x6w-5v4u-3t2s-1r0q9p8o7n6m",
  "immediately": false
}
```

| `immediately`    | Comportamento                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `false` (padrão) | Troca agendada para o início do próximo período                                                                                      |
| `true`           | Troca imediata com **pro-rata**: crédito proporcional ao tempo não utilizado no período atual é calculado e descontado do novo valor |

A troca é classificada automaticamente como `upgrade` (novo valor ≥ atual) ou `downgrade` (novo valor \< atual) e sinalizada no webhook.

***

## Atualizar cartão

`PATCH /api/v1/subscriptions/{uuid}/card` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "card_token": "card_novocartao..."
}
```

Use quando o cartão anterior for recusado (estado `past_due`) ou quando o cliente adicionar um novo método de pagamento. O cartão deve pertencer ao mesmo cliente da assinatura.

<Info>
  Após atualizar o cartão de uma assinatura `past_due`, chame **Antecipar** para tentar cobrar imediatamente sem esperar o próximo ciclo automático.
</Info>

***

## Antecipar

`POST /api/v1/subscriptions/{uuid}/anticipate` — requer `X-Client-ID` + `X-API-Key`.

Corpo vazio. Cobra o próximo ciclo **agora**, independentemente de `next_billing_at`. Ideal para:

* Reativar assinaturas `past_due` após atualização de cartão
* Testes de integração
* Cobranças sob demanda antecipadas pelo operador

Retorna o ciclo criado com o resultado da tentativa de cobrança.

***

## Aplicar cupom

`POST /api/v1/subscriptions/{uuid}/coupon` — requer `X-Client-ID` + `X-API-Key`.

```json theme={null}
{
  "coupon_code": "RETENCAO10"
}
```

Substitui o cupom atual (se houver). O desconto passa a valer a partir do próximo ciclo. O contador de `max_cycles` é resetado — os N ciclos com desconto são contados do zero.