Pular para o conteúdo principal

Pedidos

2026-09-18 — Promotions — criar, ler, atualizar e excluir uma promoção; aplicar um cupom a um pedido​

🆕 Novo

  • POST /v1/orders/{id}/coupon — Resgata um código de cupom em um pedido e o retorna com os totais recalculados. Somente pedidos criados pela API podem ser alterados aqui (422 order_not_modifiable caso contrário). Um cupom que existe mas não é elegível para esse pedido — tipo de atendimento, limite de uso atingido, uma vez por cliente, ou somente para novos clientes — responde 422 coupon_not_applicable; um cupom já aplicado ao pedido responde 422 validation_failed. Para remover um cupom, use o já existente DELETE /v1/orders/{id}/discounts/{discountId} com o id do desconto que o cupom criou.

Escopos​

  • orders:write — também obrigatório para POST /v1/orders/{id}/coupon (escopo existente, sem necessidade de nova concessão para chaves que já escrevem pedidos).

2026-09-16 — Pedidos — pagamentos em pedidos de loja virtual e PDV​

✨ Alterado

  • POST /v1/orders/:id/payments e DELETE /v1/orders/:id/payments/:paymentId agora também funcionam em pedidos feitos pelo cliente na loja virtual (INBOUND) ou registrados pelo estabelecimento no PDV (OUTBOUND), não somente em pedidos criados pela API. Pedidos de aplicativos de delivery continuam respondendo 422 order_not_modifiable. Todos os demais endpoints de escrita continuam aceitando somente pedidos criados pela API.

2026-09-12 — Pedidos — criar e atualizar pedidos​

🆕 Novo

  • POST /v1/orders — Cria um pedido. Envie service_type e, opcionalmente, client_id (um cliente existente da sua empresa). table_id só é aceito para pedidos TABLE; address_id e delivery_price somente para pedidos DELIVERY. source, country_code, timezone e currency são sempre obtidos da sua credencial. Por padrão o pedido começa como INITIATED, um rascunho que o estabelecimento não vê: adicione seus itens, pagamentos e descontos, depois confirme com PATCH /v1/orders/{id}/status e status: PENDING (ou PREPARING), o que atribui o número diário e o exibe ao estabelecimento. Envie status: PENDING na criação para pular o rascunho. Rascunhos nunca são retornados por GET /v1/orders: guarde o id da resposta de criação e leia-os com GET /v1/orders/{id}. Requer um header Idempotency-Key, armazenado como a referência do pedido e que deve ser único por pedido.
  • PATCH /v1/orders/{id} — Edita um pedido criado por você pela API. Envie ao menos um de comment, order_title, delivery_comment, delivery_price, packaging_price ou scheduled_delivery_date; delivery_comment e delivery_price só são aceitos em pedidos DELIVERY. comment é anexado ao que o pedido já tem, em vez de substituí-lo; currency é sempre obtida da sua credencial. Pedidos de outros canais não podem ser editados aqui.

2026-09-04 — Gestão de pedidos — itens, pagamentos, descontos, status e cancelamento​

🆕 Novo

  • PATCH /v1/orders/:id/status — Avança um pedido em seu ciclo de vida.
  • POST /v1/orders/:id/cancel — Cancela um pedido, com um motivo.
  • POST /v1/orders/:id/combos — Adiciona itens a um pedido existente.
  • DELETE /v1/orders/:id/combos/:comboId — Remove um item de um pedido.
  • POST /v1/orders/:id/payments — Registra um pagamento em um pedido.
  • DELETE /v1/orders/:id/payments/:paymentId — Cancela um pagamento.
  • POST /v1/orders/:id/discounts — Aplica um desconto manual.
  • DELETE /v1/orders/:id/discounts/:discountId — Remove um desconto.

Os oito endpoints retornam o pedido em seu novo estado, no mesmo formato de GET /v1/orders/:id.

Escopos​

  • orders:write — obrigatório para os oito endpoints. As API keys existentes precisam desse escopo concedido antes de chamá-los. Os endpoints de entregador continuam usando logistics:write.

