> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> O objeto Subscription

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.*`.

```json theme={}
{
  "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"
}
```

<ResponseField name="id" type="string">
  Identificador da subscription. Usa o prefixo `sub_*`.
</ResponseField>

<ResponseField name="object" type="string">
  Sempre `"subscription"`.
</ResponseField>

<ResponseField name="billing_cycle_anchor" type="string">
  Data que ancora os ciclos completos de cobrança da subscription em ISO 8601.
</ResponseField>

<ResponseField name="billing_mode" type="object">
  Configuração de modo de cobrança da subscription.

  <Expandable title="Campos de billing_mode">
    <ResponseField name="type" type="string">
      Modo de cobrança. O valor padrão é `classic`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancel_at" type="string | null">
  Data agendada para o cancelamento quando `cancel_at_period_end` é `true`. Vem
  `null` quando não há cancelamento agendado.
</ResponseField>

<ResponseField name="cancel_at_period_end" type="boolean">
  `true` quando a subscription está marcada para cancelar no fim do período
  atual; `false` caso contrário.
</ResponseField>

<ResponseField name="canceled_at" type="string | null">
  Data em que o cancelamento foi solicitado ou efetivado em ISO 8601. Vem `null`
  enquanto a subscription não foi cancelada.
</ResponseField>

<ResponseField name="cancellation_details" type="object">
  Contexto do cancelamento. Os campos vêm `null` quando não há cancelamento.

  <Expandable title="Campos de cancellation_details">
    <ResponseField name="comment" type="string | null">
      Comentário livre informado no cancelamento.
    </ResponseField>

    <ResponseField name="feedback" type="string | null">
      Motivo escolhido pelo cliente. Um de `customer_service`, `low_quality`,
      `missing_features`, `other`, `switched_service`, `too_complex`,
      `too_expensive` ou `unused`.
    </ResponseField>

    <ResponseField name="reason" type="string | null">
      Motivo definido pela Chargefy. Um de `cancellation_requested`,
      `canceled_by_retention_policy`, `payment_disputed` ou `payment_failed`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="collection_method" type="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`.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data de criação em ISO 8601.
</ResponseField>

<ResponseField name="currency" type="string">
  Moeda da subscription em código ISO de 3 letras minúsculas, como `brl`.
</ResponseField>

<ResponseField name="current_period_end" type="string">
  Fim do período de cobrança atual em ISO 8601. É também quando a próxima
  renovação ocorre.
</ResponseField>

<ResponseField name="current_period_start" type="string">
  Início do período de cobrança atual em ISO 8601.
</ResponseField>

<ResponseField name="customer" type="string">
  ID do customer dono da subscription (`cus_*`).
</ResponseField>

<ResponseField name="days_until_due" type="integer | null">
  Número de dias até o vencimento das faturas criadas com
  `collection_method: "send_invoice"`. Vem `null` quando não foi definido.
</ResponseField>

<ResponseField name="default_payment_method" type="string | null">
  Payment method usado nas cobranças automáticas (`pm_*`). Vem `null` quando
  nenhum método padrão foi definido.
</ResponseField>

<ResponseField name="discount" type="string | null">
  Desconto aplicado à subscription nas invoices recorrentes.
</ResponseField>

<ResponseField name="ended_at" type="string | null">
  Data em que a subscription chegou a um estado final. Vem `null` enquanto a
  assinatura ainda pode renovar ou ser recuperada.
</ResponseField>

<ResponseField name="items" type="object">
  Lista dos itens recorrentes da subscription, no formato de lista padrão.

  <Expandable title="Campos de items">
    <ResponseField name="object" type="string">
      Sempre `"list"`.
    </ResponseField>

    <ResponseField name="data" type="array">
      Array de `subscription_item`.

      <Expandable title="Campos de subscription_item">
        <ResponseField name="id" type="string">
          Identificador do item. Usa o prefixo `si_*`.
        </ResponseField>

        <ResponseField name="object" type="string">
          Sempre `"subscription_item"`.
        </ResponseField>

        <ResponseField name="subscription" type="string">
          ID da subscription dona do item (`sub_*`).
        </ResponseField>

        <ResponseField name="position" type="integer">
          Posição do item na subscription, começando em `0`.
        </ResponseField>

        <ResponseField name="product" type="string | null">
          ID do produto do catálogo (`prod_*`). Vem `null` quando o item usa
          um preço definido na hora.
        </ResponseField>

        <ResponseField name="price" type="string | null">
          ID do preço do catálogo (`price_*`). Vem `null` quando o item usa
          `price_data`.
        </ResponseField>

        <ResponseField name="price_data" type="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`.
        </ResponseField>

        <ResponseField name="quantity" type="integer">
          Quantidade cobrada do item.
        </ResponseField>

        <ResponseField name="currency" type="string">
          Moeda do item em código ISO de 3 letras minúsculas.
        </ResponseField>

        <ResponseField name="unit_amount" type="integer">
          Valor unitário em centavos.
        </ResponseField>

        <ResponseField name="amount_subtotal" type="integer">
          Subtotal do item em centavos (`unit_amount` × `quantity`).
        </ResponseField>

        <ResponseField name="amount_discount" type="integer">
          Desconto aplicado ao item em centavos.
        </ResponseField>

        <ResponseField name="amount_tax" type="integer">
          Imposto aplicado ao item em centavos.
        </ResponseField>

        <ResponseField name="amount_total" type="integer">
          Total do item em centavos (`amount_subtotal` − `amount_discount` +
          `amount_tax`).
        </ResponseField>

        <ResponseField name="recurring" type="object | null">
          Intervalo de recorrência do item. Vem `null` quando o item não é
          recorrente.

          <Expandable title="Campos de recurring">
            <ResponseField name="interval" type="string">
              Unidade do ciclo: `day`, `week`, `month` ou `year`.
            </ResponseField>

            <ResponseField name="interval_count" type="integer">
              Quantidade de `interval` por ciclo.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="metadata" type="object">
          Objeto livre do item. Quando vazio, retorna `{}`.
        </ResponseField>

        <ResponseField name="created_at" type="string">
          Data de criação do item em ISO 8601.
        </ResponseField>

        <ResponseField name="updated_at" type="string | null">
          Data da última atualização do item em ISO 8601. Vem `null` enquanto
          o item nunca foi atualizado.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="has_more" type="boolean">
      Indica se há mais itens além dos retornados.
    </ResponseField>

    <ResponseField name="url" type="string">
      URL relativa dos itens desta subscription.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="latest_invoice" type="string | null">
  Invoice mais recente da subscription. Vem `null` antes da primeira invoice.
