VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Métodos de envio

Faixas de preço

Lê, cria, altera e apaga as faixas que definem o preço do frete de um método por peso, valor do pedido e quantidade de itens.

Uma faixa é uma linha da tabela de preços do método: "carrinhos de até 5 kg custam R$ 19,00". O checkout escolhe a faixa cujos limites de peso, valor do pedido e quantidade de itens contêm o carrinho (na área do endereço) e cobra o rate dela. Um limite 0 significa "sem limite" naquela medida.

Esta é a tabela de preços por faixa. A tabela de tarifas por degrau é independente. Toda gravação invalida o cache de cotações.

Listar faixas

GET/api/v1/admin/shipping-methods/{id}/tiersAdmin

Lista as faixas de um método

Devolve todas as faixas do método, de todas as áreas, ordenadas por peso mínimo e depois por valor mínimo. Um método sem faixas devolve tiers: null.

Parâmetros de caminho

iduuidobrigatório
Id do método.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/tiers" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Faixas retornadas
json
{
  "tiers": [
    {
      "id": "e0b01930-48f1-441e-b278-96b99db92887",
      "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "min_weight": 0,
      "max_weight": 5000,
      "min_order_value": 0,
      "max_order_value": 0,
      "rate": 1900,
      "rate_area_id": null,
      "min_items": 0,
      "max_items": 0,
      "created_at": "2026-10-11T21:35:34.687301Z",
      "rate_id": "e0b01930-48f1-441e-b278-96b99db92887",
      "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
      "rate_value": "19.00",
      "timestamp": 1791754534
    }
  ],
  "total": 1
}

Campos da resposta

tiersarray
Faixas do método.
totalinteger
Quantidade de faixas.
tiers[].iduuid
Id da faixa.
tiers[].shipping_method_iduuid
Método dono da faixa.
tiers[].min_weightinteger
Peso mínimo do carrinho, em gramas. 0 = sem mínimo.
tiers[].max_weightinteger
Peso máximo, em gramas. 0 = sem máximo.
tiers[].min_order_valueinteger
Valor mínimo do pedido, em centavos. 0 = sem mínimo.
tiers[].max_order_valueinteger
Valor máximo do pedido, em centavos. 0 = sem máximo.
tiers[].rateinteger
Preço do frete nesta faixa, em centavos.
tiers[].rate_area_iduuid
Área de tarifa a que a faixa pertence. null = faixa do vínculo padrão (todos os outros destinos).
tiers[].min_itemsinteger
Mínimo de itens no carrinho. 0 = sem mínimo.
tiers[].max_itemsinteger
Máximo de itens. 0 = sem máximo.
tiers[].created_atstring
Criação, RFC 3339 em UTC.
tiers[].rate_iduuid
Alias de id. shipping_id, rate_value (preço em string decimal) e timestamp (Unix) também são aliases.

Criar uma faixa

Não há validação de limites: duas faixas podem se sobrepor, e o corpo vazio cria uma faixa de R$ 0,00 sem limites. Confira o conjunto depois de gravar.

POST/api/v1/admin/shipping-methods/{id}/tiersAdmin

Cria uma faixa de preço

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório
Id do método.

Corpo da requisição

rateinteger
Preço do frete em centavos. Se omitido, vale 0 (frete grátis nesta faixa).
min_weightinteger
Gramas. 0 = sem mínimo.
max_weightinteger
Gramas. 0 = sem máximo.
min_order_valueinteger
Centavos. 0 = sem mínimo.
max_order_valueinteger
Centavos. 0 = sem máximo.
min_itemsinteger
Itens. 0 = sem mínimo.
max_itemsinteger
Itens. 0 = sem máximo.
rate_area_iduuid
Área de tarifa da faixa. Omita para a faixa do vínculo padrão.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/tiers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "max_weight": 5000,
    "rate": 1900
  }'

Resposta

