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:
Fulfillment order identifier
A fulfillmentOrderId represents the identifier of the fulfillment order.
id
âž”
fulfillmentOrderId
Order identifier
An upstreamId represents the identifier of the order. We recommend setting this value for tracking purposes and maintaining data consistency.
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.
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.
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.
Last updated