Overview - Chargefy

Uma subscription é uma assinatura. Ela representa o acordo de cobrança recorrente entre você e um customer: ela guarda o que está sendo cobrado (items), o estado do relacionamento, o método de pagamento padrão, a próxima cobrança e a política de trial. A cadência vem dos preços/itens recorrentes; a assinatura é a fonte de verdade para trial_start, trial_end e trial_settings.

Data Object

Este é o formato completo retornado em create, get, update, delete, itens de list e em data.object dos webhooks subscription.*.

{
  "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_456",
  "days_until_due": null,
  "default_payment_method": "pm_789",
  "discount": null,
  "ended_at": null,
  "items": {
    "object": "list",
    "data": [
      {
        "id": "si_123",
        "object": "subscription_item",
        "aggregate_usage": "sum",
        "amount_discount": 0,
        "amount_subtotal": 9900,
        "amount_tax": 0,
        "amount_total": 9900,
        "created_at": "2026-05-19T18:00:00Z",
        "currency": "brl",
        "discount": null,
        "metadata": {},
        "position": 0,
        "price": "price_123",
        "price_data": null,
        "product": "prod_123",
        "quantity": 1,
        "recurring": {
          "interval": "month",
          "interval_count": 1
        },
        "subscription": "sub_123",
        "unit_amount": 9900,
        "updated_at": null,
        "usage_period_end": null,
        "usage_period_start": null,
        "usage_type": "licensed"
      }
    ],
    "has_more": false,
    "url": "/v1/subscription-items?subscription=sub_123"
  },
  "latest_invoice": "in_123",
  "livemode": true,
  "metadata": {},
  "next_billing_at": "2026-06-19T18:00:00Z",
  "pause_collection": null,
  "payment_settings": {},
  "pending_setup_intent": null,
  "pending_update": null,
  "resumed_at": null,
  "schedule": null,
  "schedule_phase_index": 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:00:00Z"
}

string

Identificador da subscription. Usa o prefixo sub_*.

object

string

Sempre "subscription".

billing_cycle_anchor

string

Data que ancora os ciclos completos de cobrança da subscription em ISO 8601.

billing_mode

object

Configuração de modo de cobrança da subscription.

Show Campos de billing_mode

type

string

Modo de cobrança. O valor padrão é classic.

cancel_at

string | null

Data agendada para o cancelamento quando cancel_at_period_end é true. Vem null quando não há cancelamento agendado.

cancel_at_period_end

boolean

true quando a subscription está marcada para cancelar no fim do período atual; false caso contrário.

canceled_at

string | null

Data em que o cancelamento foi solicitado ou efetivado em ISO 8601. Vem null enquanto a subscription não foi cancelada.

cancellation_details

object

Contexto do cancelamento. Os campos vêm null quando não há cancelamento.

Show Campos de cancellation_details

comment

string | null

Comentário livre informado no cancelamento.

feedback

string | null

Motivo escolhido pelo cliente. Um de customer_service, low_quality, missing_features, other, switched_service, too_complex, too_expensive ou unused.

reason

string | null

Motivo definido pela Chargefy. Um de cancellation_requested, canceled_by_retention_policy, payment_disputed ou payment_failed.

collection_method

string

Forma de cobrança. charge_automatically (padrão): cada ciclo é cobrado automaticamente no método de pagamento padrão. send_invoice: a cada ciclo a Chargefy envia um link de pagamento (PIX ou boleto) e a fatura é cobrada manualmente — não há cartão arquivado. Quando um cartão é definido como padrão, a assinatura passa automaticamente para charge_automatically.

created_at

string

Data de criação em ISO 8601.

currency

string

Moeda da subscription em código ISO de 3 letras minúsculas, como brl.

current_period_end

string

Fim do período de cobrança atual em ISO 8601. É também quando a próxima renovação ocorre.

current_period_start

string

Início do período de cobrança atual em ISO 8601.

customer

string

ID do customer dono da subscription (cus_*).

days_until_due

integer | null

Número de dias até o vencimento das faturas criadas com collection_method: "send_invoice". Vem null quando não foi definido.

default_payment_method

string | null

Payment method usado nas cobranças automáticas (pm_*). Vem null quando nenhum método padrão foi definido.

discount

string | null

Desconto aplicado à subscription nas invoices recorrentes.

ended_at

string | null

Data em que a subscription chegou a um estado final. Vem null enquanto a assinatura ainda pode renovar ou ser recuperada.

items

object

Lista dos itens recorrentes da subscription, no formato de lista padrão.

Show Campos de items

object

string

Sempre "list".

data

array

Array de subscription_item.