201Faixa criada
json
{
  "id": "e0b01930-48f1-441e-b278-96b99db92887",
  "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "min_weight": 0,
  "max_weight": 5000,
  "min_order_value": 0,
  "max_order_value": 0,
  "rate": 1900,
  "rate_area_id": null,
  "min_items": 0,
  "max_items": 0,
  "created_at": "2026-10-11T21:35:34.687301Z",
  "rate_id": "e0b01930-48f1-441e-b278-96b99db92887",
  "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "rate_value": "19.00",
  "timestamp": 1791754534
}

Alterar uma faixa

Alteração parcial: só os campos enviados mudam. Para mover a faixa para outra área, envie rate_area_id.

PUT/api/v1/admin/shipping-methods/{id}/tiers/{tier_id}Admin

Altera uma faixa de preço

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório
Id do método.
tier_iduuidobrigatório
Id da faixa.

Corpo da requisição

rateinteger
Preço do frete em centavos. Se omitido, vale 0 (frete grátis nesta faixa).
min_weightinteger
Gramas. 0 = sem mínimo.
max_weightinteger
Gramas. 0 = sem máximo.
min_order_valueinteger
Centavos. 0 = sem mínimo.
max_order_valueinteger
Centavos. 0 = sem máximo.
min_itemsinteger
Itens. 0 = sem mínimo.
max_itemsinteger
Itens. 0 = sem máximo.
rate_area_iduuid
Área de tarifa da faixa. Omita para a faixa do vínculo padrão.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/tiers/$TIER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rate": 2100
  }'

Resposta

200Faixa alterada
json
{
  "id": "e0b01930-48f1-441e-b278-96b99db92887",
  "shipping_method_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "min_weight": 0,
  "max_weight": 5000,
  "min_order_value": 0,
  "max_order_value": 0,
  "rate": 2100,
  "rate_area_id": null,
  "min_items": 0,
  "max_items": 0,
  "created_at": "2026-10-11T21:35:34.687301Z",
  "rate_id": "e0b01930-48f1-441e-b278-96b99db92887",
  "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "rate_value": "21.00",
  "timestamp": 1791754534
}

Apagar uma faixa

DELETE/api/v1/admin/shipping-methods/{id}/tiers/{tier_id}Admin

Apaga uma faixa de preço

Exige manage_shipping. A faixa precisa pertencer ao método do caminho.

Parâmetros de caminho

iduuidobrigatório
Id do método.
tier_iduuidobrigatório
Id da faixa.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID/tiers/$TIER_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Faixa apagada
json
{
  "message": "shipping rate tier deleted"
}

Erros

StatusQuandoCorpo
401Sem token, token inválido ou expirado{"error":"invalid or expired token"}
403Usuário sem o privilégio manage_shipping{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}
400Corpo que não é JSON{"error":"invalid request body","detail":"..."}
500Método ou faixa inexistente, rate_area_id que não existe, ou outro valor recusado pelo banco{"error":"failed to create shipping rate tier","detail":"..."} / {"error":"failed to update shipping rate tier","detail":"..."} / {"error":"failed to delete shipping rate tier","detail":"shipping rate tier not found: ..."}
Como montar uma tabela

Cubra todo o intervalo sem buracos: se a última faixa termina em max_weight: 5000, um carrinho de 6 kg não encontra faixa nenhuma. Deixe a última faixa com max_weight: 0 para valer "daí para cima".

Gramas aqui, quilos no método

Os pesos das faixas são em gramas. Os campos min_weight e max_weight do próprio método são em quilos. Não copie um valor de um lugar para o outro.

Veja também

  • Áreas do método
  • Tarifas por degrau
  • Criar um método
Anterior
Apagar e duplicar método
Próxima
Tarifas por degrau
Nesta página
  • Listar faixas
  • Exemplo de requisição
  • Resposta
  • Criar uma faixa
  • Exemplo de requisição
  • Resposta
  • Alterar uma faixa
  • Exemplo de requisição
  • Resposta
  • Apagar uma faixa
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também