Notas

  • Somente pedidos criados pela API podem ser editados.
  • Alterar o status é a exceção: funciona para pedidos de qualquer canal. Avançar um pedido que o estabelecimento já está preparando é uma ação operacional, independentemente de quem a realizou.
  • Os status só avançam, na ordem PENDING, PREPARING, READY, DELIVERED e FINALIZED. Enviar um status anterior ao atual deixa o pedido inalterado e o retorna como está; pular para frente aplica os status intermediários. CANCELLED não é aceito aqui — use o endpoint de cancelamento.
  • Um pedido com pagamentos ativos não pode ser cancelado. Cancele os pagamentos primeiro com DELETE /v1/orders/:id/payments/:paymentId.
  • Remover um item ou um pagamento o cancela: a linha permanece no pedido com canceled_at definido, para que a alteração permaneça auditável e continue aparecendo nos relatórios do estabelecimento. Remover um desconto o exclui.
  • Os itens não precisam existir no seu menu. Enviados sem product_id eles são adicionados como linhas livres; um sku que corresponda a um produto do seu menu vincula a linha a ele automaticamente.
  • Pode haver vários pagamentos por pedido, um por forma usada pelo cliente. O pedido é marcado como pago quando a soma atinge o total, e valores acima do total são aceitos e reportados como pagamento em excesso.
  • Os descontos são manuais, por AMOUNT ou PERCENTAGE, e se acumulam. Uma porcentagem acima de 100 é rejeitada; um valor acima de 100 não é.
  • A moeda e o fuso horário são obtidos da empresa proprietária da sua API key, então você nunca os envia.

Preços: você envia preços unitários, lê de volta totais da linha

Os campos do item têm os mesmos nomes na requisição e na resposta, mas não significam a mesma coisa. Você envia o custo de uma unidade; o pedido armazena o total da linha inteira:

variant_price          = unit price x item quantity
variant_original_price = unit list price x item quantity

per modifier:
  price    = unit price x modifier quantity x item quantity
  quantity = modifier quantity x item quantity

modifiers_price      = sum of the modifier prices
combo_price          = variant_price + modifiers_price
combo_original_price = variant_original_price + sum of original prices

A quantity de um modificador é por unidade do item. Pedir um acompanhamento grande em um item com quantity: 2 registra dois acompanhamentos grandes.

Por exemplo, enviando um item com quantity: 2, variant_price: 25 e variant_original_price: 30, mais um modificador com price: 4 e outro com price: 6, o pedido armazena variant_price: 50, os modificadores em 8 e 12, modifiers_price: 20 e combo_price: 70.

variant_original_price e o original_price de um modificador são opcionais: o padrão é o preço cobrado, então envie-os somente quando quiser que o pedido mostre o desconto concedido.

2026-08-14 — Logistics API — Provedores de entrega externos​

🆕 Novo

  • PUT /v1/orders/:id/rider — Atribui ou atualiza um entregador (nome, telefone).
  • DELETE /v1/orders/:id/rider — Remove o entregador de um pedido.
  • PATCH /v1/orders/:id/delivery-status — Atualiza o status de entrega. Define delivered_by como API automaticamente.

Escopos​

  • logistics:write — obrigatório para os três novos endpoints.

Notas

  • Esses endpoints permitem que provedores de entrega externos (ex.: PickNGo) reportem atribuição de entregador e progresso de entrega em pedidos já existentes.
  • Eles NÃO criam pedidos — só operam em pedidos já criados na OlaClick.
  • delivered_by é definido como API automaticamente para que os relatórios distingam entregas feitas via provedor.
  • As API keys existentes precisam do escopo logistics:write concedido antes de chamar esses endpoints.

2026-06-20 — Public API — Lançamento inicial​

🆕 Novo

Primeira versão da OlaClick Public API está no ar.

  • GET /v1/orders — Lista paginada de pedidos com filtros
  • GET /v1/orders/:id — Um único pedido pelo UUID ou ID público
  • GET /v1/orders/by-payment-methods — Pedidos agregados por forma de pagamento
  • GET /v1/orders/by-tips — Pedidos agregados por gorjetas
  • GET /v1/orders/products-sold — Estatísticas de produtos vendidos