Skip to main content
POST
/
api
/
scheduled-charges
Criar Cobrança Agendada
curl --request POST \
  --url https://garu.com.br/api/scheduled-charges \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerId": 123,
  "amount": 123,
  "type": "<string>",
  "dueDate": "<string>",
  "methods": [
    {}
  ],
  "productId": 123,
  "recurrence": {
    "interval": "<string>",
    "intervalCount": 123,
    "endsAfter": 123,
    "endsOn": "<string>"
  },
  "trialDays": 123,
  "description": "<string>",
  "maxRecoveryDays": 123,
  "externalReference": "<string>",
  "metadata": {}
}
'

​
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).
Cadastre o cliente primeiro via dashboard ou API — veja Cadastro de clientes. O customerId é o ID numérico retornado pelo POST /api/customers.

​
Exemplo de Requisição

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"
  }'

​
Recorrente com Pix Automático

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

​
customerId
number
required
ID do cliente no Garu (já cadastrado neste seller).
​
amount
number
required
Valor em BRL decimal (ex: 297.50). Não use centavos.
​
type
string
required
Tipo da cobrança: one_time (avulsa) ou recurring (recorrente). pix_automatic exige recurring.
​
dueDate
string
required
Data de vencimento em YYYY-MM-DD, fuso de São Paulo. Deve ser hoje ou futura.
​
methods
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.
​
productId
number
ID de um produto opcional. Quando informado, aparece vinculado à cobrança no dashboard. Obrigatório quando methods inclui pix_automatic.
​
recurrence
object
Configuração da recorrência (use com type: "recurring").
​
trialDays
number
Dias de teste gratuito antes do primeiro ciclo (1–365). Apenas para type: "recurring".
​
description
string
Texto livre exibido no e-mail do cliente e na página de pagamento. Até 500 caracteres.
​
maxRecoveryDays
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.
​
externalReference
string
Identificador interno seu (até 255 caracteres). Útil para reconciliação.
​
metadata
object
JSON livre. Persistido como JSONB; não interpretado pela Garu.

​
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

{
  "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"
}