API atual/Referência completa/Pedidos e conta do cliente

GETMeus pedidos

Lista o histórico de pedidos do cliente logado, do mais novo para o mais antigo, com filtros e paginação.

Devolve o histórico de pedidos do cliente logado, do mais novo para o mais antigo. É a base da tela "Meus pedidos" de qualquer loja ou aplicativo: cada item já traz o necessário para desenhar o cartão (número, data, status, total, forma de pagamento e uma prévia dos produtos).

Só entram pedidos pai; os sub-pedidos de cada seller ficam de fora (veja Acompanhar o envio). Se a conta do cliente pertence a uma conta corporativa (mesmo CNPJ), a lista inclui os pedidos dos usuários vinculados.

GET/api/v1/storefront/ordersCliente

Lista os pedidos do cliente logado

Parâmetros de consulta

pageintegerpadrão: 1

Página, a partir de 1. Valor menor que 1 vira 1.

per_pageintegerpadrão: 20

Itens por página, de 1 a 100. Fora desse intervalo (inclusive 0) volta ao padrão.

statusstring

Filtra por status. Aceita o código (pending, delivered...) ou a letra (O, C...) do cadastro da loja. all ou vazio não filtra. Um status que não existe devolve lista vazia.

payment_statusstring

pendingauthorizedcapturedrefundedfailed

Filtra pela situação do pagamento: pending, authorized, captured (ou paid), refunded ou failed. Um valor desconhecido vira pending em silêncio, em vez de dar erro.

searchstring

Texto livre: casa, sem diferenciar maiúsculas, com um trecho do número do pedido ou do nome de qualquer produto do pedido.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/orders?status=pending&per_page=10" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedidos do cliente

json

{
  "orders": [
    {
      "id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "order_id": "6af86ed3-d949-474d-8e04-513c6e83bfe4",
      "order_number": "PEDIDO-20261011-0009",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "customer_id": "264a70c1-9c69-458d-ac73-838543f87da2",
      "customer_name": "Maria Souza",
      "customer_email": "maria.souza@example.com",
      "subtotal": 4990,
      "shipping_total": 1000,
      "tax_total": 0,
      "discount_total": 724,
      "total": 5266,
      "currency": "BRL",
      "payment_method": "pix",
      "payment_method_name": "PIX",
      "payment_status": "pending",
      "sales_channel": "web",
      "shipping_method_name": "Entrega Padrão",
      "min_delivery_days": 10,
      "max_delivery_days": 10,
      "is_guest": false,
      "status": "O",
      "status_text": "pending",
      "items_count": 1,
      "items": [
        {
          "id": "a43b9f10-5590-424b-87c8-dffa34bae43d",
          "product_id": "a34f126e-ff3b-4779-bf74-bda03502136e",
          "product_name": "Caneca Exemplo",
          "product_image": "/uploads/exemplo/caneca.png",
          "quantity": 0,
          "unit_price": 0,
          "total": 0
        }
      ],
      "total_str": "52.66",
      "timestamp": 1791752125,
      "created_at": "2026-10-11T20:55:25.558277Z",
      "updated_at": "2026-10-11T20:55:25.558277Z"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 20,
  "total_pages": 1
}

Campos da resposta

ordersarray

Pedidos da página. Quando o cliente não tem nenhum, o servidor devolve null em vez de []: trate os dois.

orders[].iduuid

Id do pedido. Os demais campos do resumo são os mesmos do bloco order de Consultar pedido.

orders[].items_countinteger

Quantidade de linhas do pedido.

orders[].itemsarray

Prévia das linhas, para desenhar miniaturas: id, product_id, product_name e product_image (caminho ou URL, pode faltar). quantity, unit_price e total vêm sempre zerados aqui; para valores reais abra o pedido.

totalinteger

Pedidos que atendem ao filtro, somando todas as páginas.

pageinteger

Página devolvida.

per_pageinteger

Itens por página aplicados.

total_pagesinteger

Quantidade de páginas.

Erros

Status	Quando	Corpo
401	Sem token, ou token inválido ou expirado	`{"error":"missing authorization header"}` / `{"error":"invalid or expired token"}`
500	Falha interna ao consultar o banco da loja	`{"error":"failed to list orders","detail":"..."}`

Veja também