> ## 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.

# Períodos Trial

> Ofereça períodos de teste gratuitos para seus clientes experimentarem antes de pagar

> [!NOTE]
>
> **Aumente suas conversões com trials**
>
> Períodos trial permitem que potenciais clientes experimentem seu produto antes de se comprometerem com uma assinatura paga. Estudos mostram que oferecer trials pode aumentar a taxa de conversão em até 60%.

## Visão Geral

Um período trial é um intervalo de tempo no início de uma assinatura onde o cliente tem acesso ao produto sem ser cobrado. Ao final do trial, a assinatura é automaticamente convertida para uma assinatura paga.

A Chargefy suporta dois modelos de trial:

| Modelo | Cartão obrigatório | Conversão | Melhor para |
| - | - | - | - |
| Trial com cartão | Sim | Automática | Maior taxa de conversão |
| Trial sem cartão | Não | Manual (cliente informa pagamento) | Menor fricção de entrada |

## Configuração de Trial no Produto

### Via API

```typescript theme={null}
import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
  server: "https://api.chargefy.io",
});

// Criar produto com trial de 14 dias
const product = await chargefy.products.create({
  name: "Plano Profissional",
  prices: [
    {
      type: "recurring",
      currency: "brl",
      unit_amount: 9990, // R$ 99,90
      interval: "month",
      interval_count: 1,
      trial_period_days: 14,
    },
  ],
});
```

### Via Dashboard

**1. Acesse Produtos**

No painel da Chargefy, vá em **Produtos** e clique em **Criar Produto**.

**2. Configure o preço recorrente**

Defina o valor (ex: R\$ 99,90/mês) e selecione o ciclo de cobrança.

**3. Ative o período trial**

Em **Período Trial**, ative a opção e defina a quantidade de dias (ex: 7, 14 ou 30 dias).

**4. Escolha o modelo**

Selecione se deseja exigir cartão de crédito durante o checkout do trial.

## Trial com Cartão

No modelo de trial com cartão, o cliente informa os dados do cartão de crédito no checkout, mas **não é cobrado** durante o período trial. Ao final do trial, a cobrança é processada automaticamente.

### Fluxo

```
Cliente acessa checkout
    ↓
Informa dados do cartão de crédito
    ↓
Assinatura criada com status "trialing"
    ↓
Cliente usa o produto durante o trial
    ↓
Trial expira → Primeira cobrança automática
    ↓
Assinatura muda para status "active"
```

### Configuração via API

```typescript theme={null}
const product = await chargefy.products.create({
  name: "Plano Enterprise",
  prices: [
    {
      type: "recurring",
      currency: "brl",
      unit_amount: 29990, // R$ 299,90
      interval: "month",
      interval_count: 1,
      trial_period_days: 7,
      trial_requires_payment_method: true, // Exige cartão
    },
  ],
});
```

> [!TIP]
>
> **Recomendado para maior conversão.** Como o cartão já está cadastrado, a transição de trial para assinatura paga é automática e sem fricção. A taxa de conversão costuma ser significativamente maior que o modelo sem cartão.

## Trial sem Cartão

No modelo de trial sem cartão, o cliente se cadastra e começa a usar o produto imediatamente, sem informar dados de pagamento. Ao final do trial, o cliente precisa informar um método de pagamento para continuar.

### Fluxo

```
Cliente acessa checkout
    ↓
Cadastro sem dados de pagamento
    ↓
Assinatura criada com status "trialing"
    ↓
Cliente usa o produto durante o trial
    ↓
Trial expira → Notificação para informar pagamento
    ↓
Cliente informa cartão → Primeira cobrança processada
    ↓
Assinatura muda para status "active"
```

### Configuração via API

```typescript theme={null}
const product = await chargefy.products.create({
  name: "Plano Starter",
  prices: [
    {
      type: "recurring",
      currency: "brl",
      unit_amount: 4990, // R$ 49,90
      interval: "month",
      interval_count: 1,
      trial_period_days: 30,
      trial_requires_payment_method: false, // Não exige cartão
    },
  ],
});
```

