VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Variações e opções

Preço por quantidade

Lê, cria e substitui as escalas de preço por quantidade e por grupo de clientes de um produto do seller.

Use escalas para preço de atacado ("a partir de 10 unidades, R$ 44,90") ou preço especial para um grupo de clientes. No carrinho, por padrão o preço cobrado é o menor entre as escalas que se aplicam e nunca passa do preço base do produto. A loja pode trocar a regra para usar a escala de maior quantidade atingida; o limite do preço base continua valendo.

Ler

GET/api/v1/vendor/products/{id}/price-tiersSeller

Ler as escalas de preço

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.

Exemplo de requisição (ler)

bash
curl "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/price-tiers" \
  -H "Authorization: Bearer $TOKEN"

Resposta (ler)

200Escalas
json
{
  "tiers": [
    {
      "id": "7a6b5c4d-0001-4e2f-9a3b-1c2d3e4f5a6b",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "lower_limit": 10,
      "price": 4490,
      "percentage_discount": 0,
      "usergroup_id": null,
      "created_at": "2026-10-11T21:30:00Z"
    }
  ],
  "base_price": 4990,
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d"
}

Campos da resposta

tiersarray

Escalas, ordenadas por grupo e quantidade.

idstring (uuid)
Id da escala.
product_idstring (uuid)
Produto.
lower_limitinteger
Quantidade mínima para a escala valer.
priceinteger
Preço unitário em centavos.
percentage_discountnumber
Percentual de 0 a 100 sobre o preço base. Se maior que zero, vale no lugar de price.
usergroup_idstring | null
null = todos; guest = visitantes; registered = logados; ou o UUID de um grupo de clientes.
value_per_kginteger
Preço de referência por kg, só exibição (centavos).
value_per_unitinteger
Preço de referência por unidade, só exibição (centavos).
created_atstring
Criação (RFC 3339).
base_priceinteger
Preço base do produto em centavos.
product_idstring (uuid)
Produto.

Erros (ler)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}

Criar uma escala

Cria a escala, ou atualiza a existente quando já há uma para o mesmo lower_limit e grupo.

POST/api/v1/vendor/products/{id}/price-tiersSeller

Criar ou atualizar uma escala

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.

Corpo da requisição

lower_limitintegerobrigatório
Quantidade mínima. Mínimo 1.
priceintegerobrigatório
Preço unitário em centavos.
percentage_discountnumber
Percentual de desconto (0 a 100; fora disso é ajustado).
usergroup_idstring
Grupo: omitido ou vazio = todos; guest, registered ou UUID de grupo.
value_per_kginteger
Preço de referência por kg (só exibição).
value_per_unitinteger
Preço de referência por unidade (só exibição).

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/price-tiers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "lower_limit": 10,
  "price": 4490
}'

Resposta (criar)

201Escala gravada
json
{
  "id": "7a6b5c4d-0001-4e2f-9a3b-1c2d3e4f5a6b",
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "lower_limit": 10,
  "price": 4490,
  "percentage_discount": 0,
  "usergroup_id": null,
  "created_at": "2026-10-11T21:30:00Z"
}

Campos da resposta

idstring (uuid)
Id da escala.
product_idstring (uuid)
Produto.
lower_limitinteger
Quantidade mínima para a escala valer.
priceinteger
Preço unitário em centavos.
percentage_discountnumber
Percentual de 0 a 100 sobre o preço base. Se maior que zero, vale no lugar de price.
usergroup_idstring | null
null = todos; guest = visitantes; registered = logados; ou o UUID de um grupo de clientes.
value_per_kginteger
Preço de referência por kg, só exibição (centavos).
value_per_unitinteger
Preço de referência por unidade, só exibição (centavos).
created_atstring
Criação (RFC 3339).

Erros (criar)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
400lower_limit menor que 1.{"error":"lower_limit must be at least 1"}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}

Substituir todas

