# Managing a fulfillment order

A [fulfillment order](#a-fulfillment-order) manages the fulfillment of a transaction's [SKU-inventory item pairs](https://docs.digitalriver.com/digital-river-api/product-management/common-attributes). You only use this resource in [Digital River coordinated fulfillments](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments).

If you're using the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model), you must send a [create fulfillment order request](#creating-a-fulfillment-order) to initiate physical fulfillment.

Digital River submits this fulfillment order request if you use the [orchestrated model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#orchestrated-model).

You should subscribe to [events that occur during a fulfillment order's lifecycle](#listening-and-responding-to-fulfillment-order-events) in distributed and orchestrated models. These events notify you of (1) [pending shipments](#pending-events), (2)[ back-ordered products](#backordered-events), (3) [shipped products](#shipped-events), and (4) [product cancellations](#cancelled-events).

You can also use [shipments ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipments)to [track the progress of a delivery.](#tracking-a-shipment)

## Creating a fulfillment order

In the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model)**,** once you either [synchronously](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#accepted) or [asynchronously](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#listening-for-the-order-accepted-event) receive an [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders) in an [`accepted`](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#handling-accepted-orders) state, your integration should [handle the order state change event](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#handling-accepted-orders) by sending a create fulfillment order request. This [`POST /fulfillment-orders`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders#fulfillment-orders-1) request initiates the fulfillment of a transaction's [SKU-inventory item pairs](https://docs.digitalriver.com/digital-river-api/product-management/common-attributes).

{% hint style="success" %}
In the [orchestrated model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#orchestrated-model), we listen for an [`accepted` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events)order and handle this state change event by internally submitting a create fulfillment order request.
{% endhint %}

The following describes the request's required data and optional data:

{% hint style="info" %}
For a full list of specifications, refer to the [Fulfillment Orders APIs](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) reference documentation.
{% endhint %}

#### Required data

Every `POST/fulfillment-orders` request must include [currency](#currency), [created time](#upstream-order-time), [shipping address](#ship-to-address), [shipping method](#shipping-choices), and [product](#product-information) data.

This required data can be retrieved from an [order](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders) in an [`accepted` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events)state:

| Order in an `accepted` state  |       | `POST/fulfillment-orders` |
| ----------------------------- | ----- | ------------------------- |
| `currency`                    | **➔** | `currency`                |
| `createdTime`                 | **➔** | `upstreamOrderTime`       |
| `shipTo.country`              | **➔** | `shipTo.country`          |
| `shippingChoice.serviceLevel` | **➔** | `shippingChoice.id`       |
| `items[].skuId`               | **➔** | `items[].inventoryItemId` |
| `items[].quantity`            | **➔** | `items[].quantity`        |
| `items[].tax.amount`          | **➔** | `items[].tax.amount`      |

#### Optional data

In addition to other optional data, a `POST/fulfillment-orders` request accepts [product](#product-information), [customer](#customer-information), [ship to](#ship-to-address), upstream order identifier, and locale data. If you place a hold on products, [attach the reservation identifier](#attaching-a-reservation).

This optional data can be retrieved from an [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)in an [`accepted` ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders/order-basics#order-states-and-events)state:

| `items[].id`                    | **➔** | `items[].upstreamId`      |
| ------------------------------- | :---: | ------------------------- |
| `items[].amount`                | **➔** | `items[].total`           |
| `shipTo.name`or `billTo.name`   | **➔** | `name` or `shipTo.name`   |
| `shipTo.phone`or `billTo.phone` | **➔** | `phone` or `shipTo.phone` |
| `shipTo.email`or `billTo.email` | **➔** | `email` or `shipTo.email` |
| `shipTo`                        | **➔** | `shipTo`                  |
| `id`                            | **➔** | `upstreamId`              |
| `locale`                        | **➔** | `locale`                  |
| `checkoutId`                    | **➔** | `reservationId`           |

### Currency

The `currency` in the request should be the same as the value in the upstream [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders). This avoids creating downstream invoicing errors, issues with customs, and incorrect tax computations.

### Upstream order time

As with all [dates and times in the Digital River APIs](https://app.gitbook.com/s/ZrhMyLX5esFYS64lNWVW/digital-river-api-reference-guide/best-practices#dates-and-times), the `createdTime` of the upstream [order ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)is in [UTC](https://www.timeanddate.com/time/aboututc.html) and adheres to the [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) standard. You should not modify this date-time value before setting it `upstreamOrderTime` in a [fulfillment order](#creating-a-fulfillment-order).

```javascript
{
    "id": "186962110336",
    "createdTime": "2021-04-02T18:46:45Z",
    ...
}
```

### Customer information

You can set the customer's `name`, `email`, and `phone` at the fulfillment order level and within `shipTo`.

### Ship to address

The [fulfillment order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) `shipTo` values should be the same as the upstream [order's](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders) [`shipTo`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/providing-address-information#ship-to-address).

### Attaching a reservation

The [fulfillment order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) `reservationId` should reference the [reservation](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/reserving-inventory-items) used to place a hold on the products.

{% hint style="info" %}
When [creating a reservation](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/reserving-inventory-items#submitting-a-reservation-request), you should [set the reservation's identifier](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/reserving-inventory-items#unique-identifier) value to be the same as the [checkout's identifier](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts#checkout-identifier).
{% endhint %}

If the create fulfillment order request doesn't contain a `reservationId`, Digital River tries to allocate the specified inventory items. If we determine inventory levels are too low, what happens at that point depends on whether you [allow overselling of an item](https://docs.digitalriver.com/digital-river-api/product-management/common-attributes#allow-oversell) and whether your channel is set up to accept backorders.

### Shipping choices

When setting the [fulfillment order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) `shippingChoice.id`, you should use the [order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders) [`shippingChoice.serviceLevel`](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/shipping-choice#shipping-method) . This value maps to the [identifier of the shipping quote](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-shipping-quotes#unique-identifier-and-service-levels) selected by the customer.

| Shipping quote |       | Order                         |       | Fulfillment Order   |
| -------------- | ----- | ----------------------------- | ----- | ------------------- |
| `id`           | **➔** | `shippingChoice.serviceLevel` | **➔** | `shippingChoice.id` |

If you want to set the [fulfillment order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) `signatureRequiredType`, you'll need to persist with the [shipping quote](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-shipping-quotes#shipping-quotes) selected by the customer. You can then retrieve the [shipping quote's `signatureRequiredType`](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/using-shipping-quotes#signature-requirements) and use that value to set the fulfillment order's `signatureRequiredType`.

If the upstream [order](#creating-a-fulfillment-order) triggers the [landed cost feature](https://docs.digitalriver.com/digital-river-api/integration-options/creating-checkouts/landed-costs#how-landed-cost-is-represented), then set the fulfillment order's `dutiesPaid` to `true`. This notifies the shipping carrier that the customer has already paid the full landed cost, and they should invoice you for any duties paid.

### Product information

Use the [fulfillment order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) `items` array to specify product information. The [line items](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#line-items) must be retrieved from the upstream [order](https://www.digitalriver.com/docs/digital-river-api-reference/#operation/retrieveOrders). The same applies to most of a fulfillment order's optional product data.

For example, you can use `giftMessage` to send the downstream fulfiller a message that customers want included with the package. The `giftWrap` flag allows you to indicate whether the product should be wrapped.

## A fulfillment order

Once you successfully submit a `POST/fulfillment-orders` request, a [fulfillment order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) contains [unique identifiers](#unique-identifiers) needed for downstream processing. Additionally, we return attributes that inform you of a [fulfillment order's state](#the-fulfillment-order-life-cycle) and [categorize the status of its line items](#product-status-by-category).

### Unique identifiers

Once a [fulfillment order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) is created, we assign it a unique identifier and assign unique identifiers to each of [its line items](#product-information). You should persist all of these values.

You'll need the fulfillment order identifier to [retrieve the object](#retrieving-a-fulfillment-order).

When submitting [product cancellation](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/instructing-digital-to-cancel-items) and [return requests](https://docs.digitalriver.com/digital-river-api/order-management/returns-and-refunds-1/returns/digital-river-coordinated-returns), you must provide the fulfillment order identifier and the relevant line item identifiers.

In the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model), you can retrieve these identifiers from the `201 Created` response to a [`POST /fulfillment-orders`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) request.

In the [orchestrated model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#orchestrated-model), you can retrieve these identifiers by listening for the [`fulfillment_order.pending` ](#pending-events)event.

### The fulfillment order life cycle

You should be aware of both the [fulfillment order's lifecycle](#fulfillment-order-level) and the[ fulfillment order's line item's lifecycle](#line-item-level). In both, each stage of the lifecycle is represented by a `state`.

#### Fulfillment order level

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

| (1) When the fulfillment order...                         | (2) its `state` transitions to... |
| --------------------------------------------------------- | --------------------------------- |
| is created but not yet partially or fully shipped         | `pending`                         |
| partially or fully ships                                  | `shipped`                         |
| is cancelled by the customer, the client or the fulfiller | `cancelled`                       |

#### Line item level

The line item `state` attribute indicates where a [fulfillment order](#a-fulfillment-order)'s line item is in its lifecycle. The values for a successfully fulfilled line item (i.e., the happy path) are `pending` > `shipped`.

| (1) When the line item...                                                                                                                                          | (2) its `state` transitions to... |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| has not yet partially or fully shipped                                                                                                                             | `pending`                         |
| is configured to [allow oversell](https://docs.digitalriver.com/digital-river-api/product-management/managing-inventory#allow-oversell) and is awaiting restocking | `backordered`                     |
| partially or fully ships                                                                                                                                           | `shipped`                         |
| is cancelled by the customer, the client or the fulfiller                                                                                                          | `cancelled`                       |

### Product status by category

Each element of [fulfillment order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) `items` array indicates how many items are `pending`, `backordered`, `shipped`, `cancelled`, and `returned`. In aggregate, these values equal the total `quantity` of that line item, representing the amount originally purchased by the customer.

## Monitoring and responding to a fulfillment order

You can determine a [fulfillment order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) [`state`](#the-fulfillment-order-life-cycle) by either [calling the API](#retrieving-a-fulfillment-order) or [listening for webhook events](#listening-and-responding-to-fulfillment-order-events).

### Retrieving a fulfillment order

There are two methods you can use in the [Fulfillment Orders API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders) to retrieve fulfillment orders. You can [get a list of fulfillment orders](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders#fulfillment-orders) filtered by optional query parameters. You can also [get an individual fulfillment order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-orders#fulfillment-orders-id) by including its unique identifier as a path parameter in the request.

### Listening and responding to fulfillment order events

We recommend you respond to a [fulfillment order's](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Fulfillment-Orders) [`state`](#the-fulfillment-order-life-cycle) changes by listening for the [pending](#pending-events), [backordered](#backordered-events), [shipped](#shipped-events), and [cancelled](#cancelled-events) events.

In all of these events, `data.object` contains the unique identifier of:

* The[ fulfillment order and each of its line items](#unique-identifiers)
* The [upstream order](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#unique-identifier) and each of [its line items](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#line-items)
* Each line item's [SKU-inventory item pair](https://docs.digitalriver.com/digital-river-api/product-management/common-attributes#unique-identifier).

#### Fulfillment order pending events <a href="#pending-events" id="pending-events"></a>

When Digital River queues a fulfillment order for creation, we create a `fulfillment_order.pending` event. The event's `data.object` is a [fulfillment order](#a-fulfillment-order) in a [`pending`](#the-fulfillment-order-life-cycle) state.

In the [orchestrated model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#orchestrated-model), use this event to retrieve and save the fulfillment order's and each line item's identifiers.

{% hint style="info" %}
A [`pending`](#the-fulfillment-order-life-cycle) fulfillment order doesn't necessarily mean that all of its line items are also [`pending`](#the-fulfillment-order-life-cycle). A line item can be `pending`, `shipped`, `backordered` or `cancelled` while the fulfillment order is still `pending`.
{% endhint %}

#### Fulfillment order back-ordered events <a href="#backordered-events" id="backordered-events"></a>

Upon receiving a back-ordered notification from your channel's designated fulfiller, Digital River sends you a `fulfillment_order.backordered` event. The event's `data.object` contains an array of back-ordered `items`.

For each product in the `items` array, we provide an estimated `availableTime` (assuming the fulfiller sends us this information). We also specify the original `ordered` quantity as well as the quantity of `backOrdered` items that triggered the event.

The `totalBackordered` is the aggregated `backOrdered` quantity from all the back-ordered events. When processing duplicate back-ordered events, you can use this value as a checksum, ensuring your system does not exceed the total `ordered` amount.

You can use the `fulfillment_order.backordered` event as a trigger to send a delayed order notification (typically an email) to the customer. We recommend providing a link directing customers to their order management page in the email.

On this page, you should allow customers to cancel the order fully or partially. If they select either option, make sure you respond to this event by submitting a [create fulfillment cancellation request](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/instructing-digital-to-cancel-items).

{% tabs %}
{% tab title="fulfillment\_order.backordered" %}

```javascript
{
    "id": "evt_e381g2ff-7d42-3b05-91d5-e711443r3521",
    ...
    "data": {
        "object": {
            ...
            "items": [
                {
                    ...
                    "ordered": 6,
                    "backordered": 2,
                    "totalBackordered": 3,
                    "availableTime": 2020-11-25T20:36:00Z,
                    ...
                }
            ],
            ...
        },
        "previousAttributes": {}
    },
    ...
    "type": "fulfillment_order.backordered"
}
```

{% endtab %}
{% endtabs %}

#### Fulfillment order shipped events <a href="#shipped-events" id="shipped-events"></a>

Once Digital River receives a shipped notification from your channel's designated fulfiller, we create an [event ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/events)with a [`type`](https://docs.digitalriver.com/digital-river-api/order-management/events-and-webhooks-1/events-1#event-types) of `fulfillment_order.shipped`. Its `data.object` consists of a [shipment](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipments). To [track a shipment's progress](#tracking-a-shipment), persist `data.object.id`, which represents the shipment's identifier.

In the event's payload, `fulfillmentOrderUpstreamId` represents the [order's](#creating-a-fulfillment-order) `id` and each `items[].fulfillmentOrderItemUpstreamId` maps to an `items[].id` in that [order](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders).

{% tabs %}
{% tab title="fulfillment\_order.shipped" %}

```javascript
{
    "id": "evt_d290f1ee-6c54-4b01-90e6-d701748f0851",
    ...
    "data": {
        "object": {
            "id": "29016544906",
            ...
            "fulfillmentOrderId": "5774321009",
            "fulfillmentOrderUpstreamId": "9292981838",
            ...
            "items": [
                {
                    "id": "8760948870",
                    "fulfillmentOrderItemId": "650398674428",
                    "fulfillmentOrderItemUpstreamId": "650398674428",
                    ...
                    "quantity": 1,
                    ...
                }
            ],
            ...
        },
        "previousAttributes": {}
    },
    ...
    "type": "fulfillment_order.shipped"
}
```

{% endtab %}
{% endtabs %}

In the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model), respond to this event by sending a [`POST /fulfillments`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillments#fulfillments-1) request, which captures the appropriate amount of an [order's](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders) payment  [charges](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics).

The following table lists the data to retrieve from the event and then pass in a `POST /fulfillments`.

| Event                                    |       | `POST /fulfillments`     |
| ---------------------------------------- | ----- | ------------------------ |
| `data.object.id`                         | **➔** | `shipmentId`             |
| `items[].id`                             | **➔** | `items[].shipmentItemId` |
| `fulfillmentOrderUpstreamId`             | **➔** | `orderId`                |
| `items[].fulfillmentOrderItemUpstreamId` | **➔** | `items[].itemId`         |
| `items[].quantity`                       | **➔** | `items[].quantity`       |

#### Fulfillment order cancelled events <a href="#cancelled-events" id="cancelled-events"></a>

Whenever a fulfillment order is fully or partially cancelled, we send you a `fulfillment_order.cancelled` event.

The source of these events is  [`POST /fulfillment-cancellations`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillment-cancellations#fulfillment-cancellations-1) requests that your system submits or cancellation notifications sent by the product's fulfiller. The event's `data.object` is a [fulfillment order](#a-fulfillment-order) in a `cancelled` state.

The event's payload, `upstreamId` represents the [order's](#creating-a-fulfillment-order) [unique identifier](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#unique-identifier) and `items[].upstreamId` represents a [line item's identifier](https://docs.digitalriver.com/digital-river-api/order-management/creating-and-updating-an-order#line-items) in an [order](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Orders).

In the [distributed model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#distributed-model), *every time* you receive `fulfillment_order.cancelled`, retrieve data from the event and send it in a [`POST /fulfillments`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/fulfillments) request. This request instructs Digital River to [cancel](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges/charge-basics#cancels) the appropriate amount of an [order's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/orders)payment [charges](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/charges).

{% hint style="success" %}
In the [orchestrated model](https://docs.digitalriver.com/digital-river-api/integration-options/checkouts/handling-digital-river-coordinated-fulfillments/..#orchestrated-model), we listen for the cancelled event and respond by submitting an internal payment cancel request.
{% endhint %}

The following table lists the data you must retrieve from each `fulfillment_order.cancelled` event and then pass in a `POST/fulfillments`.

| `fulfillment_order.cancelled` event |       | `POST/fulfillments`      |
| ----------------------------------- | ----- | ------------------------ |
| `upstreamId`                        | **➔** | `orderId`                |
| `items[].upstreamId`                | **➔** | `items[].itemId`         |
| `items[].cancelled`                 | **➔** | `items[].cancelQuantity` |

## Tracking a shipment

A [fulfillment order's ](#a-fulfillment-order)products can be delivered to the end customer in one or more shipments, each represented by the [shipment resource](https://www.digitalriver.com/docs/digital-river-api-reference/#tag/Shipments).

You can use the unique shipment identifier you receive in a [`fulfillment_order.shipped`](#shipped-events) event to [submit queries](#querying-the-shipments-api) that return a [shipment's contents](#determining-the-contents-of-a-shipment) and provide [tracking information](#monitoring-the-progress-of-a-shipment).

### Querying the Shipments API

There are two methods for querying the [shipments API](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipments). You can retrieve an individual shipment by sending its unique identifier as a path parameter in a [`GET /shipments/{id}`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipments#shipments-id) request. You can also submit a [`GET /shipments`](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipments#shipments) request to retrieve a list of shipments and use optional query parameters to filter the results.

### Determining the contents of a shipment

A [shipment's ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipments)`items` array returns each shipment item's unique identifier, and the item's shipped `quantity`. All the relevant upstream identifiers of the item are also included.

Additionally, when the shipped item is a smartphone or cellphone, the downstream fulfiller may pass back to you `unitAttributes` that help identify and track the device. These attributes consist of a serial, [IMEI](https://en.wikipedia.org/wiki/International_Mobile_Equipment_Identity), or [SIM](https://en.wikipedia.org/wiki/SIM_card) card number

### Monitoring the progress of a shipment

A [shipment ](https://app.gitbook.com/s/x8fSFzVR3sg0TsNWwwVz/shipments)provides numerous data points that you can use to track a delivery's progress.

For the entire shipment, we provide you a `trackingUrl` that directs customers to a page where they can enter the `trackingNumber` provided by the `trackingCompany`.

At the shipment item level, we also give you a `trackingUrl` that directs customers to a page where they can enter the item's `trackingNumber` and monitor the delivery progress of specific products.