Upsell e Downsell

Cada produto pode ter um registro ProductUpsellDownsell apontando para outros produtos via paymentLinkIds[]. O fluxo de checkout consulta este registro após succeeded da transação principal.

Modelo

{
  product_id: 'prd_main',
  payment_link_ids: ['plk_upsell_premium', 'plk_downsell_basic'],
}

Ordem importa:

1. payment_link_ids[0] → upsell primário (ofertado primeiro, geralmente premium)
2. payment_link_ids[1] → downsell (ofertado se 1 for recusado)
3. Demais → sequência adicional (até 5 ofertas no funil)

Configurar

Endpoint: POST /v1/products/:productId/upsell_downsell

curl -X POST https://prometheus.zhex.io/v1/products/prd_xyz/upsell_downsell \
  -H "Authorization: Bearer $ZHEX_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "payment_link_ids": ["plk_upsell_premium", "plk_downsell_basic"] }'

Buscar configuração

Endpoint: GET /v1/products/:productId/upsell_downsell

const res = await fetch(
  `https://prometheus.zhex.io/v1/products/${productId}/upsell_downsell`,
  { headers: { Authorization: `Bearer ${process.env.ZHEX_SECRET_KEY}` } },
);
const upsell = await res.json();
// { payment_link_ids: [...], updated_at, ... }

Remover

Endpoint: DELETE /v1/products/:productId/upsell_downsell

await fetch(
  `https://prometheus.zhex.io/v1/products/${productId}/upsell_downsell`,
  {
    method: 'DELETE',
    headers: { Authorization: `Bearer ${process.env.ZHEX_SECRET_KEY}` },
  },
);

Apaga o registro inteiro — produto deixa de ter funil pós-compra.

Fluxo no hosted checkout

One-click: após o cartão tokenizado na primeira transação, upsells subsequentes não pedem CVV de novo (em adquirentes que suportam).

Boas práticas

• Upsell premium = +30 a 50% do ticket principal. Mais que isso reduz aceitação para < 5%.
• Downsell = -40 a 60%. Funcionado como "pelo menos algo a mais" — converte 8–15% dos que recusam o upsell.
• Nunca encadeie mais de 3 ofertas. Friction e abandono explodem após a 3ª.
• Use produtos DIGITAL em upsell. Sem complicação de logística e entrega imediata.
• Combine com cupom único (expiresAt: +15min) — gera urgência real, não fake.
• Não ofereça produto bloqueado como upsell. A Zhex pula automaticamente, mas o registro payment_link_ids[] aceita IDs inativos — limpe manualmente.

Métricas

Endpoint: GET /v1/products/:productId/upsell_downsell/stats?period=30d

Retorna:

{
  "main_succeeded": 1247,
  "upsell_offered": 1247,
  "upsell_accepted": 198,
  "upsell_rate": 0.158,
  "downsell_offered": 1049,
  "downsell_accepted": 87,
  "downsell_rate": 0.083,
  "incremental_revenue": 24830
}

incremental_revenue é o que você ganhou a mais do funil pós-compra (em centavos da baseCurrency).