Carrinho

Visão Geral

O carrinho de compras é um dos principais componentes de um e-commerce.

Ele permite que o cliente adicione e gerencie múltiplos produtos em um único pedido, armazenando temporariamente os itens selecionados.

Além disso, o carrinho pode oferecer recursos como aplicação de cupons de desconto, promoções, cálculo de frete, atualização de quantidades e visualização do valor total da compra.

Autenticação

Os endpoints de carrinho não exigem autenticação na maioria dos casos.

A exceção ocorre em funcionalidades promocionais relacionadas ao sistema de pontos e à carteira do cliente, que exigem vínculo com o usuário para validação.

Token

O carrinho pode ser criado a partir de quase todos os endpoints, retornando um token no header da resposta, que deve ser armazenado e reutilizado nas requisições seguintes.

Esse token representa o carrinho atual e permite a utilização sem autenticação.

Caso ele seja perdido, ao realizar qualquer nova solicitação, um novo carrinho e token serão gerados automaticamente.

Embora o token seja retornado inicialmente via header, nas requisições subsequentes ele será enviado por meio de cookie.

Entidades relacionadas

Promocional Cupom

No contexto do carrinho, o cupom permite a aplicação de descontos por meio de um hash que representa um cupom específico.

Essa aplicação envolve regras e período de validade, sendo uma forma simples para o lojista oferecer descontos à loja ou a clientes específicos.

Em geral, apenas quem gera o cupom conhece seu hash e define para quem ele será distribuído.

Promocional Carteira

A carteira do cliente é uma entidade que armazena valores disponíveis, provenientes de cartões-presente, vouchers ou outras ações promocionais.

Em alguns casos, pode conter valores de estornos de compras que não foram concluídas corretamente.

Esse saldo pode ser utilizado no carrinho como forma de pagamento ou desconto.

Promocional Sistema de Pontos

O sistema de pontos premia o cliente após cada compra, permitindo o acúmulo de pontos que podem ser convertidos em descontos para compras futuras.

No carrinho, esses pontos podem ser aplicados para redução do valor total ou, caso o saldo seja suficiente, para pagamento integral de um produto ou serviço.

Produtos de Upsell

Os produtos de upsell são sugestões exibidas, geralmente, no checkout, oferecendo algum desconto adicional com base nos itens presentes no carrinho.

Cada item pode atender a regras específicas de segmentação, fazendo com que determinados produtos sejam exibidos como oferta.

Compre Junto

Produtos de compre junto são sugestões complementares ao produto principal.

Quando o item sugerido é adicionado ao carrinho, pode ser aplicado um desconto, conforme a configuração definida pelo lojista.

Notas e Considerações

O carrinho é recalculado constantemente e passa repetidamente pelos mesmos processos a cada endpoint acionado.

Por esse motivo, alguns erros podem se repetir em diferentes operações.

Nesta documentação, foram priorizados os erros mais relevantes dentro do contexto específico de cada endpoint.

Upsells do Carrinho

GET /cart/upsell/{locationId}

Retorna produtos de upsell sugeridos com base no carrinho atual

Descrição

Este endpoint é responsável por executar a segmentação dos produtos presentes no carrinho, identificando e retornando os itens de upsell compatíveis com esses produtos.

Além disso, a rota depende de uma localização, que deve ser especificada pelo frontend diretamente na URL da requisição.

Parâmetros de Query

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
locationId	string	Sim	ID da localização do upsell (ex: cart-page, checkout-page)

Campos Disponíveis (fields)

Especifique apenas os campos necessários para otimizar a performance:

