Estrutura do pedido

Todos os campos do pedido, de id e displayId a items, payments, delivery, takeout, schedule e test, com exemplos completos de DELIVERY e TAKEOUT.

GET /v1/orders/{orderId} devolve o pedido no formato do padrão Open Delivery 1.4.0. É o mesmo corpo para qualquer origem: app, site, cardápio digital, mesa ou marketplace produzem a mesma estrutura, com a origem exposta em extraInfo.

GET /v1/orders/3f8a1c2d-5b6e-4f7a-9c8d-1e2f3a4b5c6d
Authorization: Bearer {access_token}

Escopo: orders:read. Pedido de outra loja ou id inexistente respondem 404, sem distinção. Um orderId que não é GUID também responde 404.

Regras gerais do formato:

Campos sem valor vêm como null, e não são omitidos. A chave está sempre lá.
Datas são ISO 8601 em UTC com sufixo Z.
Dinheiro é sempre um objeto Money: {"value": 49.90, "currency": "BRL"}. Os valores são copiados do pedido, nunca recalculados: o que você lê é o que a loja cobrou.
Ids são GUIDs. displayId é o número curto que a loja e o cliente veem.

Campos

Raiz

Campo	Tipo	Nulo?	Descrição
`id`	GUID	não	Identificador do pedido. É o `orderId` dos eventos e das ações.
`displayId`	string	não	Número curto do pedido, o que aparece no cupom e na tela da loja. Não é único para sempre.
`type`	`DELIVERY`, `TAKEOUT`, `INDOOR`	não	Entrega, retirada ou consumo no local (mesa).
`orderTiming`	`INSTANT`, `SCHEDULED`	não	Imediato ou agendado. `SCHEDULED` vem acompanhado de `schedule`.
`createdAt`	data	não	Instante de criação.
`preparationStartDateTime`	data	não	Quando começar a preparar. Igual a `createdAt` em pedido `INSTANT`; igual a `schedule.scheduledDateTimeStart` em `SCHEDULED`.
`merchant`	objeto	não	`{id, name}` da loja. `id` é o `merchant_id` da sua credencial.
`customer`	objeto	não	Dados do cliente. Veja customer.
`items`	array	não	Itens do pedido. Veja items.
`otherFees`	array	sim	Taxas além dos itens (entrega, acréscimo). `null` quando não há.
`discounts`	array	sim	Descontos aplicados. `null` quando não há.
`total`	objeto	não	Totais do pedido. Veja total.
`payments`	objeto	não	Pagamentos. Veja payments.
`delivery`	objeto	sim	Só em pedido `DELIVERY`. Veja delivery.
`takeout`	objeto	sim	Só em pedido `TAKEOUT` ou `INDOOR`. Veja takeout.
`schedule`	objeto	sim	Só em pedido `SCHEDULED`. Veja schedule.
`extraInfo`	string	sim	Observação do pedido e origem, no formato `"obs \| origem=X \| canal=Y \| numeroCanal=Z"`. Partes sem valor são omitidas.
`test`	boolean	não	`true` em pedido de loja de teste. Nunca envie um pedido de teste para a sua produção.

customer

Campo	Tipo	Nulo?	Descrição
`id`	GUID	sim	Identificador do cliente no MeuPedido.
`name`	string	sim	Nome informado no pedido.
`phone`	objeto	sim	`{number, extension}`. `number` é o telefone como o cliente informou; `extension` é o ramal, normalmente `null`.
`documentNumber`	string	sim	CPF ou CNPJ, quando informado para a nota.
`email`	string	sim	E-mail, quando informado.
`ordersCountOnMerchant`	inteiro	sim	Quantidade de pedidos do cliente nesta loja, quando disponível.

items

Cada item é um produto do pedido com as opções escolhidas.

Campo	Tipo	Nulo?	Descrição
`id`	GUID	não	Identificador da linha do pedido.
`index`	inteiro	sim	Posição do item no pedido.
`name`	string	não	Nome do produto como foi vendido (inclui o tamanho, quando há variações).
`externalCode`	string	sim	Id do produto no cardápio (`GET /v1/merchant/{merchantId}/menus`).
`unit`	string	sim	Unidade de medida, quando aplicável.
`ean`	string	sim	Código de barras, quando cadastrado.
`quantity`	número	não	Quantidade.
`specialInstructions`	string	sim	Observação do cliente para este item.
`unitPrice`	Money	não	Preço unitário do produto, sem opções.
`optionsPrice`	Money	não	Soma das opções.
`totalPrice`	Money	não	Total da linha, o valor cobrado.
`options`	array	não	Complementos escolhidos. Vazio quando não há.

items[].options