> [!WARNING]
>
> **Atenção:** Se o cliente não informar um método de pagamento ao final do trial, a assinatura será automaticamente suspensa após o período de carência configurado.

## Duração do Trial

A duração do trial é configurada em dias no campo `trial_period_days`. Você pode definir qualquer valor inteiro positivo.

### Durações comuns

| Duração | Caso de uso |
| - | - |
| 3 dias | Produtos simples, teste rápido |
| 7 dias | Padrão para SaaS com onboarding curto |
| 14 dias | Produtos que exigem mais exploração |
| 30 dias | Ferramentas complexas, B2B enterprise |

### Consultar dias restantes do trial

```typescript theme={null}
const subscription = await chargefy.subscriptions.get(subscriptionId);

if (subscription.status === "trialing") {
  const trialEnd = new Date(subscription.trial_end_at);
  const now = new Date();
  const daysRemaining = Math.ceil(
    (trialEnd.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
  );

  console.log(`Trial expira em ${daysRemaining} dias`);
  console.log(`Data de expiração: ${trialEnd.toLocaleDateString("pt-BR")}`);
}
```

## Conversão Automática

Quando o trial expira em uma assinatura com cartão cadastrado, a Chargefy automaticamente:

**1. Processa a primeira cobrança**

A Chargefy processa a cobrança no cartão cadastrado.

**2. Cria o plano de recorrência**

Se a cobrança for aprovada, um plano de recorrência é criado para cobranças futuras.

**3. Atualiza o status**

A assinatura muda de `trialing` para `active`.

**4. Dispara webhooks**

Eventos `subscription.updated` e `subscription.active` são disparados.

### Tratando falha na conversão

Se a cobrança falhar ao final do trial (cartão expirado, saldo insuficiente, etc.), a Chargefy tenta novamente conforme a política de retry configurada.

```typescript theme={null}
// Verificar assinaturas com trial expirado e falha na conversão
const subscriptions = await chargefy.subscriptions.list({
  status: "suspended",
  trial_expired: true,
});

for (const sub of subscriptions.items) {
  console.log(`Assinatura ${sub.id} - Trial expirou, cobrança falhou`);
  console.log(`Cliente: ${sub.customer.email}`);

  // Notificar cliente para atualizar método de pagamento
  await notifyCustomerPaymentFailed(sub.customer.email, sub.id);
}
```

## Cancelamento Durante o Trial

O cliente pode cancelar a assinatura a qualquer momento durante o trial sem ser cobrado.

### Cancelamento imediato

```typescript theme={null}
// Cancelar assinatura durante o trial (sem cobrança)
await chargefy.subscriptions.cancel(subscriptionId, {
  cancel_at_period_end: false, // Cancelamento imediato
});
```

### Cancelamento pelo cliente (portal)

O cliente também pode cancelar diretamente pelo portal do cliente, acessando a área de assinaturas e clicando em "Cancelar assinatura".

> [!NOTE]
>
> Quando uma assinatura em trial é cancelada, o cliente **nunca é cobrado**. O acesso é revogado imediatamente (ou ao final do trial, conforme sua configuração).

## Webhook Events

A Chargefy dispara webhooks específicos durante o ciclo de vida do trial:

| Evento | Quando | Payload relevante |
| - | - | - |
| `subscription.created` | Assinatura criada com trial | `status: "trialing"`, `trial_end_at` |
| `subscription.updated` | Trial convertido para ativo | `status: "active"` |
| `subscription.canceled` | Cancelamento durante trial | `status: "canceled"` |
| `subscription.suspended` | Trial expirou sem pagamento | `status: "suspended"` |
| `subscription.active` | Primeira cobrança pós-trial ativada | `status: "active"` |

### Exemplo de webhook handler

