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

# Trial

> Entenda como funciona o período gratuito nas assinaturas

O motor de recorrência da Malga oferece suporte completo a períodos de trial (teste gratuito), permitindo que você ofereça aos seus clientes um período experimental antes da primeira cobrança.

## Como funciona o Trial

### Configuração do Trial

O trial é configurado na criação da assinatura através do objeto `trial`:

```json theme={null}
{
  "name": "Assinatura Premium",
  "trial": {
    "endDate": "2025-02-15"
  },
  "recurrence": {
    "interval": "monthly"
  },
  // ... outros campos
}
```

### Características do Sistema de Trial

* **Opcional**: O trial pode ou não ser configurado na criação da assinatura
* **Flexível**: Pode ter qualquer duração (dias, semanas, meses)
* **Imutável**: Uma vez criado, o trial não pode ser editado
* **Automático**: A transição para cobrança acontece automaticamente

### Comportamento do Trial

#### Durante o Período de Trial

* Status da assinatura: `trialing`
* **Nenhuma cobrança é realizada**
* A assinatura permanece ativa para o cliente
* Webhooks específicos são enviados

#### Transição Automática

Quando o trial expira:

1. Status muda de `trialing` para `created`
2. Sistema agenda a primeira cobrança
3. Webhook `subscription.created` é enviado
4. Próxima fatura é gerada automaticamente

## Fluxo de Trial

```mermaid theme={null}
flowchart TD
    A[Criar Assinatura com Trial] --> B{Trial definido?}
    B -->|SIM| C[Status: trialing]
    B -->|NÃO| D[Status: created]
    C --> E[Trial ativo - sem cobrança]
    E --> F{Trial expirou?}
    F -->|NÃO| E
    F -->|SIM| G[Status: created]
    G --> H[Gerar primeira fatura]
    H --> I[Processar primeira cobrança]
    I --> J{Cobrança aprovada?}
    J -->|SIM| K[Status: active]
    J -->|NÃO| L[Iniciar retentativas]
```

## Exemplos de Uso

### Criando uma assinatura com trial de 7 dias

<CodeGroup>
  ```bash Request theme={null}
  curl --location 'https://api.malga.io/v1/subscriptions' \
  --header 'Content-Type: application/json' \
  --header 'X-Client-Id: YOUR_CLIENT_ID' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --data '{
    "name": "Plano Premium - Trial 7 dias",
    "merchantId": "YOUR_MERCHANT_ID",
    "customerId": "YOUR_CUSTOMER_ID",
    "trial": {
      "endDate": "2025-02-07"
    },
    "recurrence": {
      "interval": "monthly"
    },
    "paymentMethod": {
      "type": "credit",
      "card": {
        "cardId": "YOUR_CARD_ID"
      }
    },
    "items": [
      {
        "name": "Plano Premium",
        "amount": 2990,
        "quantity": 1
      }
    ]
  }'
  ```
</CodeGroup>

## Webhooks do Sistema de Trial

### Eventos específicos do trial

| Evento                       | Descrição                                                              |
| ---------------------------- | ---------------------------------------------------------------------- |
| `subscription.trial_started` | Enviado quando uma assinatura é criada com trial ativo                 |
| `subscription.created`       | Enviado quando o trial expira e a assinatura fica pronta para cobrança |

## Regras Importantes

### Validações do Trial

* **Data futura obrigatória**: `trial.endDate` deve ser no futuro (mínimo de 1 dia)
* **Alinhamento com startAt**: Se `startAt` não for especificado, usa automaticamente `trial.endDate`
* **Formato UTC**: O campo `startAt` deve ser informado em formato UTC (YYYY-MM-DD)
* **Imutabilidade**: Trial não pode ser editado após a criação da assinatura

### Comportamento Especial

* **Prioridade de eventos**: Se trial definido, emite apenas `trial_started`, nunca `created` na criação

### Limitações

* **Apenas na criação**: Trial só pode ser configurado durante a criação da assinatura
* **Não editável**: Impossível modificar ou estender o período de trial
* **Sem cobrança parcial**: Durante o trial, nenhuma cobrança é realizada

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Gerenciar assinaturas" icon="gear" href="/documentations/more/recurrence/engine/managing">
    Aprenda como gerenciar assinaturas durante e após o período de trial
  </Card>

  <Card title="Configurar webhooks" icon="webhook" href="/documentations/more/recurrence/engine/webhooks">
    Configure notificações para eventos de trial
  </Card>
</CardGroup>