Permite alterar a próxima data de vencimento (due_date) e/ou o valor (amount) de uma assinatura ativa. A alteração é propagada diretamente para o gateway de pagamentos.
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
Pelo menos um dos campos abaixo é obrigatório.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|
due_date | string | Condicional | Próxima data de vencimento no formato ISO (YYYY-MM-DD) |
amount | number | Condicional | Novo valor total em centavos (ex: 4990 para R$ 49,90). Deve ser positivo. Obrigatório quando cross_sell é não-vazio |
cross_sell | array | Condicional | Lista de add-ons (bundle). Substitui as linhas de bundle existentes na assinatura. Mesmas regras de validação do checkout. Envie um array vazio [] para remover todos os add-ons |
cross_sell:
| Campo | Tipo | Obrigatório | Descrição |
|---|
product_id | string | Sim | ID do produto add-on (deve pertencer à mesma organização) |
product_price_id | string | Não | ID do preço do produto add-on |
quantity | number | Sim | Quantidade |
amount_cents | number | Sim | Valor do add-on em centavos. A soma dos add-ons não pode exceder amount |
name_snapshot | string | Sim | Nome do produto no momento da criação |
Somente assinaturas com status: active, trialing, unpaid ou past_due podem ter o faturamento atualizado. Assinaturas com cobrança via gateway (billing_source: zoop_recurrence) também exigem um zoop_subscription_id configurado; assinaturas com cobrança manual (billing_source: chargefy_manual) não precisam desse identificador.
Campos da Resposta
Retorna o objeto completo da assinatura atualizada com current_period_start e current_period_end recalculados com base na nova data de vencimento.
Exemplo de Requisição
curl -X PATCH "https://api.chargefy.io/api/v1/subscriptions/sub_1a2b3c4d/billing" \
-H "Authorization: Bearer $CHARGEFY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"due_date": "2026-04-15",
"amount": 4990
}'
Exemplo de Resposta
{
"id": "sub_1a2b3c4d",
"status": "active",
"customer_id": "cus_9x8y7z",
"product_id": "prod_abc123",
"amount": 4990,
"current_period_start": "2026-03-15T00:00:00Z",
"current_period_end": "2026-04-15T00:00:00Z",
"modified_at": "2026-03-20T10:00:00Z"
}