```typescript theme={null}
import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/chargefy", async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case "subscription.created":
      if (event.data.status === "trialing") {
        const trialEnd = event.data.trial_end_at;
        console.log(`Novo trial iniciado. Expira em: ${trialEnd}`);

        // Iniciar sequência de onboarding
        await startOnboardingSequence(event.data.customer.email);

        // Agendar lembrete antes do trial expirar
        await scheduleTrialReminder(
          event.data.customer.email,
          trialEnd
        );
      }
      break;

    case "subscription.updated":
      if (event.data.status === "active" && event.data.previous_status === "trialing") {
        console.log("Trial convertido com sucesso!");

        // Liberar acesso completo
        await grantFullAccess(event.data.customer.id);

        // Enviar email de boas-vindas como cliente pagante
        await sendConversionEmail(event.data.customer.email);
      }
      break;

    case "subscription.suspended":
      if (event.data.trial_expired) {
        console.log("Trial expirou sem pagamento");

        // Revogar acesso
        await revokeAccess(event.data.customer.id);

        // Enviar email pedindo atualização de pagamento
        await sendPaymentRequestEmail(event.data.customer.email);
      }
      break;
  }

  res.status(200).json({ received: true });
});
```

## Exemplo Completo

### Criando um produto SaaS com trial

```typescript theme={null}
import { Chargefy } from "@chargefy/sdk";

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
  server: "https://api.chargefy.io",
});

// 1. Criar produto com trial de 14 dias (com cartão)
const product = await chargefy.products.create({
  name: "CRM Avançado",
  description: "Gerencie seus clientes com inteligência artificial",
  prices: [
    {
      type: "recurring",
      currency: "brl",
      unit_amount: 14990, // R$ 149,90/mês
      interval: "month",
      interval_count: 1,
      trial_period_days: 14,
      trial_requires_payment_method: true,
    },
    {
      type: "recurring",
      currency: "brl",
      unit_amount: 149900, // R$ 1.499,00/ano (2 meses grátis)
      interval: "year",
      interval_count: 1,
      trial_period_days: 14,
      trial_requires_payment_method: true,
    },
  ],
});

// 2. Gerar link de checkout
const checkout = await chargefy.checkouts.create({
  product_price_id: product.prices[0].id,
  success_url: "https://app.meucrm.com.br/welcome",
});

console.log(`Link de checkout: ${checkout.url}`);

// 3. Verificar status do trial de um cliente
const subscription = await chargefy.subscriptions.get("sub_abc123");

if (subscription.status === "trialing") {
  const trialEnd = new Date(subscription.trial_end_at);
  const now = new Date();
  const daysLeft = Math.ceil(
    (trialEnd.getTime() - now.getTime()) / (1000 * 60 * 60 * 24)
  );

  if (daysLeft <= 3) {
    // Enviar lembrete de que o trial está acabando
    await sendTrialEndingReminder(
      subscription.customer.email,
      daysLeft
    );
  }
}
```

## Boas Práticas

> [accordion] Defina a duração ideal para o seu produto
>
> O trial deve ser longo o suficiente para o cliente perceber valor, mas curto o suficiente para criar urgência. Para SaaS simples, 7 dias costuma ser ideal. Para produtos complexos, considere 14 ou 30 dias.

> [accordion] Prefira trial com cartão para maior conversão
>
> Embora trials sem cartão tenham menor fricção de entrada, trials com cartão têm taxas de conversão significativamente maiores. O cartão cadastrado elimina a barreira de pagamento na conversão.

> [accordion] Envie lembretes antes do trial expirar
>
> Configure emails automáticos para lembrar o cliente 3 dias e 1 dia antes do trial expirar. Use os webhooks para disparar essas notificações automaticamente.

> [accordion] Ofereça onboarding durante o trial
>
> Use o período trial para guiar o cliente pelas funcionalidades mais importantes do produto. Quanto mais valor o cliente perceber durante o trial, maior a chance de conversão.

> [accordion] Monitore métricas de trial
>
> Acompanhe a taxa de conversão trial-para-pago, o tempo médio de cancelamento durante trial e os motivos de não-conversão. Esses dados são essenciais para otimizar sua estratégia.

> [accordion] Não cobre na falha do trial
>
> Se a cobrança falhar ao final do trial, suspenda o acesso e notifique o cliente. Nunca tente cobrar em métodos de pagamento alternativos sem consentimento explícito.


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