Campo	Tipo	Nulo?	Descrição
`id`	GUID	não	Identificador da linha da opção.
`index`	inteiro	sim	Posição da opção dentro do item.
`name`	string	não	Nome do complemento.
`externalCode`	string	sim	Id da opção no cardápio.
`quantity`	número	não	Quantidade.
`unit`	string	sim	Unidade, quando aplicável.
`unitPrice`	Money	não	Preço unitário da opção.
`price`	Money	não	Total da opção.
`groupName`	string	sim	Nome do grupo de complementos, quando disponível.

otherFees

Campo	Tipo	Nulo?	Descrição
`name`	string	não	Nome da taxa, por exemplo `"Taxa de entrega"`.
`type`	`DELIVERY`, `SERVICE_FEE`	não	Taxa de entrega ou acréscimo.
`receivedBy`	`MERCHANT`	não	Quem recebe. Sempre a loja.
`price`	Money	não	Valor.

discounts

Campo	Tipo	Nulo?	Descrição
`amount`	Money	não	Valor do desconto.
`target`	`CART`	não	O desconto incide sobre o carrinho inteiro.
`targetId`	string	sim	Não usado em desconto de carrinho.
`sponsorshipValues`	array	não	Quem banca: `[{name: "MERCHANT", amount}]`. Desconto do MeuPedido é sempre da loja.

total

Campo	Tipo	Descrição
`items`	Money	Soma dos itens (`totalPrice` de cada um).
`otherFees`	Money	Soma de `otherFees`.
`discount`	Money	Soma de `discounts`.
`orderAmount`	Money	Valor final: `items + otherFees - discount`.

payments

Campo	Tipo	Descrição
`prepaid`	número	Soma dos pagamentos `ONLINE` (já pagos).
`pending`	número	Soma dos pagamentos `OFFLINE` (a cobrar na entrega ou no balcão).
`methods`	array	Um item por pagamento.

payments.methods[]

Campo	Tipo	Nulo?	Descrição
`value`	número	não	Valor deste pagamento.
`currency`	`BRL`	não	Moeda.
`method`	`CREDIT`, `DEBIT`, `CASH`, `PIX`, `MEAL_VOUCHER`, `OTHER`	não	Meio de pagamento.
`methodInfo`	string	sim	Nome do meio como a loja cadastrou (por exemplo, `"Cartão de crédito na entrega"`).
`type`	`ONLINE`, `OFFLINE`	não	`ONLINE` quando já foi pago; `OFFLINE` quando a loja cobra. Deriva do pagamento efetivo, não do meio: um PIX pago na porta é `OFFLINE`.
`changeFor`	número	sim	Em dinheiro: o valor com que o cliente vai pagar, para calcular o troco.
`brand`	string	sim	Bandeira do cartão, quando informada.
`transaction`	objeto	sim	`{transactionId, authorizationCode, acquirerDocument}` em pagamento on-line.

delivery

Presente apenas em pedido DELIVERY.

Campo	Tipo	Nulo?	Descrição
`deliveryDateTime`	data	sim	Quando foi entregue, quando registrado.
`estimatedDeliveryDateTime`	data	sim	Previsão de entrega, quando calculada.
`deliveredBy`	`MERCHANT`, `MARKETPLACE`	não	Quem entrega: a própria loja ou o marketplace de origem.
`deliveryAddress`	objeto	sim	Endereço. Veja abaixo.

delivery.deliveryAddress

Campo	Tipo	Nulo?	Descrição
`country`	string	não	`"BR"`.
`state`	string	sim	UF.
`city`	string	sim	Cidade.
`district`	string	sim	Bairro.
`street`	string	não	Logradouro.
`number`	string	sim	Número.
`postalCode`	string	sim	CEP.
`complement`	string	sim	Complemento.
`reference`	string	sim	Ponto de referência.
`formattedAddress`	string	sim	Endereço em uma linha, quando disponível.
`coordinates`	objeto	sim	`{latitude, longitude}` em graus decimais.

takeout

Presente em pedido TAKEOUT e INDOOR.

Campo	Tipo	Nulo?	Descrição
`mode`	`DEFAULT`	não	Modo de retirada.
`takeoutDateTime`	data	sim	Horário agendado da retirada. `null` em pedido imediato: o MeuPedido não inventa uma previsão.

schedule

Presente em pedido SCHEDULED.

Campo	Tipo	Nulo?	Descrição
`scheduledDateTimeStart`	data	não	Início da janela agendada. Também em `preparationStartDateTime`.
`scheduledDateTimeEnd`	data	sim	Fim da janela, quando definido.

Exemplo: pedido DELIVERY

Pedido imediato de entrega, pago por PIX on-line, com desconto e taxa de entrega.

GET /v1/orders/3f8a1c2d-5b6e-4f7a-9c8d-1e2f3a4b5c6d

