Produtos e Variantes - Visão Geral

#Introdução

O recurso de Produtos (Products) representa seu catálogo. Cada produto agrupa uma ou mais Variantes (Variants) — e é a variante que carrega a precificação. Um produto "Plano Premium" pode ter as variantes "Mensal", "Anual" e "Vitalício", cada uma com seu preço e regras de cobrança.

As variantes são o que você referencia em Transações (variantes oneTime) e em Assinaturas (variantes recurring).

#Estrutura do Produto

{
  "id": "prd_01hqzvabc",
  "name": "Plano Premium",
  "slug": "plano-premium",
  "salesPage": "https://example.com/sales",
  "description": "Full access plan",
  "language": "pt-BR",
  "enabled": true,
  "salesQty": 42,
  "type": "digital",
  "category": "saas",
  "externalReference": "SKU-EXT-1",
  "warrantyDays": 7,
  "images": ["https://example.com/img1.png"],
  "imageAssetIds": null,
  "createdAt": "2026-04-12T17:56:33.000Z",
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "variants": [
    {
      "id": "var_01hqzvabc",
      "productId": "prd_01hqzvabc",
      "name": "Mensal",
      "slug": "mensal",
      "description": "Monthly billing",
      "sku": "SKU-M",
      "primary": true,
      "enabled": true,
      "pricing": {
        "unitPrice": 9900,
        "oldPrice": null,
        "costPerItem": null,
        "currency": "BRL",
        "schema": "unit",
        "type": "recurring",
        "billingType": "prepaid",
        "billingFrequency": "monthly",
        "billingFrequencyCount": 1
      },
      "images": null,
      "metadata": null,
      "attributes": null,
      "externalReference": null,
      "checkoutUrl": null,
      "createdAt": "2026-04-12T17:56:33.000Z",
      "updatedAt": "2026-04-12T17:56:33.000Z"
    }
  ]
}

#Campos do produto

#Modelo de Precificação (dual-axis)

A precificação vive na variante, em pricing, organizada em dois eixos independentes:

#Eixo 1 — type (natureza da cobrança) · imutável

• Uma variante oneTime não pode ser usada em assinatura (a assinatura exige variante recorrente) → variantNotRecurring (422).
• O type é imutável após a criação → pricingTypeImmutable (422).

#Eixo 2 — schema (como o preço é calculado) · imutável

#Campos de pricing

Na resposta, pricing traz todos os campos acima (os não aplicáveis vêm null); unitPrice, oldPrice e costPerItem sempre presentes (centavos ou null). renewalShipping e renewalMethodDiscount vêm sempre como booleano: a regra que vale para o plano (a sua escolha, ou o default).

#Regras da renovação

Num plano recorrente vendido pelo checkout hospedado, a 1ª cobrança é o total do pedido: itens + frete − cupons − desconto do método de pagamento (Pix, boleto ou cartão, conforme o template do checkout). As cobranças seguintes (as renovações) levam os itens − os cupons recorrentes e mais o que estas duas regras do plano dizem:

• Por plano. Cada variante recorrente tem as suas regras: um plano físico e um digital da mesma loja podem ter regras diferentes. Num plano digital, sem frete, renewalShipping não muda nada.
• A assinatura congela as regras. No momento da compra, a assinatura guarda as duas regras, o frete cotado e o percentual do desconto (o renewalTerms dela). Mudar o plano depois vale só para quem assinar depois.
• O checkout mostra o valor de cada renovação já com essas regras, antes do comprador pagar.
• Assinaturas criadas antes de 15/10/2026, pela API de assinaturas ou por um upsell não congelam regras: as renovações delas levam os itens − os cupons recorrentes.

#Recursos Disponíveis

#Integração com Outros Recursos

• Transactions — variantes oneTime são cobradas em transações avulsas.
• Subscriptions — variantes recurring compõem os itens da assinatura.
• Coupons — descontos podem ser limitados a produtos/variantes específicos.
• Checkouts — links de pagamento referenciam variantes por id.

#Exportar produtos

Use POST /v1/exports — job assíncrono com dedup, TTL e download assinado.

O antigo POST /v1/products/export foi APOSENTADO e responde 410 apontando para o substituto. Ele nunca gerou arquivo nenhum: devolvia { succeeded: true } a partir de uma função sem argumentos e sem saída — um controle que dizia existir. A rota continua registrada de propósito, para o 410 nomear o substituto em vez de o gateway devolver um 404 mudo.