Pular para o conteúdo principal

Aplicar um cupom a um pedido

POST 
/v1/orders/:id/coupon

Resgata um código de cupom em um pedido e o retorna com os totais recalculados.

Somente o code do cupom é aceito aqui — a moeda e o fuso horário sempre vêm da sua empresa.

Somente pedidos criados pela API podem ser alterados aqui. Um pedido feito na loja virtual, no POS ou em um food app pertence a esse canal e responde 422 order_not_modifiable.

Como o cupom se comporta no pedido

  • O desconto é aplicado imediatamente: total_discounts e total são recalculados e salvos quando esta chamada retorna, não quando o pedido é pago. Cobre o total retornado.
  • O status do pedido não é verificado: um cupom pode ser resgatado em qualquer ponto do ciclo de vida do pedido, então aplique-o antes de receber o pagamento.
  • Um cupom por pedido. Um segundo cupom responde 422 validation_failed. Um desconto manual adicionado por POST /v1/orders/{id}/discounts pode coexistir com um cupom.
  • O valor mínimo do cupom é comparado com o total do pedido, após qualquer desconto já existente no pedido.
  • O pedido deve ter um cliente associado (client); caso contrário a requisição falha com 422.
  • Se os itens mudarem depois, um cupom percentual é recalculado sobre o novo total de itens; um cupom de valor fixo mantém seu valor.
  • As regras de elegibilidade do cupom são as configuradas na promoção: tipo de serviço, datas de validade e agenda semanal (avaliadas no fuso horário da sua empresa), limite de uso, uma vez por cliente, apenas novos clientes e — para promoções restritas a produtos — ao menos um item correspondente no pedido.

Um cupom que existe mas não é elegível para este pedido — limite de uso atingido, uma vez por cliente, ou restrito a um tipo de serviço ou a novos clientes — responde 422 coupon_not_applicable com o motivo em detail. Um código de cupom desconhecido ou um pedido desconhecido ambos respondem um 404 not_found genérico.

Para remover um cupom, use DELETE /v1/orders/{id}/discounts/{discountId} com o id do desconto que o cupom criou. Removê-lo não devolve o resgate à contagem de uso do cupom.

Escopo necessário: orders:write

Request​

Responses​

O pedido com o cupom aplicado.