Detalhe do produto com blocos independentes
Retorna tudo sobre um produto em blocos independentes: resumo de métricas com comparação ao período anterior, funil do GA4, coorte de entrada, produtos comprados juntos (pares em associations e conjuntos de 3 a 5 em boughtTogether), retenção mensal, frequência de compra, o que foi comprado depois, cupons e canais de aquisição.
- Cada bloco traz seu próprio
stateereason: se uma fonte falhar ou não tiver dados, só aquele bloco é afetado e a resposta continua200. 404significa que o produto não existe nessa loja;400, que algum parâmetro é inválido.- Nem todo bloco usa
dateFrom/dateTo:periodAppliedewindowde cada bloco dizem qual período foi medido.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
productId*stringID do produto pai, no formato publicado pela sua plataforma: um identificador VTEX (1234567) ou um GID da Shopify (gid://shopify/Product/10417518674198), que contém barras e deve ser codificado com percent-encoding no caminho. O valor é o mesmo productId retornado pela listagem, repassado sem alterações. Um produto ausente do catálogo, mas presente nas vendas ou na coorte de entrada, continua endereçável.
^[A-Za-z0-9._~+@:/-]{1,256}$length <= 256organizationId*stringuuidintegrationId*stringIdentificador da loja: o sourceIntegrationId retornado por GET /v1/products/integrations. Não use a App Key da VTEX.
uuiddateFrom?stringPeríodo do detalhe (AAAA-MM-DD; padrão: os últimos 30 dias até hoje). Seguido pelos blocos de resumo, funil, frequência de compra, cupons e canais. A retenção usa os meses que o período toca; coorte, comprados juntos e comprado depois usam janelas próprias, informadas em periodApplied e window.
datedateTo?stringPeríodo do detalhe (AAAA-MM-DD; padrão: os últimos 30 dias até hoje). Seguido pelos blocos de resumo, funil, frequência de compra, cupons e canais. A retenção usa os meses que o período toca; coorte, comprados juntos e comprado depois usam janelas próprias, informadas em periodApplied e window.
datecohortView?stringVisão de retenção do bloco de coorte: por clientes (logo) ou por receita líquida (revenue). As duas são sempre calculadas; o parâmetro apenas registra a visão escolhida.
"logo""logo""revenue"groupBy?stringAgrupa os meses de entrada da coorte por mês, trimestre ou semestre. O eixo de meses após a entrada continua mensal.
"month""month""quarter""semester"cohortWindowMonths?integerQuantos meses de entrada a grade de coorte mostra, contando para trás a partir do mês de entrada mais recente do produto. Não segue dateFrom/dateTo.
63612combinationSize?integerTamanho da combinação de produtos analisada. 2 (pares) é respondido pelo bloco associations, que traz confiança, lift, margem e clientes; nesse caso boughtTogether vem com state: not_applicable. De 3 a 5, quem responde é boughtTogether, e associations continua mostrando pares.
22345minOrders?integerMínimo de pedidos em comum para um par (associations) ou conjunto (boughtTogether) aparecer. Se existem combinações mas nenhuma atinge o mínimo, o bloco responde thresholded — diferente de no_base, quando não há combinação alguma. Para conjuntos de 3 a 5 a fonte também tem um mínimo próprio, que não pode ser reduzido: pedir menos retorna o motivo below_source_support_floor.
1 <= value <= 10005boughtAfterWindow?integer"Comprado em até N dias": prazo máximo entre o pedido com este produto e o pedido seguinte para entrar em boughtAfter. Não é um filtro de período.
30306090180boughtAfterMinCustomers?integerMínimo de clientes distintos para um próximo produto ser listado em boughtAfter.
1 <= value <= 10005Detalhe do produto. Sempre 200 quando o produto existe para a organização e a loja, qualquer que seja o estado de cada bloco: leia cada bloco pelo seu próprio state. Os dados de cada bloco podem levar até 5 minutos para refletir atualizações; um bloco com state: 'error' não é reaproveitado, então uma nova chamada tenta buscá-lo de novo. Se todas as fontes falharem, todos os blocos vêm com error e a resposta ainda é 200 — não monitore a disponibilidade só pelo status HTTP.
application/json- response
Detalhe composto por blocos independentes. Não há um indicador de sucesso geral: leia cada bloco pelo seu próprio state.
identity*Identificação do produto, obtida do catálogo — ou das vendas e da coorte, para um produto que saiu do catálogo mas foi vendido. Tem estado próprio: um produto desconhecido retorna 404, mas se o catálogo não puder ser lido, os outros blocos continuam respondendo e os campos de catálogo vêm null.
period*Período de relatório resolvido do bloco de resumo.
asOf*|Data de atualização mais antiga entre os blocos que retornaram dados (null se nenhum retornou): a página é tão atual quanto seu dado menos atual. Cada bloco tem o seu próprio asOf, que é o que deve aparecer ao lado de cada número.
date-timesummary*funnel*cohort*Grade de coortes de entrada do produto. Não segue dateFrom/dateTo: mostra os últimos cohortWindowMonths meses de entrada do produto, para que um período curto não esconda coortes maduras. window informa os meses de entrada realmente medidos.
associations*boughtTogether*Conjuntos de 3 a 5 produtos comprados junto com este. Pares (tamanho 2) são respondidos pelo bloco associations, que traz métricas específicas de pares; com combinationSize: 2, este bloco vem com state: not_applicable.
Este bloco não tem window: usa a mesma janela de 12 meses de associations, então associations.window vale também aqui.
retention*Retenção mensal do produto.
A fonte trabalha com meses completos, então o bloco responde pelos meses que o período pedido toca — periodApplied é {basis: "requested", granularity: "month"}. window informa os meses que realmente retornaram dados.
purchaseFrequency*Distribuição de quantas vezes cada cliente identificado comprou este produto nos dias solicitados — não uma média mensal e não a janela própria da fonte.
Lida na granularidade de pedido de propósito. A série mensal em retention não consegue responder isto: um cliente que comprou em julho e de novo em agosto pertence ao bucket 2 de um período que cobre ambos, e somar as linhas mensais o contaria duas vezes em 1.
Pedidos anônimos não carregam identidade para contar, então ficam fora de todo bucket e fora do denominador. São publicados ao lado dele em vez de descartados, e identityCoverage indica se uma distribuição vazia é um produto que ninguém comprou ou uma loja com checkout anônimo.
boughtAfter*O que os clientes compraram no pedido seguinte ao pedido com este produto.
Ignora dateFrom/dateTo: usa os pedidos dos clientes nos últimos 12 meses, a mesma janela dos blocos de cesta. periodApplied informa essa base. Como boughtTogether, não tem window.
coupons*Cupons do produto: pedidos pagos que usaram um cupom e continham o produto, no período pedido (periodApplied é requested/day).
O que o desconto não é. discountScope: order indica que os números de desconto são do PEDIDO inteiro: um pedido pode ter cupom, promoção e desconto de frete ao mesmo tempo, e a VTEX não separa o total entre eles. Por isso discountRate e averageDiscountPerOrder descrevem os pedidos que usaram cupom — nunca o desconto causado pelo cupom — e não devem ser apresentados como desconto do produto.
discountRate é ponderado por valor (soma dos descontos ÷ soma dos valores brutos dos pedidos), não uma média de percentuais.
Cobertura por item. itemLevelTagCoverage mostra a parcela dos pedidos com cupom que têm detalhamento de promoções por item. Ela é baixa em pedidos antigos, porque esse detalhamento só passou a ser coletado recentemente; por isso é informada como cobertura, nunca como desconto.
acquisitionChannels*Canais de aquisição do produto: quais canais trouxeram os pedidos que o continham, separando mídia paga de orgânica, no período pedido (periodApplied é requested/day).
O canal é o de último clique do pedido, pela mesma definição de atribuição usada no restante da V4MOS.AI. Um pedido pode não ter canal identificado: nesse caso ele não é contado como Orgânico, e sim informado em channelCoverage.
Nesta versão não há detalhamento por campanha nem investimento em mídia.
curl -X GET "https://example.com/v1/products/string?organizationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&integrationId=497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "identity": { "state": "ready", "reason": null, "integrationId": "3f8a5c62-1d47-4e6b-9a10-5b2c7d8e9f01", "productId": "12345", "productName": "Tênis Runner Pro", "categoryId": "12", "categoryName": "Tênis", "categoryPath": [ { "id": "1", "name": "Esportes" }, { "id": "12", "name": "Tênis" } ], "status": "active", "skuCount": 4, "inventoryState": "monitored", "inventoryFreshness": "fresh", "inventoryUpdatedAt": "2026-08-18T06:12:00.000Z", "firstSaleDate": "2025-11-03", "lastSaleDate": "2026-08-17", "asOf": "2026-08-18T06:12:00.000Z", "imageUrl": null, "sourceImageUrl": null, "imageStatus": "no_source" }, "period": { "from": "2026-07-01", "to": "2026-07-31" }, "asOf": "2026-08-18T05:40:00.000Z", "summary": { "state": "ready", "reason": null, "asOf": "2026-08-18T06:12:00.000Z", "periodApplied": { "basis": "requested", "granularity": "day" }, "data": { "grossSales": 184320.5, "netSales": 171004.2, "grossUnits": 612, "netUnits": 568, "averageTicket": 344.77, "marginAverage": 0.38, "marginTotal": 64981.6, "newCustomers": 402, "recurringCustomers": 94, "ltv180": 512.4, "repurchaseRate180": 0.21, "ltvToDate": 288.6, "repurchaseRateToDate": 0.14, "cohortElapsedDaysAverage": 96.4, "availableStock": 1240, "velocity30d": 18.9, "daysOfStock": 65.6, "returnRate": 0.072 }, "coverage": { "grossValue": 1, "cost": 1, "inventory": 1, "matureCohort": 1 }, "ndReasons": { "averageTicket": null, "margin": null, "averageMargin": null, "daysOfStock": null, "ltv180": null, "repurchaseRate180": null, "returnRate": null }, "previous": { "state": "ready", "reason": null, "window": { "from": "2026-05-31", "to": "2026-06-30" }, "availableWindow": { "from": "2025-11-03", "to": "2026-08-17" }, "data": { "grossSales": 147456.4, "netSales": 136803.36, "grossUnits": 490, "netUnits": 454, "averageTicket": 275.82, "marginAverage": 0.3, "marginTotal": 51985.28, "newCustomers": 322, "recurringCustomers": 75, "ltv180": 409.92, "repurchaseRate180": 0.17, "returnRate": 0.06 }, "coverage": { "grossValue": 1, "cost": 1, "inventory": null, "matureCohort": 1 }, "ndReasons": { "averageTicket": null, "margin": null, "averageMargin": null, "daysOfStock": null, "ltv180": null, "repurchaseRate180": null, "returnRate": null } }, "variation": { "grossSales": 25, "netSales": 25, "grossUnits": 24.9, "netUnits": 25.11, "averageTicket": 25, "marginAverage": 26.67, "marginTotal": 25, "newCustomers": 24.84, "recurringCustomers": 25.33, "ltv180": 25, "repurchaseRate180": 23.53, "returnRate": 20, "availableStock": null, "daysOfStock": null }, "returnMeasurement": { "basis": "floor", "reason": "late_returns_not_rescanned", "underestimated": [ "returnRate" ], "overestimated": [ "netSales", "netUnits", "averageTicket", "marginTotal", "marginAverage" ], "observedReturnRows": 341 } }, "funnel": { "state": "ready", "reason": null, "asOf": "2026-08-18T05:40:00.000Z", "periodApplied": { "basis": "requested", "granularity": "day" }, "window": { "from": "2026-07-01", "to": "2026-07-31" }, "steps": [ { "stageIndex": 1, "stageKey": "exposure", "stageSource": "MEDIA", "volume": null, "volumeUnit": null, "previousVolume": null, "stepRate": null, "abandonments": null, "sequenceClosed": null, "stageReason": "not_attributable_to_product" }, { "stageIndex": 2, "stageKey": "attention", "stageSource": "GA4", "volume": 18000, "volumeUnit": "items", "previousVolume": null, "stepRate": null, "abandonments": null, "sequenceClosed": false, "stageReason": "no_comparable_previous_stage" }, { "stageIndex": 3, "stageKey": "interest", "stageSource": "GA4", "volume": 2700, "volumeUnit": "items", "previousVolume": 18000, "stepRate": 0.15, "abandonments": 15300, "sequenceClosed": false, "stageReason": "aggregated_sequence_only" }, { "stageIndex": 4, "stageKey": "qualification", "stageSource": "GA4", "volume": 1080, "volumeUnit": "items", "previousVolume": 2700, "stepRate": 0.4, "abandonments": 1620, "sequenceClosed": false, "stageReason": "aggregated_sequence_only" }, { "stageIndex": 5, "stageKey": "commitment", "stageSource": "VTEX", "volume": 540, "volumeUnit": "orders", "previousVolume": 1080, "stepRate": null, "abandonments": null, "sequenceClosed": false, "stageReason": "cross_source" }, { "stageIndex": 6, "stageKey": "decision", "stageSource": "VTEX", "volume": 486, "volumeUnit": "orders", "previousVolume": 540, "stepRate": 0.9, "abandonments": 54, "sequenceClosed": true, "stageReason": null }, { "stageIndex": 7, "stageKey": "retention", "stageSource": "VTEX", "volume": 66, "volumeUnit": "customers", "previousVolume": 486, "stepRate": null, "abandonments": null, "sequenceClosed": true, "stageReason": null } ], "largestDrop": { "fromStep": "attention", "toStep": "interest", "lostUsers": 15300, "dropRate": 0.85 }, "mappingCoverage": { "ga4PropertyId": "properties/312445901", "propertyCount": 1, "coverageState": "production", "purchases": 0.973, "views": 0.951, "revenue": 0.968, "purchaseDenominator": 4821, "viewDenominator": 91240, "revenueDenominator": 1204551.3, "totalMappedItems": 812, "totalUnmappedItems": 22, "totalConflictingItems": 0, "totalProductMappedItems": 4, "resolutionRule": "SKU_ID" }, "categoryBenchmark": null }, "cohort": { "state": "ready", "reason": null, "asOf": "2026-08-18T06:12:00.000Z", "periodApplied": { "basis": "source_window", "granularity": "month" }, "view": "logo", "groupBy": "month", "overlappingRows": true, "window": { "from": "2026-03-01", "to": "2026-07-01" }, "activityThrough": "2026-08-01", "data": [ { "cohort": "2026-03-01", "cohortMonths": 1, "ageMonths": 6, "entryCustomers": 218, "netRevenue": 92911.9, "marginTotal": 35306.52, "marginAverage": 161.95651376146787, "marginNdReason": null, "cells": [ { "monthOffset": 0, "entryCustomers": 218, "activeCustomers": 218, "netRevenue": 68940.2, "retentionRate": 1, "revenueRetentionRate": 1, "marginTotal": 26197.28, "marginNdReason": null, "mature": true }, { "monthOffset": 1, "entryCustomers": 218, "activeCustomers": 34, "netRevenue": 10870.5, "retentionRate": 0.155963, "revenueRetentionRate": 0.157682, "marginTotal": 4130.79, "marginNdReason": null, "mature": true }, { "monthOffset": 2, "entryCustomers": 218, "activeCustomers": 19, "netRevenue": 6240.8, "retentionRate": 0.087156, "revenueRetentionRate": 0.090518, "marginTotal": 2371.5, "marginNdReason": null, "mature": true }, { "monthOffset": 4, "entryCustomers": 218, "activeCustomers": 11, "netRevenue": 3720.3, "retentionRate": 0.050459, "revenueRetentionRate": 0.053963, "marginTotal": 1413.71, "marginNdReason": null, "mature": true }, { "monthOffset": 5, "entryCustomers": 218, "activeCustomers": 9, "netRevenue": 3140.1, "retentionRate": 0.041284, "revenueRetentionRate": 0.045547, "marginTotal": 1193.24, "marginNdReason": null, "mature": true } ] }, { "cohort": "2026-05-01", "cohortMonths": 1, "ageMonths": 4, "entryCustomers": 310, "netRevenue": 111650.5, "marginTotal": 42427.19, "marginAverage": 136.86190322580646, "marginNdReason": null, "cells": [ { "monthOffset": 0, "entryCustomers": 310, "activeCustomers": 310, "netRevenue": 96420.1, "retentionRate": 1, "revenueRetentionRate": 1, "marginTotal": 36639.64, "marginNdReason": null, "mature": true }, { "monthOffset": 1, "entryCustomers": 310, "activeCustomers": 47, "netRevenue": 15230.4, "retentionRate": 0.151613, "revenueRetentionRate": 0.157959, "marginTotal": 5787.55, "marginNdReason": null, "mature": true } ] }, { "cohort": "2026-07-01", "cohortMonths": 1, "ageMonths": 2, "entryCustomers": 287, "netRevenue": 102701, "marginTotal": 39026.38, "marginAverage": 135.9804181184669, "marginNdReason": null, "cells": [ { "monthOffset": 0, "entryCustomers": 287, "activeCustomers": 287, "netRevenue": 89120.7, "retentionRate": 1, "revenueRetentionRate": 1, "marginTotal": 33865.87, "marginNdReason": null, "mature": true }, { "monthOffset": 1, "entryCustomers": 287, "activeCustomers": 41, "netRevenue": 13580.3, "retentionRate": null, "revenueRetentionRate": null, "marginTotal": 5160.51, "marginNdReason": null, "mature": false } ] } ] }, "associations": { "state": "ready", "reason": null, "asOf": "2026-08-18T06:12:00.000Z", "periodApplied": { "basis": "source_window", "granularity": "month" }, "combinationSize": 2, "minOrders": 5, "limit": 50, "window": { "from": "2025-09-01", "to": "2026-08-01" }, "pairsTotal": 37, "data": [ { "productId": "20918", "productName": "Meia Esportiva Cano Alto", "ordersTogether": 88, "ordersWithProduct": 496, "ordersWithAssociated": 741, "ordersTotal": 41230, "confidence": 0.177419, "lift": 9.871, "associatedNetRevenue": 5210.9, "basketNetRevenue": 10420.8, "averageTicket": 118.42, "marginTotal": 3910.35, "marginNdReason": null, "newCustomers": 31, "recurringCustomers": 46, "months": 11, "imageUrl": null, "sourceImageUrl": null, "imageStatus": "no_source" } ] }, "boughtTogether": { "state": "not_applicable", "reason": "size_served_by_associations", "asOf": null, "periodApplied": { "basis": "source_window", "granularity": "month" }, "combinationSize": 2, "minOrders": 5, "limit": 50, "supportFloor": null, "maxBasketSize": null, "ordersExcluded": null, "combinationsTotal": 0, "data": [] }, "retention": { "state": "ready", "reason": null, "asOf": "2026-08-18T06:12:00.000Z", "periodApplied": { "basis": "requested", "granularity": "month" }, "window": { "from": "2026-07-01", "to": "2026-07-01" }, "data": [ { "month": "2026-07-01", "buyers": 496, "repeatBuyers": 94, "newBuyers": 402, "repeatBuyerRate": 0.189516, "orders": 610, "identifiedOrders": 588, "anonymousOrders": 22, "purchaseFrequency": 1.185484, "avgDaysBetweenPurchases": 23.4, "repeatIntervals": 78, "netRevenue": 171004.2, "grossUnits": 612, "matureMonth": true } ] }, "purchaseFrequency": { "state": "ready", "reason": null, "asOf": "2026-08-18T06:12:00.000Z", "periodApplied": { "basis": "requested", "granularity": "day" }, "identifiedCustomers": 496, "identifiedOrders": 588, "anonymousOrders": 22, "identityCoverage": 0.963934, "repurchaseRate": 0.133065, "averagePurchaseFrequency": 1.185484, "previous": { "state": "ready", "reason": null, "window": { "from": "2026-05-31", "to": "2026-06-30" }, "identifiedCustomers": 452, "repurchaseRate": 0.111111, "averagePurchaseFrequency": 1.132743 }, "variation": { "repurchaseRate": 19.76, "averagePurchaseFrequency": 4.66 }, "data": [ { "bucket": "1", "customers": 430, "orders": 430, "share": 0.866935 }, { "bucket": "2", "customers": 48, "orders": 96, "share": 0.096774 }, { "bucket": "3", "customers": 12, "orders": 36, "share": 0.024194 }, { "bucket": "4+", "customers": 6, "orders": 26, "share": 0.012097 } ] }, "boughtAfter": { "state": "ready", "reason": null, "asOf": "2026-08-18T06:12:00.000Z", "periodApplied": { "basis": "source_window", "granularity": "month" }, "limit": 50, "data": [ { "productId": "20918", "productName": "Meia Esportiva Cano Alto", "isSameProduct": false, "customers": 128, "transitions": 141, "customersWithNextOrder": 310, "ordersWithNextOrder": 402, "customerShare": 0.412903, "avgDaysToNext": 34.2, "minDaysToNext": 2, "maxDaysToNext": 209, "nextBasketNetRevenue": 54531.75, "averageTicket": 386.75, "marginTotal": 16359.53, "marginNdReason": null, "newCustomers": 31, "recurringCustomers": 97, "imageUrl": null, "sourceImageUrl": null, "imageStatus": "no_source" }, { "productId": "12345", "productName": "Tênis Runner Pro", "isSameProduct": true, "customers": 46, "transitions": 51, "customersWithNextOrder": 310, "ordersWithNextOrder": 402, "customerShare": 0.148387, "avgDaysToNext": 96.8, "minDaysToNext": 21, "maxDaysToNext": 288, "nextBasketNetRevenue": 26132.4, "averageTicket": 512.4, "marginTotal": null, "marginNdReason": "incomplete_cost", "newCustomers": 8, "recurringCustomers": 38, "imageUrl": null, "sourceImageUrl": null, "imageStatus": "no_source" } ] }, "coupons": { "state": "ready", "reason": null, "asOf": "2026-08-18T06:12:00.000Z", "discountScope": "order", "periodApplied": { "basis": "requested", "granularity": "day" }, "ordersWithProduct": 400, "ordersWithCoupon": 120, "couponOrderShare": 0.3, "couponDiscountValue": 5820, "couponGrossValue": 194000, "discountRate": 0.03, "averageDiscountPerOrder": 48.5, "previous": { "state": "ready", "reason": null, "window": { "from": "2026-05-31", "to": "2026-06-30" }, "ordersWithProduct": 360, "ordersWithCoupon": 96, "couponOrderShare": 0.266667, "averageDiscountPerOrder": 42, "discountRate": 0.025 }, "variation": { "couponOrderShare": 12.5, "averageDiscountPerOrder": 15.48, "discountRate": 20 }, "itemLevelTagCoverage": 0.25, "itemLevelTagCoverageStatus": "measured", "limit": 50, "data": [ { "couponCode": "PROMO-INVERNO-15", "orders": 120, "netRevenue": 41000, "averageTicket": 341.67, "marginTotal": 12000, "marginNdReason": null, "newCustomers": 30, "recurringCustomers": 85, "orderDiscountValue": 4616 }, { "couponCode": "FRETEGRATIS", "orders": 44, "netRevenue": 15900, "averageTicket": 361.36, "marginTotal": null, "marginNdReason": "incomplete_cost", "newCustomers": 9, "recurringCustomers": 34, "orderDiscountValue": 1204 } ] }, "acquisitionChannels": { "state": "ready", "reason": null, "asOf": "2026-08-18T06:12:00.000Z", "cacState": "no_source", "ltvScope": "organization_lifetime", "periodApplied": { "basis": "requested", "granularity": "day" }, "ordersWithProduct": 400, "ordersWithChannel": 400, "channelCoverage": 1, "ordersMissingChannelFact": 0, "paidOrderShare": 0.625, "organicOrderShare": 0.375, "customers": 380, "newCustomers": 120, "recurringCustomers": 270, "data": [ { "channel": "Meta Ads", "mediaType": "paid", "orders": 250, "netRevenue": 82000, "customers": 240, "newCustomers": 90, "recurringCustomers": 160, "averageLtv": 512.5, "ltvCoverage": 0.75, "marginTotal": 24000, "marginNdReason": null, "spend": null, "cac": null, "ltvCac": null }, { "channel": "Orgânico", "mediaType": "organic", "orders": 150, "netRevenue": 48000, "customers": 145, "newCustomers": 30, "recurringCustomers": 118, "averageLtv": 702.4, "ltvCoverage": 0.965517, "marginTotal": null, "marginNdReason": "incomplete_cost", "spend": null, "cac": null, "ltvCac": null } ] }}