> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# PATCH /api/v1/subscriptions/:id

> Atualiza uma assinatura existente, como trocar de plano, aplicar desconto ou agendar cancelamento

Permite atualizar propriedades de uma assinatura. Também pode ser usado para agendar cancelamento ao fim do período (`cancel_at_period_end: true`) ou revogar imediatamente (`revoke: true`).

## Autenticação

> [!NOTE]
>
> Requer um token de acesso válido (`CHARGEFY_ACCESS_TOKEN`) no header `Authorization`. Escopos necessários: `web:write` ou `subscriptions:write`.

## Parâmetros de Path

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `id` | `string` | Sim | ID da assinatura |

## Parâmetros do Body

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `product_price_id` | `string` | Não | Novo ID de preço para troca de plano |
| `discount_id` | `string \| null` | Não | ID do desconto a aplicar (ou `null` para remover) |
| `user_metadata` | `object` | Não | Metadados personalizados do usuário |
| `cancel_at_period_end` | `boolean` | Não | Agendar cancelamento ao fim do período atual |
| `revoke` | `boolean` | Não | Revogar a assinatura imediatamente |
| `customer_cancellation_reason` | `string` | Não | Motivo do cancelamento informado pelo cliente. Valores: `customer_service`, `low_quality`, `missing_features`, `switched_service`, `too_complex`, `too_expensive`, `unused`, `other` |
| `customer_cancellation_comment` | `string` | Não | Comentário livre do cliente sobre o cancelamento |

> [!NOTE]
>
> Quando `cancel_at_period_end: true` ou `revoke: true` são enviados, os demais campos de atualização são ignorados e a operação de cancelamento tem precedência.

## Campos da Resposta

Retorna o objeto completo da assinatura atualizada (mesmos campos de [Obter Assinatura](https://scaleup-c34c4386.mintlify.site/api-reference/subscriptions/get.md)).

## Exemplo de Requisição

```bash cURL theme={null}
curl -X PATCH "https://api.chargefy.io/api/v1/subscriptions/sub_1a2b3c4d" \
  -H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_price_id": "price_new789",
    "discount_id": "disc_xyz"
  }'
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const subscription = await chargefy.subscriptions.update('sub_1a2b3c4d', {
  product_price_id: 'price_new789',
  discount_id: 'disc_xyz',
});
```

## Exemplo de Resposta

```json theme={null}
{
  "id": "sub_1a2b3c4d",
  "status": "active",
  "customer_id": "cus_9x8y7z",
  "product_id": "prod_abc123",
  "product_price_id": "price_new789",
  "discount_id": "disc_xyz",
  "current_period_start": "2026-03-01T00:00:00Z",
  "current_period_end": "2026-04-01T00:00:00Z",
  "cancel_at_period_end": false,
  "created_at": "2026-01-15T10:30:00Z"
}
```


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