Skip to main content
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 interno do cliente (não o uuid público de /api/v1/customers) — as duas APIs ainda não compartilham um identificador cruzado.

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. Mínimo de R$ 5,00 (5.00), o valor mínimo da plataforma por cobrança, na cobrança avulsa e na recorrente. Abaixo disso a API responde 400. Veja Erros Comuns.
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 header X-Idempotency-Key. A mesma chave devolve a série originalmente criada por 24h, em vez de agendar uma cobrança duplicada, então um retry após timeout de rede fica seguro. Derive a chave de algo estável no seu sistema, como o id da assinatura e o mês. Uma chave nova a cada tentativa não protege nada. O SDK Node só envia o header quando você passa idempotencyKey: desde a versão 5.0.0 ele não gera uma chave sozinho.

Resposta

Erros Comuns

Solução: Envie um amount de pelo menos 5.00. A regra vale para a cobrança avulsa e para a recorrente. As cobranças agendadas criadas antes dessa regra mantêm o valor e continuam sendo cobradas normalmente.