Campo	Descrição
brand	Informações completas da marca do produto
flags	Flags do produto (showInSite, saleWithoutStock, minimumStock)
mainUrl	URL principal do produto
secondaryUrls	URLs secundárias do produto
description	Descrições (short, full, searchDescription)
parentProduct	Produto pai
indicatedProducts	Produtos indicados relacionados
relatedProducts	Produtos relacionados
tax	Informações de impostos e taxas
filters	Filtros e atributos aplicáveis
stockByStorage	Estoque por armazém
stock	Informações consolidadas de estoque
seals	Selos e certificações do produto
mainCategory	Categoria principal
categories	Todas as categorias do produto
categoryBreadcrumb	Breadcrumb de navegação de categorias
dimension	Dimensões físicas (peso, altura, largura, comprimento)
variation	Variações do produto (cores, tamanhos, etc)
media	Mídias (imagens, vídeos, arquivos)
price	Preço, promoções e parcelamento
priceRules	Regras de preço aplicadas
bannerGroups	Grupos de banners associados
review	Avaliações e reviews
status	Status do produto
haveChildren	Produtos filhos
restriction	Restrição de compra do produto (tradePolicyId, requiredAge)
availableCoupons	Retorna até 10 cupons aplicáveis ao produto

Estrutura do field `availableCoupons`

Cada item do array representa um cupom aplicável ao produto. O nó discounts detalha as faixas de desconto:

1{
2  "id": 15,
3  "hash": "PROMO10",
4  "discounts": [
5    {
6      "entityId": 15,
7      "entity": "coupon",
8      "itemAmount": 3,
9      "value": 10
10    }
11  ],
12  "createdAt": "2026-01-01 00:00:00",
13  "updatedAt": "2026-01-01 00:00:00"
14}
{
  "id": 15,
  "hash": "PROMO10",
  "discounts": [
    {
      "entityId": 15,
      "entity": "coupon",
      "itemAmount": 3,
      "value": 10
    }
  ],
  "createdAt": "2026-01-01 00:00:00",
  "updatedAt": "2026-01-01 00:00:00"
}

Campo	Tipo	Descrição
`id`	integer	ID do cupom
`hash`	string	Código do cupom (inserido pelo cliente no checkout)
`discounts[].entityId`	integer	ID da entidade referenciada em `entity`
`discounts[].entity`	string	Entidade que recebe o desconto
`discounts[].itemAmount`	number	Quantidade mínima de itens para que o desconto em `value` seja aplicado
`discounts[].value`	number	Valor do desconto aplicado quando `itemAmount` é atingido

Parâmetros do Corpo

Parâmetro	Tipo	Obrigatório	Descrição
`skipUsedUpsell`	boolean	❌	Determina se deve ser listados novamente itens de upsells que já estejam presentes no carrinho
`variationMap`	array	❌	Um mapa de variação onde caso seja retornado um produto pai o mesmo seja substituído por sua variação (chave: productId, valor: variationId)

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/cart/upsell/{locationId} \
3  --data '{
4    "fields": [
5      "brand",
6      "flags",
7      "mainUrl"
8    ],
9    "skipUsedUpsell": true,
10    "variationMap": {
11      "1":"13",
12      "2":"14",
13      "3":"15"
14    },
15  }'
curl --request GET \
  --url {{MAIN_URL}}/cart/upsell/{locationId} \
  --data '{
    "fields": [
      "brand",
      "flags",
      "mainUrl"
    ],
    "skipUsedUpsell": true,
    "variationMap": {
      "1":"13",
      "2":"14",
      "3":"15"
    },
  }'

✅ Resposta de Sucesso

