Change order

Change order is a feature that allows your store to modify the items or prices of an order. With this feature, the store can handle eventual changes in orders motivated by customer mistakes, product unavailability, and the inclusion of discounts, among other things. Learn more about how it works and its restrictions in the article Changing items from a completed order.

📘

Learn more about Order replacement and how to enable your customers to easily request order changes.

Implementation

The Register change on order endpoint in the Orders API allows you to create a discount, change an item or increase the price of an order.

🚧

When removing or adding items to an order, the inventory of the affected SKUs is not updated automatically - you should update it using the Logistics API.

Changes made this way can be confirmed by the changesAttachment field in the response of the Get order endpoint. Alternatively, you may search for the order in the Orders > Orders management > All orders section of your Admin panel and see the item change history in the order details.

❗️

Increasing the price of an order is only available for credit card purchases. The connector must also be able to handle purchases without the CVV, as well as duplicated sequences.

Errors

See below what API errors can be returned when attempting to change an order via API and how to avoid or work around them.

Request errors

These errors happen when there are one or more errors in the information sent in the request.

Error Description
The change value needs to be greater or equal than zero discountValue or incrementValue is smaller than 0.
Invalid change for order All of these conditions are true:
  • incrementValue is equal to discountValue.

  • itemsAdded is empty.

  • itemsRemoved is empty.

Invalid id for item The request body contains either an itemsAdded or itemsRemoved object, that has an empty id.
Field reason not set Empty reason field.

Restriction errors

These are errors that are returned when the request is correct but the order cannot be modified due to order change restrictions.

Error Description
Só é permitido registrar mudanças (change) quando o pedido estiver em manuseio: status = handling, waiting for fulfillment or ready for invoicing The fulfillment order is not in a status that allows changes (handling, waiting for fulfillment and ready-for-invoice).
Não é permitido fazer changes em pedidos de cadeia The order has a chain origin.
Só é permitido registrar uma mudança (change) quando o pedido estiver com o pagamento aprovado - status = payment-approved The marketplace order is not on the status payment-approved.
The value of the change exceed the order's price discountValue is greater than the total order price.
Impossible cancel order {0} - Payment not found Order is complete, but transaction id is empty or null.
Workflow not found for order {0} Order has workflowInstanceId empty or null.
Max allowed changes for order exceeded: {0} More than 50 registered change requests for a single order.
404 Not Found At least one of these conditions is true:
  • Removed item does not exist in the order.

  • Added item does not exist in the catalog.

Invalid quantity to remove from item {0} An item’s quantity would be reduced to less than 0 after the change.
It's not allowed to make changes in orders without a credit card payment, promissory card, cash or credit control All of these conditions are true:
  • Attempt to increase order price.

  • Payment method does not support value change.

  • Payment method is not credit card payment, promissory card, cash or credit control.

  • Consult with your payment gateway to see which methods allow for order value change.

    Change cannot be done. Possible reason: settlement directly done by API All of these conditions are true: - Attempt to reduce order price. - Payment method does not support value change.

    Consult with your payment gateway to see which methods allow for order value change.

    The value of the change exceed the order's price discountValue is greater than the amount allowed for the order transaction.
    500 Internal Server Error There is an issue with the payment gateway.

    Did this page help you?