Alterar pedido

Atualiza observações, rastreio, pagamento, responsável, itens, endereços e totais de um pedido existente.

Use esta operação para corrigir ou complementar um pedido que já existe: gravar o código de rastreio, anotar uma observação interna, marcar o pagamento como recebido, trocar o responsável, ou (na edição completa) trocar itens, endereços e totais.

Há duas rotas, com alcances diferentes:

Quero...	Rota
Mudar só campos simples (observações, rastreio, pagamento, responsável)	`PUT /api/v1/admin/orders/{id}`
Reescrever itens, endereços, totais e, se preciso, o status	`PUT /api/v1/admin/orders/{id}/edit`

Mudar o status não é feito pela rota de alteração simples. Para isso veja Alterar o status.

PUT/api/v1/admin/orders/{id}Admin

Atualiza campos simples do pedido

Exige o privilégio manage_orders. Altera só os campos enviados (os ausentes ficam como estão). Mudar o payment_status para paid em uma forma de pagamento sem gateway (como Boleto Faturado ou pagamento na entrega) também leva o pedido para o status "processando", como se o pagamento tivesse sido confirmado.

Path parameters

iduuidobrigatório

Id do pedido.

Corpo da requisição

admin_notesstring

Observação interna.

customer_notesstring

Observação do cliente.

tracking_numberstring

Código de rastreio do pedido. "" limpa o campo.

payment_methodstring

Código da forma de pagamento. Não é validado.

payment_statusstring

pendingpaidfailedrefunded

Situação do pagamento. Na leitura, paid aparece como captured. Mudanças geram uma linha própria no histórico e o evento de pagamento alterado.

shipping_methodstring

Nome da forma de envio. "" limpa o campo.

assigned_touuid

Usuário responsável pelo pedido. "" remove o responsável.

PUT/api/v1/admin/orders/{id}/editAdmin

Edição completa do pedido (itens, endereços, totais, status)

Exige o privilégio manage_orders. É a edição completa da tela de pedido do painel. Também aceita todos os campos de PUT /api/v1/admin/orders/{id}.

Pontos de atenção:

Se você enviar items, todas as linhas atuais são apagadas e substituídas pelas enviadas. O preço de cada linha (unit_price) é o que você mandar; a plataforma não consulta o catálogo para preço, frete, imposto ou promoção.
Se você enviar items sem subtotal/total, a plataforma recalcula subtotal pela soma das linhas e total = subtotal + frete + imposto - desconto.
Enviar billing_address ou shipping_address substitui o endereço inteiro.
Se você enviar status, a mudança passa pelo fluxo normal de status (estoque, estorno, e-mails e eventos), depois de gravados os demais campos.

Path parameters

iduuidobrigatório

Id do pedido.

Corpo da requisição

customer_iduuid

Troca o cliente do pedido.

customer_emailstring

E-mail do cliente no pedido.

customer_namestring

Nome do cliente no pedido.

customer_notesstring

Observação do cliente.

admin_notesstring

Observação interna.

payment_methodstring

Código da forma de pagamento.

payment_statusstring

pendingpaidfailedrefunded

Situação do pagamento.

shipping_methodstring

Nome da forma de envio.

tracking_numberstring

Código de rastreio do pedido.

statusstring

Novo status, pelo código longo (shipped) ou pela letra do cadastro de status da loja. Valor desconhecido causa 400 invalid_status.

assigned_touuid

Responsável pelo pedido; "" remove.

itemsarray

Novas linhas do pedido (substituem as atuais).

product_iduuidobrigatório

Produto.

variation_iduuid

Variação do produto.

quantityintegerobrigatório

Quantidade (inteiro).

unit_priceintegerobrigatório

Preço unitário em centavos.

optionsobject

Opções da linha.

notestring

Observação da linha. Se vazia, mantém a que a linha tinha.

billing_addressobject

Endereço de cobrança (first_name, last_name, address_line1, address_line2, district, complement, city, state, postal_code, country, phone, cpf).

shipping_addressobject

Endereço de entrega, com os mesmos campos.

subtotalinteger

Subtotal em centavos.

shipping_totalinteger

Frete em centavos.

tax_totalinteger

Imposto em centavos.

discount_totalinteger

Desconto em centavos.

totalinteger

Total em centavos. Se omitido e algum componente mudou, é recalculado (nunca abaixo de zero).

Exemplo de requisição

bash

# Campos simples
curl -X PUT "$BASE_URL/api/v1/admin/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"admin_notes":"Cliente pediu entrega à tarde","tracking_number":"BR987654321BR","payment_status":"paid"}'

# Edição completa: corrige o endereço de entrega
curl -X PUT "$BASE_URL/api/v1/admin/orders/$ORDER_ID/edit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_address": {
      "first_name": "Maria", "last_name": "Souza", "address_line1": "Rua Augusta, 500",
      "city": "São Paulo", "state": "SP", "postal_code": "01304-000", "country": "BR"
    }
  }'

