Rastrear a venda com client_ref

Quando a venda acontece pelo link de checkout (o caminho do cartão, e também de PIX, boleto e BDM), você pode mandar no próprio link um código do seu sistema — o id do pedido, da sessão ou do cliente — e recebê-lo de volta no webhook e na API. É assim que você liga a venda da Auryon ao registro do seu lado.

Como montar o link

Acrescente o parâmetro client_ref ao link de checkout da oferta:

https://checkout.auryon369.com.br/ABC12345?client_ref=pedido-8841

• Formato: letras, números, - e _, de 1 a 100 caracteres. Um valor fora disso é ignorado (a venda acontece normalmente, só sem o client_ref).
• Pode ir junto das UTMs: ?client_ref=pedido-8841&utm_source=instagram&utm_campaign=lancamento.
• Vale para todos os meios de pagamento: PIX, boleto, cartão nacional, cartão e meios locais internacionais, e BDM. O código é guardado antes de o comprador escolher como pagar.
• Se o comprador sair e voltar ao checkout pelo mesmo navegador sem o parâmetro, o código guardado continua valendo.

Não use ref

O parâmetro ref do link é a atribuição de afiliado e continua sendo. O seu código vai sempre em client_ref.

O que volta, e onde

Onde	Campo
Webhook V1 (eventos de venda e de pagamento)	data.object.tracking.client_ref
Webhook V1 checkout.session.abandoned	data.object.tracking.client_ref
Webhook legado TRANSACTION_*	trackProps.client_ref
Webhook legado SESSION_ABANDONED	data.order.trackProps.client_ref (onde o formato antigo guarda o trackProps desse evento)
API v1 GET /v1/transactions e /v1/transactions/{id}	tracking.client_ref
API v1 — buscar pelo código	GET /v1/transactions?client_ref=pedido-8841

O bloco tracking traz também as UTMs, o src e o sck do link, só os que existirem:

{
  "tracking": {
    "client_ref": "pedido-8841",
    "utm_source": "instagram",
    "utm_campaign": "lancamento"
  }
}

Numa venda sem nada disso, tracking vem vazio ({}) — o campo existe sempre.

Upsell, downsell, order bump e assinatura

• Order bump é a mesma venda: o mesmo tracking.
• Upsell e downsell nascem com o client_ref e as UTMs da venda principal.
• Renovações de assinatura nascem com o client_ref e as UTMs da primeira venda.
• O evento de carrinho abandonado leva o client_ref do link em que o comprador deixou o e-mail.

O client_ref segue mesmo quando o comprador desativa a medição de anúncios no aviso de cookies: ele é uma referência sua, não um dado de anúncio. As UTMs, nesse caso, não são guardadas.

⚠️ Confira o client_ref do seu lado

O client_ref viaja na URL, então o comprador pode editá-lo. Trate-o como uma referência para encontrar o registro no seu sistema, nunca como prova de nada:

• confira que o código existe e é seu antes de usá-lo;
• confira o valor e o produto da venda contra o que você esperava para aquele pedido;
• para liberar acesso, continue usando o evento transaction.paid com a assinatura verificada.

Não ponha dados pessoais no client_ref (e-mail, CPF, telefone): use um id opaco do seu sistema.