Apaga todas as escalas do produto e grava a lista enviada. Se a lista contiver a escala lower_limit: 1 sem grupo, o preço do produto passa a ser o dela (com o percentual aplicado, se houver).

PUT/api/v1/vendor/products/{id}/price-tiersSeller

Substituir todas as escalas

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

idstring (uuid)obrigatório
Id do produto.

Corpo da requisição

tiersarrayobrigatório

Escalas a gravar (lista vazia remove todas). Itens como em "Criar uma escala"; lower_limit menor que 1 vira 1.

lower_limitintegerobrigatório
Quantidade mínima. Mínimo 1.
priceintegerobrigatório
Preço unitário em centavos.
percentage_discountnumber
Percentual de desconto (0 a 100; fora disso é ajustado).
usergroup_idstring
Grupo: omitido ou vazio = todos; guest, registered ou UUID de grupo.
value_per_kginteger
Preço de referência por kg (só exibição).
value_per_unitinteger
Preço de referência por unidade (só exibição).

Exemplo de requisição (substituir)

bash
curl -X PUT "$BASE_URL/api/v1/vendor/products/$PRODUCT_ID/price-tiers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tiers": [
    {
      "lower_limit": 1,
      "price": 4990
    },
    {
      "lower_limit": 10,
      "price": 4490
    },
    {
      "lower_limit": 50,
      "percentage_discount": 15,
      "price": 0
    }
  ]
}'

Resposta (substituir)

200Escalas gravadas
json
{
  "tiers": [
    {
      "id": "7a6b5c4d-0001-4e2f-9a3b-1c2d3e4f5a6b",
      "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
      "lower_limit": 10,
      "price": 4490,
      "percentage_discount": 0,
      "usergroup_id": null,
      "created_at": "2026-10-11T21:30:00Z"
    }
  ],
  "base_price": 4990,
  "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d"
}

Campos da resposta

tiersarray

Escalas, ordenadas por grupo e quantidade.

idstring (uuid)
Id da escala.
product_idstring (uuid)
Produto.
lower_limitinteger
Quantidade mínima para a escala valer.
priceinteger
Preço unitário em centavos.
percentage_discountnumber
Percentual de 0 a 100 sobre o preço base. Se maior que zero, vale no lugar de price.
usergroup_idstring | null
null = todos; guest = visitantes; registered = logados; ou o UUID de um grupo de clientes.
value_per_kginteger
Preço de referência por kg, só exibição (centavos).
value_per_unitinteger
Preço de referência por unidade, só exibição (centavos).
created_atstring
Criação (RFC 3339).
base_priceinteger
Preço base do produto em centavos.
product_idstring (uuid)
Produto.

Erros (substituir)

StatusQuandoCorpo
401Token ausente, inválido ou expirado.{"error":"missing authorization header"}
403Token que não é de seller, ou usuário sem o privilégio exigido pela rota.{"error":"insufficient vendor privileges","privilege_required_any":["vendor_catalog"]}
403O produto existe mas é de outro seller (ou da loja).{"error":"you do not have access to this product"}
404Produto não existe.{"error":"product not found"}
Remover uma escala só

Para remover uma escala sem mexer nas outras, use DELETE /api/v1/vendor/price-tiers/{id} (id da escala), rota fora do caminho do produto, ou reenvie a lista completa com PUT.

Percentual manda no preço

Quando percentage_discount é maior que zero, o carrinho calcula o desconto sobre o preço base do produto e ignora price. Para ter só preço fixo, deixe o percentual em 0.

Veja também

  • Variações e opções: visão geral
  • Produtos do seller
Anterior
Eixos e geração de variações
Próxima
Produtos obrigatórios
Nesta página
  • Ler
  • Exemplo de requisição (ler)
  • Resposta (ler)
  • Erros (ler)
  • Criar uma escala
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Substituir todas
  • Exemplo de requisição (substituir)
  • Resposta (substituir)
  • Erros (substituir)
  • Veja também