> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Assinaturas & Recorrência

> Gerencie cobranças recorrentes com o sistema de recorrência da Chargefy

> [!NOTE]
>
> **Recorrência nativa**
>
> Na Chargefy, assinaturas são gerenciadas pelo sistema de recorrência nativo da plataforma. Ao criar um produto com preço recorrente e um cliente confirmar o checkout com cartão de crédito, a Chargefy automaticamente configura o plano de recorrência.

## Visão Geral

Uma assinatura na Chargefy representa uma relação contínua de cobrança entre um cliente e um produto. Diferente de pagamentos únicos, assinaturas cobram automaticamente o cliente em intervalos regulares.

### Frequências suportadas

O preço carrega `interval` + `interval_count`:

| Frequência | `interval` | `interval_count` | Exemplo |
| - | - | - | - |
| Diária | `day` | 1 | R\$ 1,99/dia |
| Semanal | `week` | 1 | R\$ 19,90/semana |
| Quinzenal | `week` | 2 | R\$ 34,90 a cada 2 semanas |
| Mensal | `month` | 1 | R\$ 49,90/mês |
| Trimestral | `month` | 3 | R\$ 129,90 a cada 3 meses |
| Semestral | `month` | 6 | R\$ 239,90 a cada 6 meses |
| Anual | `year` | 1 | R\$ 399,90/ano |

> [!NOTE]
>
> Assinaturas são cobradas exclusivamente via **cartão de crédito**. PIX e Boleto não suportam cobranças recorrentes automáticas. `interval_count > 1` está no schema mas a integração Zoop honra apenas `1` por ora (roadmap).

### Quantidade na assinatura

Cada linha de assinatura (`subscription_product_prices`) carrega um campo **`quantity`** (default `1`). O total cobrado por ciclo é `unit_amount × quantity`.

Use pra cobrar por assento, por licença, ou por unidade. Ver [Precificação por Quantidade](https://scaleup-c34c4386.mintlify.site/features/seat-based-pricing.md).

```typescript theme={null}
// Upgrade de 5 pra 10 assentos
await chargefy.subscriptions.update(subscriptionId, {
  quantity: 10,
})
// Próxima cobrança: unit_amount * 10
```

## Como funciona

### Criação de assinatura

**1. Produto recorrente**

Crie um produto com ciclo de cobrança recorrente (mensal, anual, semanal ou diário) no dashboard ou via API.

**2. Checkout**

O cliente acessa o checkout (via link, embed ou API) e seleciona cartão de crédito como método de pagamento.

**3. Primeira cobrança**

Ao confirmar o checkout, a Chargefy processa a primeira cobrança e cria um plano de recorrência automaticamente.

**4. Cobranças automáticas**

A Chargefy cobra automaticamente o cartão do cliente no intervalo definido, atualizando o status a cada cobrança.

### Fluxo técnico

```
Cliente confirma checkout
    ↓
Chargefy processa a primeira cobrança
    ↓
Chargefy cria plano de recorrência
    ↓
Cobranças automáticas no ciclo definido
    ↓
Chargefy atualiza status e dispara eventos
```

## Ciclo de vida da assinatura

```
Criada → Ativa → Suspensa → Cancelada
           ↑        ↓
           └── Reativada
```

### Status

| Status | Descrição |
| - | - |
| `active` | Assinatura ativa, cobranças em dia |
| `trialing` | Em período trial, sem cobrança |
| `suspended` | Temporariamente suspensa (ex: falha de pagamento) |
| `canceled` | Cancelada pelo cliente ou administrador |
| `revoked` | Revogada pelo administrador |

## Gerenciamento

### Suspender assinatura

Pausa temporariamente as cobranças sem cancelar a assinatura. O cliente perde acesso aos benefícios durante a suspensão.

```typescript theme={null}
await chargefy.subscriptions.update(subscriptionId, {
  status: "suspended",
});
```

### Reativar assinatura

Retoma as cobranças de uma assinatura suspensa. O cliente recupera acesso aos benefícios.

```typescript theme={null}
await chargefy.subscriptions.update(subscriptionId, {
  status: "active",
});
```

### Cancelar assinatura

Cancela permanentemente a assinatura. O cliente mantém acesso até o final do período já pago.

```typescript theme={null}
await chargefy.subscriptions.cancel(subscriptionId, {
  cancel_at_period_end: true, // Cancela no final do período atual
});
```

> [!NOTE]
>
> Com `cancel_at_period_end: true`, o cliente mantém acesso até a data de renovação. Com `false`, o cancelamento é imediato.

### Alterar plano (Upgrade/Downgrade)

Você pode trocar o preço de uma assinatura pra um upgrade ou downgrade. A Chargefy calcula o prorate automaticamente.

```typescript theme={null}
await chargefy.subscriptions.update(subscriptionId, {
  product_price_id: "price_new_plan",
});
```

Ou ajustar a `quantity` sem trocar de preço (mesmo plano, mais/menos assentos):

```typescript theme={null}
await chargefy.subscriptions.update(subscriptionId, {
  quantity: 8, // era 5
})
```

Saiba mais nos guias de [Upgrade](https://scaleup-c34c4386.mintlify.site/guides/subscription-upgrades.md) e [Downgrade](https://scaleup-c34c4386.mintlify.site/guides/subscription-downgrades.md).

## Período Trial

Assinaturas podem ter um período trial onde o cliente não é cobrado. Ao final do trial, a primeira cobrança é processada automaticamente.

* O trial é configurado no produto (ex: 7 dias, 14 dias, 1 mês)
* O cliente precisa fornecer dados do cartão no checkout
* Se o cliente cancelar durante o trial, não há cobrança

Saiba mais em [Trials](https://scaleup-c34c4386.mintlify.site/features/trials.md).

## Faturamento automático

A cada ciclo de cobrança, a Chargefy automaticamente:

1. Processa a cobrança no cartão
2. Cria um registro de transação (zoop\_transaction)
3. Dispara webhooks (`subscription.updated`, `checkout.updated`)
4. Atualiza o acesso do cliente aos benefícios

Em caso de falha na cobrança, a Chargefy tenta novamente automaticamente conforme configuração de retry.

## Webhook events

| Evento | Quando |
| - | - |
| `subscription.created` | Assinatura criada |
| `subscription.active` | Assinatura ativada (após primeiro pagamento ou trial) |
| `subscription.updated` | Qualquer atualização na assinatura |
| `subscription.canceled` | Assinatura cancelada |
| `subscription.uncanceled` | Cancelamento revertido |
| `subscription.revoked` | Assinatura revogada pelo administrador |

## Comparação com Stripe Subscriptions

Se você está migrando do Stripe, aqui estão as principais diferenças:

| Conceito | Stripe | Chargefy |
| - | - | - |
| Recorrência | Stripe Billing | Sistema de recorrência da Chargefy |
| Métodos de pagamento | Múltiplos | Apenas Cartão de Crédito |
| Moeda | Múltiplas | BRL (Real brasileiro) |
| Invoices | Stripe Invoices | Geração automática Chargefy |
| Proration | Automático | Automático |
| Trials | ✅ | ✅ |
| Parcelamento na recorrência | ❌ | ❌ (apenas pagamento único) |

Saiba mais sobre migração em [Migrar para Chargefy](https://scaleup-c34c4386.mintlify.site/migrate.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.