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,
  "description": "<string>",
  "externalReference": "<string>",
  "metadata": {}
}
'

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.

​
Visão Geral

Cria uma cobrança avulsa (one_time) para uma data futura. A Garu envia o e-mail ao cliente no dia do vencimento e dispara webhooks no ciclo de vida.
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"
  }'

​
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. Apenas one_time é aceito nesta versão.
​
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"] ou ["pix", "boleto"].
​
productId
number
ID de um produto opcional. Quando informado, aparece vinculado à cobrança no dashboard.
​
description
string
Texto livre exibido no e-mail do cliente e na página de pagamento. Até 500 caracteres.
​
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",
  "externalReference": null,
  "metadata": null,
  "createdAt": "2026-05-01T12:00:00Z",
  "updatedAt": "2026-05-01T12:00:00Z"
}