# Digital River coordinated returns

In [Digital River coordinated fulfillments](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments.md), you can use the [Fulfillment Returns API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/fulfillment-returns) to [request](#requesting-a-fulfillment-return) and [retrieve](#retrieving-a-fulfillment-return) returns. After you create a [fulfillment return](#a-fulfillment-return), you should monitor and respond to the [events it emits](#listening-for-fulfillment-return-events).

## Requesting a fulfillment return

When requesting a fulfillment return, you should first [ensure the items you want to return are in the correct state](#ensuring-the-correct-item-state). Once you've done that, you can [define and submit the return request](#defining-and-submitting-a-fulfillment-return).

### Ensuring the correct item state

Before providing customers the option to return an item, you should ensure that the item is in a [`shipped` state](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/global-fulfillments.md#line-item-level). Customers shouldn't be allowed to return `pending`, `backordered`, or `cancelled` items. You can obtain this information by [retrieving the upstream fulfillment order](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/global-fulfillments.md#retrieving-a-fulfillment-order) or [listening for fulfillment order events](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/global-fulfillments.md#listening-and-responding-to-fulfillment-order-events).

{% hint style="warning" %}
You may decide you want to build your integration so that customers have the [option to cancel](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/instructing-digital-to-cancel-items.md) `pending` and `backordered` items.
{% endhint %}

### Defining and submitting a fulfillment return

When customers indicate they want to return all or part of a [fulfillment order](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/global-fulfillments.md#a-fulfillment-order), submit a `POST /fulfillment-returns` request that specifies the items to return and in what quantity. More specifically, you need to provide us the [identifier of the fulfillment order](#fulfillment-order-identifier) these items are attached to, [data on the inventory items](#inventory-item-data) to return, and the [identifier of the upstream order](#order-identifier).

#### Fulfillment order identifier

The `fulfillmentOrderId` parameter is used to specify the [identifier of the upstream fulfillment order](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/global-fulfillments.md#unique-identifiers) associated with this return.

#### Inventory item data

For each item you want to return, you must provide the [identifier it was assigned in the upstream fulfillment order](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/global-fulfillments.md#unique-identifiers) and the `quantity` of that item to return.

#### Order identifier

In the request, you should also set `upstreamId` to the [identifier of the upstream order](/digital-river-api/order-management/creating-and-updating-an-order.md#unique-identifier). This allows you to retrieve this identifier from the payload of a [`fulfillment_return.accepted` event](#return-accepted-events) and use it when [issuing refunds](/digital-river-api/order-management/returns-and-refunds-1/refunds/issuing-refunds.md).

### Upstream data sent in a `POST` fulfillment return request

When defining a `POST /fulfillment-returns` request, you can retrieve the required data from the following upstream [Order ](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/orders/order-basics)and [Fulfillment Order](/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/global-fulfillments.md#a-fulfillment-order) resources.

| Upstream API       | Attribute    |       | Fulfillment Returns API          |
| ------------------ | ------------ | ----- | -------------------------------- |
| Fulfillment Orders | `id`         | **➔** | `fulfillmentOrderId`             |
| Fulfillment Orders | `items[].id` | **➔** | `items[].fulfillmentOrderItemId` |
| Orders             | `id`         | **➔** | `upstreamId`                     |

## A fulfillment return

Once you've successfully submitted a `POST/fulfillment-returns` request, you get back a fulfillment return with a unique `id` which you can use to later [retrieve the fulfillment return](#retrieving-a-fulfillment-return).

The object provides you with information on each [requested and accepted return item](#returned-items). A fulfillment return also contains enumerations that indicate its [state](#the-fulfillment-return-life-cycle) and [who initiated it](#return-initiator).

Once the [fulfiller approves the return](#return-approved-events), we also provide the [return address](#return-address) where the customer should ship the items.

### Returned items

The `items` array of a fulfillment return contains information on requested and accepted returns. For each item in this array, `quantity` is the number of items you requested to be returned. The `quantityAccepted` is how many items have been accepted for return by the fulfiller.

When `quantityAccepted` is less than `quantity`, then the fulfiller has not yet approved all products for return.

### The fulfillment return life cycle

A Digital River coordinated physical return has a defined lifecycle at both the [fulfillment return level](#fulfillment-return-level) and [line item](#line-item-level) level. Each stage of these lifecycles is represented by the `state` attribute.

#### Fulfillment return level

The `state` attribute at the fulfillment return level indicates where a [fulfillment return](#a-fulfillment-return) is in its lifecycle. The values for a successful fulfillment return (i.e., the happy path) are `created` > `pending` > `accepted`.

| (1) When the fulfillment return request...                                                           | (2) the state transitions to... |
| ---------------------------------------------------------------------------------------------------- | ------------------------------- |
| has been received by the fulfiller but they haven't approved or rejected it yet                      | `created`                       |
| has been approved by the fulfiller but the returned items haven't been received at the warehouse yet | `pending`                       |
| has been accepted by the fulfiller because the returned items have been received at the warehouse    | `accepted`                      |
| has been rejected by the fulfiller                                                                   | `rejected`                      |

#### Line item level

The `state` attribute at the item level indicates where a line item is in its return lifecycle. The values for a successfully returned line item (i.e., the happy path) are `pending` > `accepted`.

| (1) When the line item...                                                                                                               | (2) the state transitions to... |
| --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| identifier is sent in a successful`POST/fulfillment-returns` request but the product(s) is not yet approved for return by the fulfiller | `pending`                       |
| has been received by the fulfiller at the warehouse and the product(s) return is accepted                                               | `accepted`                      |
| return request is rejected by the fulfiller                                                                                             | `rejected`                      |

### Return initiator

The `type` attribute indicates who initiated the return. A `client` return is standard and is typically initiated by a customer through the storefront. A `warehouse` return is initiated when a shipment is refused.

### Return address

Once [a return request](#requesting-a-fulfillment-return) is approved by the fulfiller, we populate the `location` hash table. This data structure provides the address where a customer should return the products. To be notified of these approvals, you can subscribe to [`fulfillment_return.pending`](#return-approved-events) events.

## Monitoring and responding to fulfillment returns

Once you submit a `POST /fulfillment-returns` request, you can determine its status by [calling the API directly](#retrieving-a-fulfillment-return) or [listening for webhook events](#listening-for-fulfillment-return-events).

### Retrieving a fulfillment return

There are two methods in the [Fulfillment Returns API](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/fulfillment-returns) that can be used to retrieve fulfillment returns. You can [get a list of fulfillment returns](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/fulfillment-orders#fulfillment-orders) filtered by optional query parameters. You can also [get an individual fulfillment return](https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/fulfillment-returns#fulfillment-returns-id) by sending its unique identifier as a path parameter.

### Listening for fulfillment return events

You can [configure your webhooks](/digital-river-api/order-management/events-and-webhooks-1/webhooks/creating-a-webhook.md#step-3-create-webhooks) to listen for fulfillment return events. The `data.object` of every one of these [events](/digital-river-api/order-management/events-and-webhooks-1/events-1.md) consists of a [fulfillment return](#a-fulfillment-return).

#### Return created events

When you submit a successful `POST /fulfillment-returns` request, we send you a `fulfillment_return.created` event. This indicates that your return request has been created by Digital River but has not yet been approved or rejected by the fulfiller.

#### Return approved events

If the fulfiller approves the return request, we send you a `fulfillment_return.pending` event. You can use this event to determine [what items can be returned](#returned-items) and [where they can be sent](#return-address) and then convey this information to the customer.

#### Return accepted events

When the fulfiller notifies us that they've received and accepted the returned products, we send you a `fulfillment_return.accepted` event. If you don't want to reimburse customers until they have returned products, your integration should wait to receive this event before [issuing refunds](/digital-river-api/order-management/returns-and-refunds-1/refunds/issuing-refunds.md).

#### Return rejected events

A `fulfillment_return.rejected` event indicates the fulfiller has rejected the return.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/returns/digital-river-coordinated-returns.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.