Show Campos de subscription_item

string

Identificador do item. Usa o prefixo si_*.

object

string

Sempre "subscription_item".

subscription

string

ID da subscription dona do item (sub_*).

position

integer

Posição do item na subscription, começando em 0.

product

string | null

ID do produto do catálogo (prod_*). Vem null quando o item usa um preço definido na hora.

price

string | null

ID do preço do catálogo (price_*). Vem null quando o item usa price_data.

price_data

object | null

Preço definido na criação do item, em vez de um price do catálogo. Vem null quando o item aponta para um price.

quantity

integer

Quantidade cobrada do item.

currency

string

Moeda do item em código ISO de 3 letras minúsculas.

unit_amount

integer

Valor unitário em centavos.

amount_subtotal

integer

Subtotal do item em centavos (unit_amount × quantity).

amount_discount

integer

Desconto aplicado ao item em centavos.

amount_tax

integer

Imposto aplicado ao item em centavos.

amount_total

integer

Total do item em centavos (amount_subtotal − amount_discount + amount_tax).

recurring

object | null

Intervalo de recorrência do item. Vem null quando o item não é recorrente.

Show Campos de recurring

interval

string

Unidade do ciclo: day, week, month ou year.

interval_count

integer

Quantidade de interval por ciclo.

metadata

object

Objeto livre do item. Quando vazio, retorna {}.

created_at

string

Data de criação do item em ISO 8601.

updated_at

string | null

Data da última atualização do item em ISO 8601. Vem null enquanto o item nunca foi atualizado.

has_more

boolean

Indica se há mais itens além dos retornados.

url

string

URL relativa dos itens desta subscription.

latest_invoice

string | null

Invoice mais recente da subscription. Vem null antes da primeira invoice.

livemode

boolean

true em produção; false em ambiente de teste.

metadata

object

Objeto livre para correlacionar a subscription com o seu sistema. Quando vazio, retorna {}.

next_billing_at

string

Momento da próxima tentativa de cobrança em ISO 8601.

pause_collection

object | null

Configuração para pausar a cobrança de faturas mantendo a subscription no status atual. Vem null quando a cobrança não está pausada.

Show Campos de pause_collection

behavior

string

Comportamento aplicado às faturas durante a pausa: keep_as_draft, mark_uncollectible ou void.

resumes_at

string | null

Data de retomada automática em ISO 8601, quando definida.

payment_settings

object

Configurações de pagamento usadas pelas faturas criadas pela subscription.

pending_setup_intent

string | null

Setup intent pendente para coletar ou confirmar método de pagamento reutilizável. Em trials criados sem default_payment_method, a Chargefy cria esse setup intent automaticamente; ao confirmá-lo, o método salvo vira o default_payment_method da subscription e este campo volta para null.

pending_update

object | null

Atualização pendente criada por payment_behavior: "pending_if_incomplete". Quando presente, inclui invoice, expires_at e subscription_items. A alteração é aplicada quando a invoice associada é paga; se expirar antes, volta para null.

resumed_at

string | null

Data da última retomada de uma subscription pausada. Vem null quando nunca foi retomada.

schedule

string | null

Subscription schedule associado, quando existe.

schedule_phase_index

integer | null

Índice da fase atual dentro da schedule associada.

start_date

string

Data de início da subscription em ISO 8601.

status

string

Estado atual da subscription. Um de incomplete, incomplete_expired, trialing, active, past_due, canceled, unpaid ou paused. paused só ocorre quando um trial termina sem payment method e trial_settings.end_behavior.missing_payment_method é pause.

trial_end

string | null

Fim do período de trial em ISO 8601 para subscriptions iniciadas em trial. Vem null em subscriptions sem trial.

trial_settings

object

Política aplicada quando o trial termina.

Show Campos de trial_settings

end_behavior

object

Comportamento de fim de trial.

missing_payment_method

string

Dentro de end_behavior. Um de create_invoice, pause ou cancel. pause deixa a subscription em paused sem gerar a invoice do fim do trial; create_invoice abre a invoice e pode levar a past_due; cancel cancela a subscription no fim do trial.

trial_start

string | null

Início do trial em ISO 8601. Vem null em subscriptions sem trial.

updated_at

string | null

Data da última atualização em ISO 8601. Vem null enquanto a subscription nunca foi atualizada.

Operações

Webhooks

Mudanças nesse objeto disparam os seguintes eventos de webhook:

O payload sempre carrega o objeto subscription completo em data.object; eventos de update também incluem data.previous_attributes com os valores anteriores dos campos alterados.

​Data Object

​Operações

​Webhooks

Data Object

Operações

Webhooks