{
  "id": "3f8a1c2d-5b6e-4f7a-9c8d-1e2f3a4b5c6d",
  "displayId": "1042",
  "type": "DELIVERY",
  "orderTiming": "INSTANT",
  "createdAt": "2026-09-19T14:02:11Z",
  "preparationStartDateTime": "2026-09-19T14:02:11Z",
  "merchant": {
    "id": "7f3b2c1e-9d4a-4b8e-a1c6-2e5f8d9a0b1c",
    "name": "Pizzaria Bella Massa"
  },
  "customer": {
    "id": "a8c4e2f0-3b1d-4e6a-9f5c-7d2b8a1c0e3f",
    "name": "Mariana Souza",
    "phone": { "number": "11987654321", "extension": null },
    "documentNumber": null,
    "email": "mariana.souza@example.com",
    "ordersCountOnMerchant": null
  },
  "items": [
    {
      "id": "5d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
      "index": null,
      "name": "Pizza Margherita Grande",
      "externalCode": "c2d3e4f5-a6b7-4c8d-9e0f-1a2b3c4d5e6f",
      "unit": null,
      "ean": null,
      "quantity": 1,
      "specialInstructions": "Bem assada.",
      "unitPrice": { "value": 49.90, "currency": "BRL" },
      "optionsPrice": { "value": 6.00, "currency": "BRL" },
      "totalPrice": { "value": 55.90, "currency": "BRL" },
      "options": [
        {
          "id": "6e2f3a4b-5c6d-4e7f-9a8b-0c1d2e3f4a5b",
          "index": null,
          "name": "Borda recheada com catupiry",
          "externalCode": "d3e4f5a6-b7c8-4d9e-8f0a-2b3c4d5e6f7a",
          "quantity": 1,
          "unit": null,
          "unitPrice": { "value": 6.00, "currency": "BRL" },
          "price": { "value": 6.00, "currency": "BRL" },
          "groupName": null
        }
      ]
    },
    {
      "id": "7f3a4b5c-6d7e-4f8a-9b0c-1d2e3f4a5b6c",
      "index": null,
      "name": "Refrigerante lata 350 ml",
      "externalCode": "e4f5a6b7-c8d9-4e0f-9a1b-3c4d5e6f7a8b",
      "unit": null,
      "ean": null,
      "quantity": 2,
      "specialInstructions": null,
      "unitPrice": { "value": 6.50, "currency": "BRL" },
      "optionsPrice": { "value": 0, "currency": "BRL" },
      "totalPrice": { "value": 13.00, "currency": "BRL" },
      "options": []
    }
  ],
  "otherFees": [
    {
      "name": "Taxa de entrega",
      "type": "DELIVERY",
      "receivedBy": "MERCHANT",
      "price": { "value": 8.00, "currency": "BRL" }
    }
  ],
  "discounts": [
    {
      "amount": { "value": 5.00, "currency": "BRL" },
      "target": "CART",
      "targetId": null,
      "sponsorshipValues": [
        { "name": "MERCHANT", "amount": { "value": 5.00, "currency": "BRL" } }
      ]
    }
  ],
  "total": {
    "items": { "value": 68.90, "currency": "BRL" },
    "otherFees": { "value": 8.00, "currency": "BRL" },
    "discount": { "value": 5.00, "currency": "BRL" },
    "orderAmount": { "value": 71.90, "currency": "BRL" }
  },
  "payments": {
    "prepaid": 71.90,
    "pending": 0,
    "methods": [
      {
        "value": 71.90,
        "currency": "BRL",
        "method": "PIX",
        "methodInfo": "PIX",
        "type": "ONLINE",
        "changeFor": null,
        "brand": null,
        "transaction": {
          "transactionId": "E18236120202609191402s0f3c9a1b2c",
          "authorizationCode": null,
          "acquirerDocument": null
        }
      }
    ]
  },
  "delivery": {
    "deliveryDateTime": null,
    "estimatedDeliveryDateTime": null,
    "deliveredBy": "MERCHANT",
    "deliveryAddress": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Pinheiros",
      "street": "Rua dos Pinheiros",
      "number": "1200",
      "postalCode": "05422-001",
      "complement": "Apto 42",
      "reference": "Portão azul, ao lado da farmácia",
      "formattedAddress": null,
      "coordinates": { "latitude": -23.566432, "longitude": -46.690178 }
    }
  },
  "takeout": null,
  "schedule": null,
  "extraInfo": "Tocar o interfone 42 | origem=SITE",
  "test": false
}

Conferência dos totais: items 55,90 + 13,00 = 68,90; orderAmount 68,90 + 8,00 (taxa) - 5,00 (desconto) = 71,90; prepaid 71,90 porque o PIX foi pago on-line.

Exemplo: pedido TAKEOUT agendado

Retirada agendada para as 19h30 (UTC 22:30), paga em dinheiro no balcão, com troco para 50.

GET /v1/orders/9b2e4f6a-1c3d-4e5f-8a7b-6c5d4e3f2a1b

