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.
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

O SDK Node anexa o header X-Idempotency-Key: <uuid> automaticamente em toda chamada. A mesma chave devolve a série originalmente criada por 24h, em vez de agendar uma cobrança duplicada — seguro para retry após timeout de rede.

Resposta