O Cashback na Tray passou por uma atualização em sua estrutura de pedidos: o saldo resgatado pelo cliente na compra passou a ser tratado como desconto no pedido, e não mais como uma forma de pagamento.

Com essa alteração no endpoint orders/complete, o total da compra já é processado e enviado de forma líquida para o seu sistema de gestão (ERP). Na prática, o valor final pago pelo cliente é exatamente o montante que deve ser faturado na nota fiscal.

A estrutura existente da API foi preservada, recebendo o campo exclusivo cashback_discount e a inclusão automática desse abatimento no campo discount. Continue a leitura para entender como funciona a nova lógica de valores, quais os benefícios para o seu fluxo financeiro e como orientar sua equipe técnica na integração.

Para quem serve e qual o objetivo desta atualização?

Este recurso é voltado para todos os lojistas que utilizam o programa de Cashback da Tray como ferramenta de fidelização e que gerenciam seus pedidos por meio de integrações via API com sistemas de ERP próprios ou de terceiros.

O objetivo principal é eliminar inconsistências contábeis e simplificar o faturamento. Ao tratar o cashback como um desconto comercial (e não como uma forma de pagamento fracionada), o lojista evita duplicidade de lançamentos e garante que o faturamento reflita com precisão o dinheiro que efetivamente transitou no meio de pagamento.

O enquadramento fiscal do cashback (como desconto incondicional ou bonificação) está em definição. Este artigo detalha a estrutura de dados do pedido; confirme com a sua contabilidade como declará-lo na emissão da nota fiscal.

Benefícios do novo formato para a sua loja virtual

A transição do cashback de meio de pagamento para desconto traz ganhos expressivos para a operação contábil e a gestão de dados da loja:

• Faturamento líquido direto: o campo total reflete exatamente o valor a faturar, sem necessidade de subtrair pagamentos internos manualmente;
• Rastreabilidade total: o novo campo cashback_discount permite auditar com precisão quanto do desconto geral veio de cashback;
• Conciliação simplificada: a matriz de pagamentos (Payment) exibe unicamente as formas financeiras reais pagas pelo consumidor (como Pix, Cartão ou Boleto), sem linhas extras de cashback;
• Segurança operacional: em casos onde a cobrança externa falha, o cashback é estornado automaticamente para a carteira do cliente e a nova tentativa é recalculada pelo valor integral, impedindo a aplicação duplicada de abatimentos.

Como conciliar os valores do pedido

A fórmula de conciliação matemática dos pedidos no formato atualizado opera da seguinte maneira:

total = partial_total + shipment_value + taxes - discount

Todos os valores numéricos são devolvidos em formato texto (string) com duas casas decimais e ponto, devendo ser convertidos para formato decimal antes de qualquer cálculo no sistema.

Atenção: Nunca some os itens de additional_values ao campo discount[cite: 2]. O cashback já está embutido no montante de discount; somar ambos causará o desconto do valor em dobro no seu ERP!

Configuração técnica e integração via API (orders/complete)

A atualização é disponibilizada via requisição padrão da API de pedidos:

GET https://{dominio-da-loja}/web_api/orders/{id}/complete?access_token={token}

Como diferenciar pedidos novos dos antigos?

A implantação do recurso ocorre de forma gradual nas lojas[cite: 1]. Por isso, é importante que o sistema saiba diferenciar pedidos nos dois formatos:

• Formato Novo: O campo cashback_discount é maior que zero, o total já vem líquido e a linha de cashback consta em additional_values.
• Formato Anterior: O cashback consta como pagamento parcial no array Payment e o campo total inclui o montante pago via cashback.

Pedidos legados anteriores à atualização não são convertidos automaticamente.

Exportações manuais em planilhas Excel e o webservice SOAP legado não contemplam valores adicionais no formato novo e continuam apresentando o total cheio. Para obter os valores líquidos atualizados, utilize sempre o endpoint orders/complete.

Próximos passos e conteúdos relacionados

Agora que você conhece a estrutura do cashback como desconto, revise suas regras de integração no ERP para assegurar a sincronização financeira correta.

Caso tenha qualquer dúvida técnica ou precise de apoio na validação da integração, entre em contato com a equipe de suporte ao desenvolvedor.

Boas vendas!

Equipe Tray