Cancelling physical fulfillments

Learn how to cancel the physical fulfillment of inventory items.

When Digital River coordinates a physical fulfillment, you can use the Fulfillment Cancellations API to cancel the delivery of inventory items. When you submit a fulfillment cancellation request, you must specify the items to cancel and in what quantity.

Once this request is submitted, your integration should listen for and respond to fulfillment cancellation events. If you're notified that a cancellation is approved by the fulfiller, you can then use the Fulfillments API to submit a request to cancel the relevant part of the payment charge.

Requesting a fulfillment cancellation

When requesting a fulfillment cancellation, you should first ensure the items you want to cancel are in the correct state. Once you've done that, you can then define and submit the cancellation request.

Ensuring the correct item state

Before providing customers the option to cancel items, you should ensure that the items are either in a pending or backordered state. In other words, customers shouldn't be allowed to cancel shipped items.

You may decide you want to build your integration so that customers have the option to return shipped items.

Defining and submitting a fulfillment cancellation

When customers indicate they want to cancel all or part of a fulfillment order, submit a POST/fulfillment-cancellations request that specifies the items to cancel and in what quantity. More specifically, you need to provide us the identifier of the fulfillment order these items are attached to and data on the inventory items themselves.

For tracking purposes and to maintain data consistency, we also recommend you use the identifier of the upstream order as the upstreamId.

Fulfillment order identifier

The fulfillmentOrderId parameter is used to specify the identifier of the upstream fulfillment order associated with this cancellation.

Inventory item data

For each inventory item you want to cancel, you must provide the identifier it was assigned in the upstream fulfillment order and the quantity of that item to cancel.

Upstream data sent in a POST fulfillment cancellation request

When setting certain parameters in a POST/fulfillment-cancellations request, you can retrieve their values from the following order and fulfillment order resources.

Upstream API

Attribute

Fulfillment Cancellations API

Fulfillment Orders

id

fulfillmentOrderId

Fulfillment Orders

items[].id

items[].fulfillmentOrderItemId

Orders

id

upstreamId

A fulfillment cancellation

Once you've successfully submitted a POST/fulfillment_cancellations request, you get back a fulfillment cancellation with a unique id. You can use this identifier to later retrieve the fulfillment cancellation.

The object also contains an enumeration that indicates the state of the cancellation. Additionally, for each inventory item you cancel, we indicate how many cancellations the fulfiller has approved.

Cancelled items

The items array of a fulfilment cancellation contains the requested and accepted cancellations. For each item in this array, we return the quantity you specified in the original cancellation request as well as the quantityAccepted by the fulfiller.

When the quantityAccepted is less than the quantity, not all the products are approved for cancellation.

We also indicate where the item is in its cancellation lifecycle.

The fulfillment cancellation life cycle

A fulfillment cancellation has a defined lifecycle at both the order level and line item level. Each stage of that lifecycle is represented by the state attribute.

Order level

The state attribute at the order level indicates where a fulfillment cancellation is in its lifecycle. The values for a successful fulfillment cancellation (i.e., the happy path) are pending > accepted.

(1) When the fulfillment cancellation...

(2) the state transitions to...

is created but not yet approved for cancellation by the fulfiller

pending

is approved for cancellation by the fulfiller

accepted

is not approved for cancellation by the fulfiller

rejected

Line item level

The state attribute of a line item indicates where the object is in its fulfillment lifecycle. The values for a successfully cancelled line item (i.e., the happy path) are pending > accepted.

(1) When the line item...

(2) the state transitions to...

is included in a successfulPOST/fulfillment-cancellations request but not yet approved for cancellation by the fulfiller

pending

is approved for cancellation by the fulfiller

accepted

is not approved for cancellation by the fulfiller

rejected

Monitoring and responding to fulfillment cancellations

Once you have successfully submitted a POST/fulfillment-cancellations request, you can determine its status by either calling the API directly or listening for webhook events.

Retrieving a fulfillment cancellation

There are two methods in the Fulfillment Cancellations API that can be used to retrieve fulfillment cancellations. You can either get a list of fulfillment cancellations filtered by optional query parameters. Or you can get an individual fulfillment cancellation by sending its unique identifier as a path parameter.

Listening for cancellation events

You can configure your webhooks to listen for fulfillment cancellation events. The data.object of every one of these events consists of a fulfillment cancellation.

Cancellation created events

When you submit a successful POST/fulfillment-cancellations request, we send a fulfillment_cancellation.created event to your pre-configured webhook. This indicates that your cancel request has been created by Digital River but not yet approved or rejected by the fulfiller.

Cancellation approved events

If the fulfiller approves the cancellation request, we send you a fulfillment_cancellation.accepted event that contains information on the cancelled items.

Your integration should wait to receive this event before using the Fulfillments API to submit a POST/fulfillments request with a designated cancel quantity. By submitting this request, you're telling Digital River to cancel the relevant parts of the payment charge.

Cancellation rejected events

A fulfillment_cancellation.rejected event indicates the fulfiller has rejected the return.