Skip to main content
Use este caminho quando seu backend cria a Checkout Session diretamente pela API, sem enviar o comprador para um Payment Link. No momento da criação, envie o objeto marketing_attribution para registrar a origem da campanha desde o início e recebê-la no primeiro webhook.
Você não envia model, capture_point, captured_at, IP, país ou user agent. Esses campos pertencem à Chargefy e são preenchidos conforme a origem da captura.

​
Quando usar este caminho

Use marketing_attribution quando:
  • seu sistema já recebeu as UTMs antes de criar o pedido;
  • a Checkout Session é criada antes do redirect do comprador;
  • você quer que checkout.session.created já carregue a atribuição;
  • o checkout começa dentro de um app, SaaS, carrinho ou fluxo autenticado;
  • a campanha foi resolvida server-side e não depende da URL hospedada.

​
O que acontece se você não enviar

A sessão nasce com marketing_attribution: null. Na primeira abertura da URL hospedada, a Chargefy ainda pode registrar os parâmetros presentes na URL. Isso cria uma diferença importante nos webhooks: Se outro sistema precisa tomar decisão de campanha já no evento de criação, envie o objeto no backend.

​
Validação

O body da API é estrito. Campo desconhecido, tipo incorreto, URL inválida ou valor acima do limite retorna 400 e aponta o parâmetro com problema. Na captura pela URL, valores inválidos são ignorados para não impedir o checkout. Na API, o erro é explícito porque seu backend pode corrigi-lo antes de enviar o comprador.

​
Atribuição não é metadata

marketing_attribution alimenta relatórios e integrações de marketing. metadata guarda pares livres controlados pelo seu sistema e é apenas ecoado nos objetos e webhooks. Não coloque utm_source, utm_campaign ou fbclid dentro de metadata se espera vê-los no relatório de aquisição.

​
Referência completa

Veja todos os campos, variantes de line_items, respostas e erros em Criar uma Checkout Session.