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

# Criar Cobrança Agendada

> Agende uma cobrança PIX ou Boleto para um cliente cadastrado

## Visão Geral

Cria uma cobrança agendada — avulsa (`one_time`) ou recorrente (`recurring`) — para uma data futura. A Garu envia o e-mail ao cliente no dia do vencimento e dispara webhooks no ciclo de vida. Para recorrência debitada automaticamente, combine `type: "recurring"` com `methods: ["pix_automatic"]` (veja [Pix Automático](/guias/pix-automatico)).

<Note>
  Cadastre o cliente primeiro via dashboard ou API — veja
  [Cadastro de clientes](/guias/clientes). O `customerId` é o ID numérico
  retornado pelo `POST /api/customers`.
</Note>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://garu.com.br/api/scheduled-charges \
    -H "Authorization: Bearer sk_test_sua_chave" \
    -H "Content-Type: application/json" \
    -H "X-Idempotency-Key: 6c4c2a1e-4c2b-4f1c-9a8d-1b2e3f4a5b6c" \
    -d '{
      "customerId": 42,
      "amount": 297.50,
      "type": "one_time",
      "dueDate": "2026-06-15",
      "methods": ["pix", "boleto"],
      "description": "Mensalidade Junho"
    }'
  ```

  ```javascript JavaScript theme={null}
  import { Garu } from '@garuhq/node';

  const garu = new Garu({ apiKey: process.env.GARU_API_KEY });

  const charge = await garu.scheduledCharges.create({
    customerId: 42,
    amount: 297.5,
    type: 'one_time',
    dueDate: '2026-06-15',
    methods: ['pix', 'boleto'],
    description: 'Mensalidade Junho'
  });

  console.log(charge.id); // sch_abc123
  ```

  ```python Python theme={null}
  import requests
  import os
  import uuid

  response = requests.post(
      "https://garu.com.br/api/scheduled-charges",
      headers={
          "Authorization": f"Bearer {os.environ['GARU_API_KEY']}",
          "X-Idempotency-Key": str(uuid.uuid4())
      },
      json={
          "customerId": 42,
          "amount": 297.50,
          "type": "one_time",
          "dueDate": "2026-06-15",
          "methods": ["pix", "boleto"],
          "description": "Mensalidade Junho"
      }
  )

  print(response.json()["id"])  # sch_abc123
  ```
</CodeGroup>

### Recorrente com Pix Automático

```bash theme={null}
curl -X POST https://garu.com.br/api/scheduled-charges \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": 42,
    "productId": 456,
    "amount": 297.50,
    "type": "recurring",
    "dueDate": "2026-06-15",
    "methods": ["pix_automatic"],
    "recurrence": { "interval": "monthly", "intervalCount": 1, "endsAfter": 12 },
    "description": "Plano Premium - mensal"
  }'
```

## Parâmetros

<ParamField body="customerId" type="number" required>
  ID do cliente no Garu (já cadastrado neste seller).
</ParamField>

<ParamField body="amount" type="number" required>
  Valor em BRL decimal (ex: `297.50`). **Não use centavos.**
</ParamField>

<ParamField body="type" type="string" required>
  Tipo da cobrança: `one_time` (avulsa) ou `recurring` (recorrente). `pix_automatic` exige `recurring`.
</ParamField>

<ParamField body="dueDate" type="string" required>
  Data de vencimento em `YYYY-MM-DD`, fuso de São Paulo. Deve ser hoje ou futura.
</ParamField>

<ParamField body="methods" type="array" required>
  Métodos oferecidos ao cliente. Aceita `["pix"]`, `["boleto"]`, `["pix", "boleto"]` ou `["pix_automatic"]`. Usar `pix_automatic` exige `type: "recurring"` **e** um `productId` cujo produto tenha `pixAutomatic: true`.
</ParamField>

<ParamField body="productId" type="number">
  ID de um produto opcional. Quando informado, aparece vinculado à cobrança no dashboard. **Obrigatório** quando `methods` inclui `pix_automatic`.
</ParamField>

<ParamField body="recurrence" type="object">
  Configuração da recorrência (use com `type: "recurring"`).

  <Expandable title="campos de recurrence">
    <ParamField body="interval" type="string" required>
      Frequência: `weekly`, `biweekly`, `monthly`, `bimonthly`, `quarterly`, `biannual` ou `yearly`.
    </ParamField>

    <ParamField body="intervalCount" type="number">
      Multiplicador do intervalo (ex: `interval: "monthly"` + `intervalCount: 2` = a cada 2 meses).
    </ParamField>

    <ParamField body="endsAfter" type="number">
      Encerra após este número de ciclos. Opcional.
    </ParamField>

    <ParamField body="endsOn" type="string">
      Data final da recorrência em `YYYY-MM-DD`. Opcional.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="trialDays" type="number">
  Dias de teste gratuito antes do primeiro ciclo (`1`–`365`). Apenas para `type: "recurring"`.
</ParamField>

<ParamField body="description" type="string">
  Texto livre exibido no e-mail do cliente e na página de pagamento. Até 500 caracteres.
</ParamField>

<ParamField body="maxRecoveryDays" type="number" default="14">
  Janela, em dias (inteiro de `1` a `365`), para a recuperação automática de uma
  cobrança que o cron diário tenha perdido — se o disparo do `dueDate` falhar, a
  Garu segue tentando dentro dessa janela. Omitir usa o padrão do sistema (`14`).
  Também aparece no objeto retornado.
</ParamField>

<ParamField body="externalReference" type="string">
  Identificador interno seu (até 255 caracteres). Útil para reconciliação.
</ParamField>

<ParamField body="metadata" type="object">
  JSON livre. Persistido como JSONB; não interpretado pela Garu.
</ParamField>

## Idempotência

Envie o header `X-Idempotency-Key: <uuid>` para tornar a criação segura contra retries de rede. Em uma versão futura, repetir a mesma chave dentro de 24h retornará o registro original em vez de criar um duplicado. O SDK Node anexa o header automaticamente.

## Resposta

```json theme={null}
{
  "id": "sch_abc123",
  "sellerId": 10,
  "customerId": 42,
  "productId": null,
  "amount": 297.5,
  "description": "Mensalidade Junho",
  "type": "one_time",
  "dueDate": "2026-06-15",
  "methods": ["pix", "boleto"],
  "status": "scheduled",
  "maxRecoveryDays": 14,
  "externalReference": null,
  "metadata": null,
  "createdAt": "2026-05-01T12:00:00Z",
  "updatedAt": "2026-05-01T12:00:00Z"
}
```