{
  "id": "9b2e4f6a-1c3d-4e5f-8a7b-6c5d4e3f2a1b",
  "displayId": "1043",
  "type": "TAKEOUT",
  "orderTiming": "SCHEDULED",
  "createdAt": "2026-09-19T14:10:52Z",
  "preparationStartDateTime": "2026-09-19T22:30:00Z",
  "merchant": {
    "id": "7f3b2c1e-9d4a-4b8e-a1c6-2e5f8d9a0b1c",
    "name": "Pizzaria Bella Massa"
  },
  "customer": {
    "id": "b1d5f3a7-4c2e-4f8b-a0d6-8e3c9b2d1f4a",
    "name": "Rafael Lima",
    "phone": { "number": "11991234567", "extension": null },
    "documentNumber": "12345678909",
    "email": null,
    "ordersCountOnMerchant": null
  },
  "items": [
    {
      "id": "8a4b5c6d-7e8f-4a9b-8c0d-2e3f4a5b6c7d",
      "index": null,
      "name": "Combo Burger Clássico",
      "externalCode": "f5a6b7c8-d9e0-4f1a-8b2c-4d5e6f7a8b9c",
      "unit": null,
      "ean": null,
      "quantity": 1,
      "specialInstructions": "Sem cebola.",
      "unitPrice": { "value": 32.00, "currency": "BRL" },
      "optionsPrice": { "value": 4.00, "currency": "BRL" },
      "totalPrice": { "value": 36.00, "currency": "BRL" },
      "options": [
        {
          "id": "9b5c6d7e-8f9a-4b0c-9d1e-3f4a5b6c7d8e",
          "index": null,
          "name": "Bacon extra",
          "externalCode": "a6b7c8d9-e0f1-4a2b-9c3d-5e6f7a8b9c0d",
          "quantity": 1,
          "unit": null,
          "unitPrice": { "value": 4.00, "currency": "BRL" },
          "price": { "value": 4.00, "currency": "BRL" },
          "groupName": null
        }
      ]
    },
    {
      "id": "0c6d7e8f-9a0b-4c1d-8e2f-4a5b6c7d8e9f",
      "index": null,
      "name": "Batata frita média",
      "externalCode": "b7c8d9e0-f1a2-4b3c-8d4e-6f7a8b9c0d1e",
      "unit": null,
      "ean": null,
      "quantity": 1,
      "specialInstructions": null,
      "unitPrice": { "value": 9.00, "currency": "BRL" },
      "optionsPrice": { "value": 0, "currency": "BRL" },
      "totalPrice": { "value": 9.00, "currency": "BRL" },
      "options": []
    }
  ],
  "otherFees": null,
  "discounts": null,
  "total": {
    "items": { "value": 45.00, "currency": "BRL" },
    "otherFees": { "value": 0, "currency": "BRL" },
    "discount": { "value": 0, "currency": "BRL" },
    "orderAmount": { "value": 45.00, "currency": "BRL" }
  },
  "payments": {
    "prepaid": 0,
    "pending": 45.00,
    "methods": [
      {
        "value": 45.00,
        "currency": "BRL",
        "method": "CASH",
        "methodInfo": "Dinheiro",
        "type": "OFFLINE",
        "changeFor": 50.00,
        "brand": null,
        "transaction": null
      }
    ]
  },
  "delivery": null,
  "takeout": {
    "mode": "DEFAULT",
    "takeoutDateTime": "2026-09-19T22:30:00Z"
  },
  "schedule": {
    "scheduledDateTimeStart": "2026-09-19T22:30:00Z",
    "scheduledDateTimeEnd": null
  },
  "extraInfo": null,
  "test": true
}

Repare em três coisas: preparationStartDateTime, takeout.takeoutDateTime e schedule.scheduledDateTimeStart carregam o mesmo instante, porque o agendamento é decidido uma vez e alimenta os três; pending é 45,00 porque o pagamento é OFFLINE; e test é true, indicando um pedido de loja de teste.

Lendo o pedido com segurança

Use id como chave. displayId se repete ao longo do tempo.
Trate test: true de forma separada. O pedido é real na loja de teste, mas não deve entrar no seu faturamento.
Não some items[].unitPrice * quantity para chegar ao total: use totalPrice e total.orderAmount. Eles são os valores cobrados.
Um MODIFIED no feed significa que o pedido mudou: substitua a sua cópia inteira, não só a situação.
Guarde extraInfo como texto. O formato chave=valor é estável, mas os valores de origem e canal dependem do canal de origem.

Próximos passos

Loja e cardápio: de onde vêm externalCode e os grupos de opções.
Catálogo de eventos: quando buscar o pedido de novo.
Ações e idempotência: mover o pedido depois de lê-lo.

Estrutura do pedido

Nesta página