Skip to main content
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"
    }
  }'

{
  "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"
}
Atualiza uma subscription. A resposta direta retorna o objeto completo atualizado; o diff sai apenas no webhook subscription.updated.
​
id
string
required
ID da subscription (sub_*).
​
default_payment_method
string
Payment method padrão para próximas cobranças (pm_*). Envie null para remover.
​
collection_method
string
charge_automatically ou send_invoice.
​
days_until_due
integer
Dias até vencimento quando collection_method é send_invoice.
​
billing_cycle_anchor
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.
​
trial_end
string
Timestamp ISO 8601, now ou null.
​
trial_settings
object
Configuração do fim de trial.
​
discount
string
Desconto aplicado às invoices recorrentes. Envie null para remover.
​
pause_collection
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.
​
cancel_at_period_end
boolean
Quando true, agenda o cancelamento no fim do período atual. Quando false, remove um cancelamento agendado.
​
cancellation_details
object
Detalhes do cancelamento. Aceita comment e feedback; reason é definido pela Chargefy.
​
metadata
object
Metadata livre.
​
items
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.
​
proration_behavior
string
create_prorations, always_invoice ou none. Padrão: create_prorations.
​
payment_behavior
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.
​
proration_date
string
Timestamp ISO 8601 usado para calcular a proration. Não pode ser usado com proration_behavior: "none".

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

​
Atualizar atributos

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

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

​
Resposta

200 OK com o objeto subscription completo — mesmo shape de GET /v1/subscriptions/:id. 
{
  "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"
}