Cancelling orders

Overview

As a Convictional Seller, you may occasionally receive an order that you aren't able to fulfill. When this happens you should cancel the order so that your partner knows that the order won't be fulfilled. We'll show you a few different ways this can be done below. For more details see Cancel Order and Cancel Order Item.

Note: You cannot undo a cancellation. Also, any fulfilled quantities on an order will not be cancellable.

Cancel an order item

You can cancel a single order item by calling:

POST /orders/{order._id}/items/{item._id}/cancel

This will set a field on that item: item.cancelled=true, as well as a field on the order: order.hasCancellations=true. Both you and your partner will then be able to see that the item is cancelled and will not be fulfilled.

Cancel a partial order item

Supposing your partner orders a quantity greater than 1, you may not want to cancel the entire quantity, but rather just some of it. You can do this by adding the newQuantity field to the previous call:

POST /orders/{order._id}/items/{item._id}/cancel

{
    "newQuantity": <the amount you are able to fulfill>
}

This will have the same effect as before (setting item.cancelled=true and order.hasCancellations=true), but it will also attach a new order item to the order representing the newQuantity specified, and this new order item will not be cancelled.

Note: Partially cancelling an order item causes a new order item to be created. This means your system will need to be able to recognize this new item in order to use its item._id on future requests.

Cancel an entire order

You can cancel an entire order by calling:

POST /orders/{order._id}/cancel

The end result is the same as if you had cancelled each order item individually: each order item will have the field item.cancelled=true and the order will have the field order.hasCancellations=true.

Note: To see if a particular order is entirely cancelled, you must check each of the order items to see if they are all cancelled.

Cancel every order item left unfulfilled

If some of the items on the order are out of stock, you might find it simplest to fulfill what you can and then cancel the rest of the order afterwards. You can do this by adding the unfulfilledOnly field to the previous call:

POST /orders/{order._id}/cancel

{
    "unfulfilledOnly": true
}

This will cause all the order items that aren't already fulfilled to be cancelled. If an order item has been partially fulfilled then this will cancel the remaining quantity of that order item. If there are no fulfillments already on the order then providing unfulfilledOnly=true does not change any behavior.

Note: Supposing the order did have fulfillments then this order will now be set to order.shipped=true, since there are no remaining items left to fulfill (they have all been cancelled).