1{
2  "id": 1234,
3  "displayTitle": "Compre agora!",
4  "displayDescription": "Garanta agora seu produto com desconto!",
5  "displayButtonText": "Adicionar ao meu carrinho",
6  "quantity": 3,
7  "upsellProduct": {
8    "id": 1234,
9    "type": "product",
10    "sku": "PGP-MU-001",
11    "name": "Produto Genérico Padrão - Modelo Único",
12    "priority": 1,
13    "basePrice": 0,
14    "active": true,
15    "review": null,
16    "isGiftCard": false,
17    "stock": {
18      "productId": 1234,
19      "productStorageId": 0,
20      "availableStock": 20,
21      "reservedStock": 0,
22      "updatedAt": "2024-08-15 20:44:10"
23    },
24    "stocks": [
25      {
26        "productId": 1234,
27        "productStorageId": 1,
28        "availableStock": 20,
29        "reservedStock": 0,
30        "updatedAt": "2025-08-15 20:44:10"
31      }
32    ],
33    "originalPrice": {
34      "comparisonPrice": 0,
35      "salePrice": 0,
36      "markup": 0,
37      "ruleId": 0,
38      "ruleTrigger": "original",
39      "ruleName": "Original",
40      "availableForSale": true,
41      "basePrice": false,
42      "priceWithDiscount": 0,
43      "installments": [],
44      "scheduling": null
45    },
46    "price": {
47      "comparisonPrice": 0,
48      "salePrice": 3259,
49      "markup": 0,
50      "ruleId": 1,
51      "ruleTrigger": "automatic",
52      "ruleName": "A product price-rule",
53      "availableForSale": true,
54      "basePrice": false,
55      "priceWithDiscount": 3239,
56      "installments": [],
57      "scheduling": {
58        "id": 46,
59        "startDate": "2026-02-07 09:00:00",
60        "endDate": "2026-10-30 23:59:59"
61      }
62    },
63    "priceRules": null,
64    "brand": null,
65    "flags": {
66      "subscription": false,
67      "service": false,
68      "showInSite": true,
69      "saleWithoutStock": false,
70      "minimumStock": 1
71    },
72    "tax": {
73      "mpn": "",
74      "ean": "",
75      "ncm": "",
76      "exclusive": false
77    },
78    "indicatedProducts": [],
79    "relatedProducts": [],
80    "filters": [],
81    "seals": [],
82    "mainCategory": {
83      "id": 1,
84      "name": "Utilidades Diversas",
85      "url": "utilidades-diversas"
86    },
87    "categories": [
88      {
89        "id": 1,
90        "name": "Utilidades Diversas",
91        "url": "utilidades-diversas"
92      }
93    ],
94    "categoryBreadcrumb": [
95      {
96        "id": 1,
97        "name": "Utilidades Diversas",
98        "url": "utilidades-diversas"
99      }
100    ],
101    "dimensions": {
102      "shippingCargoTypeId": null,
103      "additionalTime": 0,
104      "width": 34.5,
105      "height": 16.5,
106      "length": 34.5,
107      "weight": 3.52
108    },
109    "parentProductId": null,
110    "combination": [],
111    "currentAttributes": [],
112    "variations": {
113      "valueList": [],
114      "combinations": [],
115      "attributes": []
116    },
117    "medias": [
118      {
119        "id": 123,
120        "type": "image",
121        "title": "",
122        "alternativeText": null,
123        "file": "\/upload\/media\/produto-media.webp",
124        "originalFile": "\/upload\/media\/produto-media.png",
125        "size": null,
126        "originalSize": null,
127        "width": null,
128        "height": null,
129        "url": null
130      }
131    ],
132    "bannerGroups": [],
133    "status": null,
134    "createdAt": "2022-10-03 17:32:28",
135    "updatedAt": "2025-09-17 14:11:42",
136    "url": "produto-generico-padrao-12345.html",
137    "urls": [],
138    "linkedTradePolicies": null,
139    "description": {
140      "id": 1234,
141      "tradePolicyId": 1,
142      "name": "Produto Genérico Padrão",
143      "shortDescription": "Um produto versátil e confiável, ideal para diferentes tipos de uso no dia a dia.",
144      "videoUrl": null,
145      "searchDescription": "Produto multifuncional, feito com materiais de qualidade e design pensado para atender diversas necessidades. Perfeito para quem busca praticidade e bom custo-benefício.",
146      "description": null,
147      "customDescription1": null,
148      "customDescription2": null,
149      "customDescription3": null,
150      "measureTable": null,
151      "seoTitle": null,
152      "seoDescription": null,
153      "seoKeywords": null,
154      "seoCanonical": null,
155      "seoSocialTitle": null,
156      "seoSocialDescription": null,
157      "seoTwitterImageUrl": null,
158      "seoGraphImageUrl": null,
159      "seoGoogleCategoryId": 1,
160      "seoIndexOnGoogle": null,
161      "seoGoogleCondition": "new",
162      "seoGoogleAgeGroup": null,
163      "seoGoogleGender": "unisex",
164      "seoStructuredData": null
165      "productId": 1234,
166      "productCategoryId": null,
167      "productBrandId": null,
168      "productPageId": null
169    }
170  },
171  "priceRule": {
172    "id": 1234,
173    "name": "Product price-rule",
174    "trigger": "automatic",
175    "ruleTarget": "product",
176    "origin": "pair-offer",
177    "applyInGroup": false,
178    "updateComparisonPrice": "not-update",
179    "basePriceField": "sale-price",
180    "code": null,
181    "beginQuantity": 0,
182    "endQuantity": 0,
183    "value": 20,
184    "valueType": "value",
185    "priority": 0,
186    "active": true,
187    "scheduling": null,
188    "tradePolicies": [],
189    "productIds": [],
190    "productCategoryIds": [],
191    "productBrandIds": [],
192    "lastUpdateUserName": null,
193    "createdAt": "2024-03-28 14:16:55",
194    "updatedAt": "2024-08-20 12:42:10"
195  }
196}
{
  "id": 1234,
  "displayTitle": "Compre agora!",
  "displayDescription": "Garanta agora seu produto com desconto!",
  "displayButtonText": "Adicionar ao meu carrinho",
  "quantity": 3,
  "upsellProduct": {
    "id": 1234,
    "type": "product",
    "sku": "PGP-MU-001",
    "name": "Produto Genérico Padrão - Modelo Único",
    "priority": 1,
    "basePrice": 0,
    "active": true,
    "review": null,
    "isGiftCard": false,
    "stock": {
      "productId": 1234,
      "productStorageId": 0,
      "availableStock": 20,
      "reservedStock": 0,
      "updatedAt": "2024-08-15 20:44:10"
    },
    "stocks": [
      {
        "productId": 1234,
        "productStorageId": 1,
        "availableStock": 20,
        "reservedStock": 0,
        "updatedAt": "2025-08-15 20:44:10"
      }
    ],
    "originalPrice": {
      "comparisonPrice": 0,
      "salePrice": 0,
      "markup": 0,
      "ruleId": 0,
      "ruleTrigger": "original",
      "ruleName": "Original",
      "availableForSale": true,
      "basePrice": false,
      "priceWithDiscount": 0,
      "installments": [],
      "scheduling": null
    },
    "price": {
      "comparisonPrice": 0,
      "salePrice": 3259,
      "markup": 0,
      "ruleId": 1,
      "ruleTrigger": "automatic",
      "ruleName": "A product price-rule",
      "availableForSale": true,
      "basePrice": false,
      "priceWithDiscount": 3239,
      "installments": [],
      "scheduling": {
        "id": 46,
        "startDate": "2026-02-07 09:00:00",
        "endDate": "2026-10-30 23:59:59"
      }
    },
    "priceRules": null,
    "brand": null,
    "flags": {
      "subscription": false,
      "service": false,
      "showInSite": true,
      "saleWithoutStock": false,
      "minimumStock": 1
    },
    "tax": {
      "mpn": "",
      "ean": "",
      "ncm": "",
      "exclusive": false
    },
    "indicatedProducts": [],
    "relatedProducts": [],
    "filters": [],
    "seals": [],
    "mainCategory": {
      "id": 1,
      "name": "Utilidades Diversas",
      "url": "utilidades-diversas"
    },
    "categories": [
      {
        "id": 1,
        "name": "Utilidades Diversas",
        "url": "utilidades-diversas"
      }
    ],
    "categoryBreadcrumb": [
      {
        "id": 1,
        "name": "Utilidades Diversas",
        "url": "utilidades-diversas"
      }
    ],
    "dimensions": {
      "shippingCargoTypeId": null,
      "additionalTime": 0,
      "width": 34.5,
      "height": 16.5,
      "length": 34.5,
      "weight": 3.52
    },
    "parentProductId": null,
    "combination": [],
    "currentAttributes": [],
    "variations": {
      "valueList": [],
      "combinations": [],
      "attributes": []
    },
    "medias": [
      {
        "id": 123,
        "type": "image",
        "title": "",
        "alternativeText": null,
        "file": "\/upload\/media\/produto-media.webp",
        "originalFile": "\/upload\/media\/produto-media.png",
        "size": null,
        "originalSize": null,
        "width": null,
        "height": null,
        "url": null
      }
    ],
    "bannerGroups": [],
    "status": null,
    "createdAt": "2022-10-03 17:32:28",
    "updatedAt": "2025-09-17 14:11:42",
    "url": "produto-generico-padrao-12345.html",
    "urls": [],
    "linkedTradePolicies": null,
    "description": {
      "id": 1234,
      "tradePolicyId": 1,
      "name": "Produto Genérico Padrão",
      "shortDescription": "Um produto versátil e confiável, ideal para diferentes tipos de uso no dia a dia.",
      "videoUrl": null,
      "searchDescription": "Produto multifuncional, feito com materiais de qualidade e design pensado para atender diversas necessidades. Perfeito para quem busca praticidade e bom custo-benefício.",
      "description": null,
      "customDescription1": null,
      "customDescription2": null,
      "customDescription3": null,
      "measureTable": null,
      "seoTitle": null,
      "seoDescription": null,
      "seoKeywords": null,
      "seoCanonical": null,
      "seoSocialTitle": null,
      "seoSocialDescription": null,
      "seoTwitterImageUrl": null,
      "seoGraphImageUrl": null,
      "seoGoogleCategoryId": 1,
      "seoIndexOnGoogle": null,
      "seoGoogleCondition": "new",
      "seoGoogleAgeGroup": null,
      "seoGoogleGender": "unisex",
      "seoStructuredData": null
      "productId": 1234,
      "productCategoryId": null,
      "productBrandId": null,
      "productPageId": null
    }
  },
  "priceRule": {
    "id": 1234,
    "name": "Product price-rule",
    "trigger": "automatic",
    "ruleTarget": "product",
    "origin": "pair-offer",
    "applyInGroup": false,
    "updateComparisonPrice": "not-update",
    "basePriceField": "sale-price",
    "code": null,
    "beginQuantity": 0,
    "endQuantity": 0,
    "value": 20,
    "valueType": "value",
    "priority": 0,
    "active": true,
    "scheduling": null,
    "tradePolicies": [],
    "productIds": [],
    "productCategoryIds": [],
    "productBrandIds": [],
    "lastUpdateUserName": null,
    "createdAt": "2024-03-28 14:16:55",
    "updatedAt": "2024-08-20 12:42:10"
  }
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_STOCK_INSUFFICIENT_AVAILABLE_STOCK	400	Quantidade disponível em estoque insuficiente.
UAPPI_STORE_PRODUCT_NOT_FOUND	404	O produto solicitado não foi encontrado.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Carrinho

Visão Geral

Autenticação

Token

Entidades relacionadas

Promocional Cupom

Promocional Carteira

Promocional Sistema de Pontos

Produtos de Upsell

Compre Junto

Notas e Considerações

Upsells do Carrinho

Descrição

Parâmetros de Query

Headers Obrigatórios

Parâmetros da URL

Campos Disponíveis (fields)

Estrutura do field availableCoupons

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Nesta página

Institucional

Estrutura do field `availableCoupons`