# Cancelling a fulfillment order

In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments), you can use the [fulfillment cancellations API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations) to cancel the delivery of [inventory items](https://docs.digitalriver.com/digital-river-api/product-management/skus#inventory-items). When you [request a fulfillment cancellation](#requesting-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](#responding-to-cancellation-events).

## Requesting a fulfillment cancellation

If your site allows customers to cancel purchases, before sending a [create fulfillment cancellation request](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations#fulfillment-cancellations-1), you should [ensure the items you want to cancel are in the correct state](#ensuring-the-correct-item-state). Once you've done that, you can [define and submit the cancellation request](#defining-and-submitting-a-fulfillment-cancellation).

### Ensuring the correct item state

Before you activate a cancellation option in your UI, check that the relevant `items[]` in the [fulfillment order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) are either [`pending`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#the-fulfillment-order-life-cycle) or [`backordered`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#the-fulfillment-order-life-cycle) . Customers shouldn't be allowed to cancel [`shipped`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#the-fulfillment-order-life-cycle) items. However, your integration can provide customers the option to [return shipped items](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/returns/digital-river-coordinated-returns).

### Defining and submitting a fulfillment cancellation request <a href="#defining-and-submitting-a-fulfillment-cancellation" id="defining-and-submitting-a-fulfillment-cancellation"></a>

When customers opt to cancel all or part of a [fulfillment order](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#a-fulfillment-order), respond to their request by defining and submitting a [`POST /fulfillment-cancellations`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations). The request needs to provide:

* [The fulfillment order identifier](#fulfillment-order-identifier)
* [The order identifier](#order-identifier)
* [Data on the items that the customer wants to cancel](#inventory-item-data)

#### Fulfillment order identifier

A `fulfillmentOrderId` represents the [identifier of the fulfillment order](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#unique-identifiers).

| Fulfillment order |       | POST/fulfillment-cancellations |
| ----------------- | :---: | ------------------------------ |
| `id`              | **➔** | `fulfillmentOrderId`           |

#### Order identifier

An `upstreamId` represents the [identifier of the order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#unique-identifier). We recommend setting this value for tracking purposes and maintaining data consistency.

| Order |       | POST/fulfillment-cancellations |
| ----- | :---: | ------------------------------ |
| `id`  | **➔** | `upstreamId`                   |

#### Item data <a href="#inventory-item-data" id="inventory-item-data"></a>

For each item a customer wants to cancel, provide its [fulfillment order line item identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/global-fulfillments#unique-identifiers) 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`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations) returns a [fulfillment cancellation](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations).

You can use this resource to [determine the state of the cancellation](#the-fulfillment-cancellation-life-cycle). Additionally, we provide the [accepted quantity](#cancelled-items) for each item you request to cancel[.](#cancelled-items)

A fulfillment cancellation also contains a unique `id`. You can use this identifier when [responding to cancellation state change events](#monitoring-and-responding-to-fulfillment-cancellations) and [retrieving the fulfillment cancellation](#retrieving-a-fulfillment-cancellation).

### Items accepted for cancellation <a href="#cancelled-items" id="cancelled-items"></a>

In a [fulfillment cancellation](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations), 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](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations), as well as its `items[]`, have a defined lifecycle, each stage of which is represented by a `state`.

{% hint style="info" %}
We recommend that you [monitor and respond to fulfillment cancellation state change events](#monitoring-and-responding-to-fulfillment-cancellations).
{% endhint %}

#### Fulfillment cancellation states

A [fulfillment cancellation](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations) 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

Each`items[]`  in a [fulfillment cancellation](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations) 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 <a href="#monitoring-and-responding-to-fulfillment-cancellations" id="monitoring-and-responding-to-fulfillment-cancellations"></a>

Your integration should be capable of [responding to fulfillment cancellation state change events](#responding-to-cancellation-events). You can also determine a fulfillment cancellation's `state` by [calling the API directly](#retrieving-a-fulfillment-cancellation).

### Responding to cancellation events

You can [configure your webhooks](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/webhooks/creating-a-webhook#step-3-create-webhooks) to listen for fulfillment cancellation created, approved, and rejected events. Each [event's](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1) `data.object` consists of a [fulfillment cancellation](#a-fulfillment-cancellation).

#### Fulfillment cancellation created events

When a `POST /fulfillment-cancellations` request is successfully submitted, we create a `fulfillment_cancellation.created` [event](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1). 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](#cancelled-items).

In [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments) that use the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model), you should respond to each fulfillment cancellation approved event by submitting a payment cancellation request through the [Fulfillments API](#requesting-a-fulfillment-cancellation).

If you're using the [orchestrated model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#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](https://docs.digitalriver.com/digital-river-api/order-management/informing-digital-river-of-a-fulfillment).

#### 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](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/returns/digital-river-coordinated-returns) and [requesting refunds](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/refunds/issuing-refunds).

### Retrieving a fulfillment cancellation

Two requests can be used to [retrieve fulfillment cancellations](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations#fulfillment-cancellations):

* You can [get a specific fulfillment cancellation](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations#fulfillment-cancellations-id) by sending its unique identifier.
* You can [get a list of fulfillment cancellations](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations#fulfillment-cancellations) filtered by optional query parameters.