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

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

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

​

Exemplo de Requisição

cURL

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"
  }'

​

Exemplo de Resposta

{
  "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"
}