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