Cancelling a fulfillment order

In Digital River coordinated fulfillments, learn how to cancel fulfillment of physical products

In Digital River coordinated fulfillments, you can use the fulfillment cancellations API to cancel the delivery of inventory items. When you request a fulfillment cancellation, you must specify the items to cancel and in what quantity.

Your integration should also be set up to respond to fulfillment cancellation events.

Requesting a fulfillment cancellation

If your site allows customers to cancel purchases, before sending a create fulfillment cancellation request, you should ensure the items you want to cancel are in the correct state. Once you've done that, you can define and submit the cancellation request.

Ensuring the correct item state

Before you activate a cancellation option in your UI, check that the relevant items[] in the fulfillment order are either pending or backordered . Customers shouldn't be allowed to cancel shipped items. However, your integration can provide customers the option to return shipped items.

Defining and submitting a fulfillment cancellation request

When customers opt to cancel all or part of a fulfillment order, respond to their request by defining and submitting a POST /fulfillment-cancellations. The request needs to provide:

• The fulfillment order identifier

• The order identifier

• Data on the items that the customer wants to cancel

Fulfillment order identifier

A fulfillmentOrderId represents the identifier of the fulfillment order.

Fulfillment order		POST/fulfillment-cancellations
id	➔	fulfillmentOrderId

Order identifier

An upstreamId represents the identifier of the order. We recommend setting this value for tracking purposes and maintaining data consistency.

Order		POST/fulfillment-cancellations
id	➔	upstreamId

Item data

For each item a customer wants to cancel, provide its fulfillment order line item identifier assigned to it. You must also specify the quantity of that line item.

Fulfillment order		POST/fulfillment-cancellations
items[].id	➔	items[].fulfillmentOrderItemId

A fulfillment cancellation

A successful POST /fulfillment-cancellations returns a fulfillment cancellation.

You can use this resource to determine the state of the cancellation. Additionally, we provide the accepted quantity for each item you request to cancel.

A fulfillment cancellation also contains a unique id. You can use this identifier when responding to cancellation state change events and retrieving the fulfillment cancellation.

Items accepted for cancellation

In a fulfillment cancellation, each items[] provides the quantity you specified in the POST/fulfillment-cancellations as well as the quantityAccepted by the fulfiller. If quantityAccepted is less than quantity, then the fulfiller didn't approve all the items for cancellation.

The fulfillment cancellation life cycle

A fulfillment cancellation, as well as its items[], have a defined lifecycle, each stage of which is represented by a state.

We recommend that you monitor and respond to fulfillment cancellation state change events.

Fulfillment cancellation states

A fulfillment cancellation contains a state. It indicates where the resource 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) its state transitions to...
is created but not yet approved for cancellation by the fulfiller	pending
is approved for cancellation by the fulfiller	accepted
is rejected for cancellation by the fulfiller	rejected

Line item states

Eachitems[] in a fulfillment cancellation also contains a state. The state values of a successfully cancelled line item (i.e., the happy path) are pending > accepted.

(1) When the line item...	(2) its state transitions to...
is not yet approved for cancellation by the fulfiller	pending
is approved for cancellation by the fulfiller	accepted
is rejected for cancellation by the fulfiller	rejected

Handling fulfillment cancellation state change events

Your integration should be capable of responding to fulfillment cancellation state change events. You can also determine a fulfillment cancellation's state by calling the API directly.

Responding to cancellation events

You can configure your webhooks to listen for fulfillment cancellation created, approved, and rejected events. Each event's data.object consists of a fulfillment cancellation.

Fulfillment cancellation created events

When a POST /fulfillment-cancellations request is successfully submitted, we create a fulfillment_cancellation.created event. This event indicates that your cancellation request has been received by Digital River but has not yet been approved or rejected by the fulfiller.

Fulfillment cancellation approved events

If the fulfiller approves a cancellation request, we create a fulfillment_cancellation.accepted event that provides the quantity of items they accepted for cancellation.

In Digital River coordinated fulfillments that use the distributed model, you should respond to each fulfillment cancellation approved event by submitting a payment cancellation request through the Fulfillments API.

If you're using the orchestrated model, we listen for fulfillment cancellation-approved events and submit the appropriate payment cancellation request.

For more details, refer to Capturing and cancelling payment charges.

Fulfillment cancellation rejected events

A fulfillment_cancellation.rejected event indicates that the fulfiller has declined the cancellation request.

We recommend you respond to these events by notifying customers (typically through email and their order management page) that the cancellation request has been rejected. In the notification, you can provide customers instructions on returning physical products and requesting refunds.

Retrieving a fulfillment cancellation

Two requests can be used to retrieve fulfillment cancellations:

• You can get a specific fulfillment cancellation by sending its unique identifier.

• You can get a list of fulfillment cancellations filtered by optional query parameters.