Resposta

200Pedido alterado

json

{
  "order": {
    "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
    "order_number": "PEDIDO-20261011-0001",
    "total": 192895,
    "payment_status": "captured",
    "admin_notes": "Cliente pediu entrega à tarde",
    "tracking_number": "BR987654321BR",
    "status": "P",
    "status_text": "processing",
    "updated_at": "2026-10-11T20:19:31.828444Z"
  },
  "items": [
    { "id": "04b62cb6-7421-41ed-9e27-4eb3c11343c4", "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "quantity": 1, "unit_price": 167895, "total": 167895 }
  ],
  "addresses": [
    { "address_type": "shipping", "first_name": "Maria", "address_line1": "Avenida Paulista, 1000", "postal_code": "01310-100" }
  ],
  "status_history": [
    { "old_status": "pending", "new_status": "captured", "reason": "payment_status_changed_admin", "kind": "payment" }
  ],
  "sub_orders": [
    { "id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0", "order_number": "PEDIDO-20261011-0001-V1", "total": 169654 }
  ]
}

Campos da resposta

orderobject

O pedido já com as alterações (campos de Consultar pedido).

itemsarray

Linhas do pedido depois da alteração.

addressesarray

Endereços do pedido depois da alteração.

status_historyarray

Histórico. Mudança de payment_status entra com kind: "payment"; não é uma mudança do status do pedido.

sub_ordersarray

Só em pedido pai.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body"}`
400	`payment_status` fora de `pending`, `paid`, `failed`, `refunded`	`{"error":"invalid_payment_status","detail":"payment_status must be one of: pending, paid, failed, refunded"}`
400	`status` enviado em `PUT /api/v1/admin/orders/{id}`	`{"error":"status is not editable here","detail":"..."}` (o detalhe ensina a rota certa)
400	`status` desconhecido em `/edit`	`{"error":"invalid_status","detail":"the requested status is not a valid order status"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão (`manage_orders`)	`{"error":"insufficient privileges","required":"manage_orders"}`
404	O pedido não existe	`{"error":"order not found"}`
400	`terms_accepted` enviado em `PUT /api/v1/admin/orders/{id}` (o aceite dos termos não se edita)	`{"error":"immutable_field","detail":"..."}`
422	Alteração recusada por regra da loja	`{"error":"<mensagem da loja>","detail":"refused_by_store"}`
500	Id que não é UUID ou falha interna	`{"error":"failed to update order","detail":"..."}`

Veja também

Alterar pedido

Atualiza observações, rastreio, pagamento, responsável, itens, endereços e totais de um pedido existente.

Há duas rotas, com alcances diferentes:

Quero...	Rota
Mudar só campos simples (observações, rastreio, pagamento, responsável)	`PUT /api/v1/admin/orders/{id}`
Reescrever itens, endereços, totais e, se preciso, o status	`PUT /api/v1/admin/orders/{id}/edit`

Mudar o status não é feito pela rota de alteração simples. Para isso veja Alterar o status.

PUT/api/v1/admin/orders/{id}Admin

Atualiza campos simples do pedido

Path parameters

iduuidobrigatório

Id do pedido.

Corpo da requisição

admin_notesstring

Observação interna.

customer_notesstring

Observação do cliente.

tracking_numberstring

Código de rastreio do pedido. "" limpa o campo.

payment_methodstring

Código da forma de pagamento. Não é validado.

payment_statusstring

pendingpaidfailedrefunded

Situação do pagamento. Na leitura, paid aparece como captured. Mudanças geram uma linha própria no histórico e o evento de pagamento alterado.

shipping_methodstring

Nome da forma de envio. "" limpa o campo.

assigned_touuid

Usuário responsável pelo pedido. "" remove o responsável.

PUT/api/v1/admin/orders/{id}/editAdmin

Edição completa do pedido (itens, endereços, totais, status)

Exige o privilégio manage_orders. É a edição completa da tela de pedido do painel. Também aceita todos os campos de PUT /api/v1/admin/orders/{id}.

Pontos de atenção:

Se você enviar items, todas as linhas atuais são apagadas e substituídas pelas enviadas. O preço de cada linha (unit_price) é o que você mandar; a plataforma não consulta o catálogo para preço, frete, imposto ou promoção.
Se você enviar items sem subtotal/total, a plataforma recalcula subtotal pela soma das linhas e total = subtotal + frete + imposto - desconto.
Enviar billing_address ou shipping_address substitui o endereço inteiro.
Se você enviar status, a mudança passa pelo fluxo normal de status (estoque, estorno, e-mails e eventos), depois de gravados os demais campos.

Path parameters

iduuidobrigatório

Id do pedido.

Corpo da requisição

customer_iduuid

Troca o cliente do pedido.

customer_emailstring

E-mail do cliente no pedido.

customer_namestring

Nome do cliente no pedido.

customer_notesstring

Observação do cliente.

admin_notesstring

Observação interna.

payment_methodstring

Código da forma de pagamento.

payment_statusstring

pendingpaidfailedrefunded

Situação do pagamento.

shipping_methodstring

Nome da forma de envio.

tracking_numberstring

Código de rastreio do pedido.

statusstring

Novo status, pelo código longo (shipped) ou pela letra do cadastro de status da loja. Valor desconhecido causa 400 invalid_status.

assigned_touuid

Responsável pelo pedido; "" remove.

itemsarray

Novas linhas do pedido (substituem as atuais).

product_iduuidobrigatório

Produto.

variation_iduuid

Variação do produto.

quantityintegerobrigatório

Quantidade (inteiro).

unit_priceintegerobrigatório

Preço unitário em centavos.

optionsobject

Opções da linha.

notestring

Observação da linha. Se vazia, mantém a que a linha tinha.

billing_addressobject

Endereço de cobrança (first_name, last_name, address_line1, address_line2, district, complement, city, state, postal_code, country, phone, cpf).

shipping_addressobject

Endereço de entrega, com os mesmos campos.

subtotalinteger

Subtotal em centavos.

shipping_totalinteger

Frete em centavos.

tax_totalinteger

Imposto em centavos.

discount_totalinteger

Desconto em centavos.

totalinteger

Total em centavos. Se omitido e algum componente mudou, é recalculado (nunca abaixo de zero).

Exemplo de requisição

bash

# Campos simples
curl -X PUT "$BASE_URL/api/v1/admin/orders/$ORDER_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"admin_notes":"Cliente pediu entrega à tarde","tracking_number":"BR987654321BR","payment_status":"paid"}'

# Edição completa: corrige o endereço de entrega
curl -X PUT "$BASE_URL/api/v1/admin/orders/$ORDER_ID/edit" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_address": {
      "first_name": "Maria", "last_name": "Souza", "address_line1": "Rua Augusta, 500",
      "city": "São Paulo", "state": "SP", "postal_code": "01304-000", "country": "BR"
    }
  }'

Resposta

200Pedido alterado

json

{
  "order": {
    "id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
    "order_number": "PEDIDO-20261011-0001",
    "total": 192895,
    "payment_status": "captured",
    "admin_notes": "Cliente pediu entrega à tarde",
    "tracking_number": "BR987654321BR",
    "status": "P",
    "status_text": "processing",
    "updated_at": "2026-10-11T20:19:31.828444Z"
  },
  "items": [
    { "id": "04b62cb6-7421-41ed-9e27-4eb3c11343c4", "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6", "quantity": 1, "unit_price": 167895, "total": 167895 }
  ],
  "addresses": [
    { "address_type": "shipping", "first_name": "Maria", "address_line1": "Avenida Paulista, 1000", "postal_code": "01310-100" }
  ],
  "status_history": [
    { "old_status": "pending", "new_status": "captured", "reason": "payment_status_changed_admin", "kind": "payment" }
  ],
  "sub_orders": [
    { "id": "2b4bd680-b717-4295-a2be-8b5c6771a4d0", "order_number": "PEDIDO-20261011-0001-V1", "total": 169654 }
  ]
}

Campos da resposta

orderobject

O pedido já com as alterações (campos de Consultar pedido).

itemsarray

Linhas do pedido depois da alteração.

addressesarray

Endereços do pedido depois da alteração.

status_historyarray

Histórico. Mudança de payment_status entra com kind: "payment"; não é uma mudança do status do pedido.

sub_ordersarray

Só em pedido pai.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body"}`
400	`payment_status` fora de `pending`, `paid`, `failed`, `refunded`	`{"error":"invalid_payment_status","detail":"payment_status must be one of: pending, paid, failed, refunded"}`
400	`status` enviado em `PUT /api/v1/admin/orders/{id}`	`{"error":"status is not editable here","detail":"..."}` (o detalhe ensina a rota certa)
400	`status` desconhecido em `/edit`	`{"error":"invalid_status","detail":"the requested status is not a valid order status"}`
401	Sem credenciais ou token expirado	`{"error":"invalid or expired token"}`
403	Sem permissão (`manage_orders`)	`{"error":"insufficient privileges","required":"manage_orders"}`
404	O pedido não existe	`{"error":"order not found"}`
400	`terms_accepted` enviado em `PUT /api/v1/admin/orders/{id}` (o aceite dos termos não se edita)	`{"error":"immutable_field","detail":"..."}`
422	Alteração recusada por regra da loja	`{"error":"<mensagem da loja>","detail":"refused_by_store"}`
500	Id que não é UUID ou falha interna	`{"error":"failed to update order","detail":"..."}`