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 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 (1365). 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: <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