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

# Update a Subscription

> Atualiza uma subscription.

Atualiza uma `subscription`. A resposta direta retorna o objeto completo
atualizado; o diff sai apenas no webhook `subscription.updated`.

<ParamField path="id" type="string" required>
  ID da subscription (`sub_*`).
</ParamField>

<ParamField body="default_payment_method" type="string">
  Payment method padrão para próximas cobranças (`pm_*`). Envie `null` para
  remover.
</ParamField>

<ParamField body="collection_method" type="string">
  `charge_automatically` ou `send_invoice`.
</ParamField>

<ParamField body="days_until_due" type="integer">
  Dias até vencimento quando `collection_method` é `send_invoice`.
</ParamField>

<ParamField body="billing_cycle_anchor" type="string">
  `unchanged` para manter o ciclo atual, `now` para reiniciar o ciclo no momento
  do update, ou um timestamp ISO 8601 para definir uma âncora específica.
</ParamField>

<ParamField body="trial_end" type="string">
  Timestamp ISO 8601, `now` ou `null`.
</ParamField>

<ParamField body="trial_settings" type="object">
  Configuração do fim de trial.
</ParamField>

<ParamField body="discount" type="string">
  Desconto aplicado às invoices recorrentes. Envie `null` para remover.
</ParamField>

<ParamField body="pause_collection" type="object">
  Pausa cobrança de invoices sem mudar o status da subscription. Aceita
  `behavior` (`keep_as_draft`, `mark_uncollectible` ou `void`) e `resumes_at`.
  Envie `null` para retomar a cobrança.
</ParamField>

<ParamField body="cancel_at_period_end" type="boolean">
  Quando `true`, agenda o cancelamento no fim do período atual. Quando `false`,
  remove um cancelamento agendado.
</ParamField>

<ParamField body="cancellation_details" type="object">
  Detalhes do cancelamento. Aceita `comment` e `feedback`; `reason` é definido
  pela Chargefy.
</ParamField>

<ParamField body="metadata" type="object">
  Metadata livre.
</ParamField>

<ParamField body="items" type="array">
  Alterações nos itens da assinatura. Use `id` para atualizar um item, `deleted:
      true` para remover, ou omita `id` para adicionar um novo item. A assinatura
  deve manter ao menos um item ativo.
</ParamField>

<ParamField body="proration_behavior" type="string">
  `create_prorations`, `always_invoice` ou `none`. Padrão: `create_prorations`.
</ParamField>

<ParamField body="payment_behavior" type="string">
  Controla updates que criam cobrança imediata. Aceita `allow_incomplete`,
  `default_incomplete`, `pending_if_incomplete` ou `error_if_incomplete`.
  Padrão: `allow_incomplete`. Use `error_if_incomplete` apenas quando a
  alteração não gerar valor a cobrar imediatamente.
</ParamField>

<ParamField body="proration_date" type="string">
  Timestamp ISO 8601 usado para calcular a proration. Não pode ser usado com
  `proration_behavior: "none"`.
</ParamField>

## Limitações

Assinaturas com `status: "canceled"` ou `status: "incomplete_expired"` não
aceitam mudança de itens, cobrança, trial ou ciclo. Nesses estados, apenas
`metadata`, `cancellation_details` e `cancellation_reason` podem ser atualizados.

Updates de item mantêm a cadência recorrente da assinatura. O novo preço precisa
ter a mesma moeda, o mesmo intervalo e estar ativo. Para alterar o valor
recorrente, crie ou selecione outro preço; o `unit_amount` de um preço existente
não é editado no update da assinatura.

## Cancelar no fim do período

Use `cancel_at_period_end: true` quando o cliente deve manter acesso até
`current_period_end`. A assinatura continua com `status: "active"` até o corte,
`cancel_at` aponta para o fim do período e a mudança dispara
`subscription.updated`.

Para desfazer o agendamento antes do corte, envie
`cancel_at_period_end: false`.

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/subscriptions/sub_123" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "cancel_at_period_end": true,
      "cancellation_details": {
        "feedback": "too_expensive"
      }
    }'
  ```
</RequestExample>

## Atualizar atributos

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/subscriptions/sub_123" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "default_payment_method": "pm_123",
      "metadata": {
        "contract": "2026-0001"
      }
    }'
  ```
</RequestExample>

## Atualizar itens

Alterações em `price`, `price_data`, `quantity`, adição ou remoção de item
geram proration por padrão. `create_prorations` cria `invoice_items` pendentes
para a próxima invoice; `always_invoice` cria uma invoice de update
imediatamente; `none` aplica a alteração sem criar proration.

Em assinaturas em período de teste, os itens são atualizados sem ajuste
proporcional do ciclo atual. A cobrança recorrente passa a considerar o novo
conjunto de itens quando o trial terminar.

Use `payment_behavior: "pending_if_incomplete"` junto de
`proration_behavior: "always_invoice"` quando a alteração só deve ser aplicada
depois do pagamento da invoice de update. Enquanto a cobrança não fecha, a
subscription retorna `pending_update` com `invoice`, `expires_at` e
`subscription_items`.

Quando `always_invoice` cria uma invoice positiva, o saldo do cliente é aplicado
antes da cobrança. Se a invoice já ficar quitada, os eventos de criação e
pagamento da invoice são enviados. Se houver valor a cobrar, um payment intent é
criado para a cobrança.

<RequestExample>
  ```bash cURL theme={}
  curl -X POST "https://api.chargefy.io/v1/subscriptions/sub_123" \
    -H "Authorization: Bearer {{API_KEY}}" \
    -H "Content-Type: application/json" \
    -d '{
      "items": [
        {
          "id": "si_123",
          "price": "price_pro",
          "quantity": 3
        }
      ],
      "payment_behavior": "pending_if_incomplete",
      "proration_behavior": "always_invoice",
      "proration_date": "2026-05-20T12:00:00Z"
    }'
  ```
</RequestExample>

## Resposta

`200 OK` com o objeto `subscription` completo — mesmo shape de
[GET /v1/subscriptions/:id](/api-reference/subscriptions/get).

<ResponseExample>
  ```json Response 200 theme={}
  {
    "id": "sub_123",
    "object": "subscription",
    "billing_cycle_anchor": "2026-05-19T18:00:00Z",
    "billing_mode": {
      "type": "classic"
    },
    "cancel_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "cancellation_details": {
      "comment": null,
      "feedback": null,
      "reason": null
    },
    "collection_method": "charge_automatically",
    "created_at": "2026-05-19T18:00:00Z",
    "currency": "brl",
    "current_period_end": "2026-06-19T18:00:00Z",
    "current_period_start": "2026-05-19T18:00:00Z",
    "customer": "cus_123",
    "days_until_due": null,
    "default_payment_method": "pm_123",
    "ended_at": null,
    "items": {
      "object": "list",
      "data": [],
      "has_more": false,
      "url": "/v1/subscription-items?subscription=sub_123"
    },
    "latest_invoice": "in_123",
    "livemode": true,
    "metadata": {
      "contract": "2026-0001"
    },
    "next_billing_at": "2026-06-19T18:00:00Z",
    "pause_collection": null,
    "payment_settings": {},
    "pending_setup_intent": null,
    "pending_update": null,
    "start_date": "2026-05-19T18:00:00Z",
    "status": "active",
    "trial_end": null,
    "trial_settings": {
      "end_behavior": {
        "missing_payment_method": "create_invoice"
      }
    },
    "trial_start": null,
    "updated_at": "2026-05-19T18:10:00Z"
  }
  ```
</ResponseExample>