API atual/Referência completa/Métodos de envio

Alterar método de envio

Altera só os campos enviados de um método de envio, como preço, prazo, status e seller dono.

Use esta rota para ajustar um método existente: mudar o preço fixo, trocar o texto do prazo, desativar ou reordenar. Apesar de ser um PUT, a alteração é parcial: só os campos presentes no corpo mudam, e os ausentes ficam como estão. Isso também significa que você não consegue "limpar" um texto enviando null; envie uma string vazia.

Ao mudar carrier, rate_calculation ou carrier_service_code, a plataforma valida o método resultante (o que ficaria depois da alteração), não só o campo enviado.

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

Altera um método de envio

Exige manage_shipping.

Parâmetros de caminho

iduuidobrigatório

Id do método.

Corpo da requisição

namestring

Nome mostrado ao cliente.

codestring

Não é alterável por esta rota: o campo é ignorado.

carrierstring

manual (padrão) ou o código da integração de transportadora.

carrier_service_codestring

Código do serviço no contrato da transportadora. É validado: veja o erro invalid_carrier_service_code.

rate_calculationstring

MR

M manual ou R em tempo real.

descriptionstring

Texto livre.

delivery_timestring

Prazo em texto livre, por exemplo 3-5 dias úteis.

statusstring

AD

A ou D (também aceita active e disabled). Vazio = A.

min_weightnumber

Peso mínimo do carrinho, em kg. 0 = sem mínimo.

max_weightnumber

Peso máximo do carrinho, em kg. 0 = sem máximo.

flat_rateinteger

Preço fixo em centavos.

free_shipping_thresholdinteger

Descontinuado: subtotal em centavos para frete grátis.

estimated_daysinteger

Descontinuado: prazo em dias.

free_shippingboolean

Se o método pode receber frete grátis de promoções.

is_address_requiredboolean

Se exige endereço de entrega. Use false para retirada.

rate_area_iduuid

Descontinuado: área de tarifa única. Prefira os vínculos em /areas.

tax_idsstring

Ids de impostos separados por vírgula.

usergroup_idsstring

Ids de grupos de usuários separados por vírgula. Vazio = todos.

icon_urlstring

URL do ícone do checkout.

surchargeinteger

Descontinuado: acréscimo fixo em centavos.

surcharge_percentinteger

Descontinuado: acréscimo percentual.

use_for_all_vendorsboolean

Vale para o carrinho de todos os sellers (apenas métodos sem company_id).

company_iduuid

Seller dono do método. Omita para um método da loja.

positioninteger

Ordem de exibição no checkout.

configobject

JSON específico da integração (descontinuado).

service_paramsobject

Parâmetros da transportadora.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/shipping-methods/$METHOD_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flat_rate": 1900,
    "delivery_time": "2 dias úteis"
  }'

Resposta

200Método alterado

json

{
  "id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "display_id": 71,
  "tenant_id": "dfe2555e-bfd0-41a8-9fa1-9586999f3798",
  "name": "Entrega Padrão",
  "code": "entrega_padrao",
  "carrier": "manual",
  "rate_calculation": "M",
  "delivery_time": "2 dias úteis",
  "status": "A",
  "min_weight": 0,
  "max_weight": 0,
  "free_shipping_threshold": 0,
  "flat_rate": 1900,
  "estimated_days": 0,
  "free_shipping": false,
  "is_address_required": false,
  "tax_ids": "",
  "usergroup_ids": "",
  "icon_url": "",
  "surcharge": 0,
  "surcharge_percent": 0,
  "use_for_all_vendors": true,
  "position": 0,
  "created_at": "2026-10-11T21:35:34.649864Z",
  "updated_at": "2026-10-11T21:35:34.649864Z",
  "shipping_id": "65d71956-dbae-4df9-a3a3-129ac66f6324",
  "shipping": "Entrega Padrão",
  "module": "manual",
  "rate_str": "19.00",
  "timestamp": 1791754534,
  "updated_timestamp": 1791754534
}

A resposta é o método completo depois da alteração (veja os campos em Listar e consultar).

Erros

Status	Quando	Corpo
401	Sem token, token inválido ou expirado	`{"error":"invalid or expired token"}`
403	Usuário sem o privilégio `manage_shipping`	`{"error":"insufficient privileges","privilege_required_any":["manage_shipping"]}`
400	Corpo que não é JSON, ou `id` que não é UUID	`{"error":"invalid request body","detail":"..."}` / `{"error":"invalid id","detail":"id must be a valid UUID"}`
400	Serviço de transportadora recusado	`{"error":"invalid_carrier_service_code","reason":"wrong_carrier","detail":"..."}`
500	O método não existe, ou o valor é inválido para o banco (por exemplo `status` desconhecido)	`{"error":"failed to update shipping method","detail":"..."}`

Veja também