</ResponseField>

<ResponseField name="livemode" type="boolean">
  `true` em produção; `false` em ambiente de teste.
</ResponseField>

<ResponseField name="metadata" type="object">
  Objeto livre para correlacionar a subscription com o seu sistema. Quando
  vazio, retorna `{}`.
</ResponseField>

<ResponseField name="next_billing_at" type="string">
  Momento da próxima tentativa de cobrança em ISO 8601.
</ResponseField>

<ResponseField name="pause_collection" type="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.

  <Expandable title="Campos de pause_collection">
    <ResponseField name="behavior" type="string">
      Comportamento aplicado às faturas durante a pausa: `keep_as_draft`,
      `mark_uncollectible` ou `void`.
    </ResponseField>

    <ResponseField name="resumes_at" type="string | null">
      Data de retomada automática em ISO 8601, quando definida.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_settings" type="object">
  Configurações de pagamento usadas pelas faturas criadas pela subscription.
</ResponseField>

<ResponseField name="pending_setup_intent" type="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`.
</ResponseField>

<ResponseField name="pending_update" type="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`.
</ResponseField>

<ResponseField name="resumed_at" type="string | null">
  Data da última retomada de uma subscription pausada. Vem `null` quando nunca
  foi retomada.
</ResponseField>

<ResponseField name="schedule" type="string | null">
  Subscription schedule associado, quando existe.
</ResponseField>

<ResponseField name="schedule_phase_index" type="integer | null">
  Índice da fase atual dentro da schedule associada.
</ResponseField>

<ResponseField name="start_date" type="string">
  Data de início da subscription em ISO 8601.
</ResponseField>

<ResponseField name="status" type="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`.
</ResponseField>

<ResponseField name="trial_end" type="string | null">
  Fim do período de trial em ISO 8601 para subscriptions iniciadas em trial. Vem
  `null` em subscriptions sem trial.
</ResponseField>

<ResponseField name="trial_settings" type="object">
  Política aplicada quando o trial termina.

  <Expandable title="Campos de trial_settings">
    <ResponseField name="end_behavior" type="object">
      Comportamento de fim de trial.
    </ResponseField>

    <ResponseField name="missing_payment_method" type="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.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="trial_start" type="string | null">
  Início do trial em ISO 8601. Vem `null` em subscriptions sem trial.
</ResponseField>

<ResponseField name="updated_at" type="string | null">
  Data da última atualização em ISO 8601. Vem `null` enquanto a subscription
  nunca foi atualizada.
</ResponseField>

## Operações

* [Listar subscriptions](/api-reference/subscriptions/list)
* [Criar subscription](/api-reference/subscriptions/create)
* [Consultar subscription](/api-reference/subscriptions/get)
* [Atualizar subscription](/api-reference/subscriptions/update)
* [Cancelar subscription imediatamente](/api-reference/subscriptions/delete)

## Webhooks

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

* [`subscription.created`](/api-reference/webhooks/subscription.created)
* [`subscription.updated`](/api-reference/webhooks/subscription.updated)
* [`subscription.canceled`](/api-reference/webhooks/subscription.canceled)
* [`subscription.paused`](/api-reference/webhooks/subscription.paused)
* [`subscription.resumed`](/api-reference/webhooks/subscription.resumed)
* [`subscription.trial.will.end`](/api-reference/webhooks/subscription.trial.will.end)
* [`subscription.pending.update.applied`](/api-reference/webhooks/subscription.pending.update.applied)
* [`subscription.pending.update.expired`](/api-reference/webhooks/subscription.pending.update.expired)

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.