Order management apps fulfill orders on behalf of merchants. Apps can automate the fulfillment workflow, or merchants can directly fulfill orders through an app.

This guide describes what fulfillment orders are, the lifecycle of a fulfillment order, use cases for order management apps, and some considerations before you get started.

> Tip:
> If your app uses its own location, such as a third-party warehouse that prepares and ships orders on behalf of the store owner, then refer to [Fulfillment service apps](/docs/apps/build/orders-fulfillment/fulfillment-service-apps).

## How it works

After a customer places an order, a merchant or third-party fulfillment service needs to prepare the items to be delivered to the customer.

A fulfillment order represents the strategy for how an order will be fulfilled. Fulfillment orders are represented in the GraphQL Admin API by the [`FulfillmentOrder`](/docs/api/admin-graphql/latest/objects/fulfillmentorder) object.

The following diagram shows an example lifecycle of fulfilling an order using an order management app:

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/fulfillments/order-management-apps/lifecycle-343fdfd30f7f52431490d572e94ef468df63a5c147192cf900a2a6d711b26644.png" class="lazyload" alt="A diagram showing an example lifecycle of fulfilling an order using an order management app." width="100%" height="1444"></figure>


- **Customers** place orders, and receive items after the fulfillment process has completed.
- **Order management apps** query orders and inventory levels, and query supported fulfillment order actions that they can take on behalf of the merchant. For example, the app can create a fulfillment order and send a fulfillment request to a merchant or third-party fulfillment service to begin the order fulfillment process.
- **Merchants or third-party fulfillment services** approve the fulfillment request, pick and package the products, label the order for shipment, and ship the package with a mail carrier.

### API objects and relationships

Before you start building your order management app, we recommend familiarizing yourself with the following API objects and their relationships.

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/fulfillments/order-management-apps/fulfillment-order-api-objects-ad3d3389ae9de49a0a6f27163781aa3cd277e0f25bf6145232b12df2068ff80b.png" class="lazyload" alt="A diagram showing the relationships between fulfillment order API objects." width="80%" height="538"></figure>

| GraphQL Admin API object | Description |
|---|---|
| [`Order`](/docs/api/admin-graphql/latest/objects/Order) | Contains information about an order, including an array of the fulfillment orders which include line items that were purchased. |
| [`FulfillmentOrder`](/docs/api/admin-graphql/latest/objects/FulfillmentOrder) | An item or a group of items in an order that are to be fulfilled from the same location. There can be more than one fulfillment order for an order at a given location. |
| [`FulfillmentOrderLineItem`](/docs/api/admin-graphql/latest/objects/FulfillmentOrderLineItem) | A line item that belongs to a fulfillment order. It associates an order line item with quantities requiring fulfillment from the respective fulfillment order and any warning messages regarding the current fulfillment status. |
| [`Fulfillment`](/docs/api/admin-graphql/latest/objects/Fulfillment) | A shipment of one or more items in an order. It includes the line item that the fulfillment applies to, its tracking information, and the location of the fulfillment. |
| [`FulfillmentService`](/docs/api/admin-graphql/latest/objects/FulfillmentService)| A third-party warehousing service that prepares and ships orders on behalf of the store owner. Each fulfillment service is associated with its own location. When you create a fulfillment service, a new location is automatically created and associated with it. |
| [`Location`](/docs/api/admin-graphql/latest/objects/Location) | A geographical location where a line item can be fulfilled from. A fulfillment service always has its own location, and variants managed by the fulfillment service should always be fulfilled from that location. |


## Statuses

Each fulfillment order has a [status](/docs/api/admin-graphql/latest/enums/FulfillmentOrderStatus) and a [request status](/docs/api/admin-graphql/latest/enums/FulfillmentOrderRequestStatus). Similarly, each fulfillment has a [status](/docs/api/admin-graphql/latest/enums/FulfillmentStatus).

The following diagram shows how a fulfillment order's status and request status changes, and how a fulfillment's status changes, based on the GraphQL Admin API request that's executed:

<figure class="figure"><img src="https://cdn.shopify.com/shopifycloud/shopify_dev/assets/apps/fulfillments/statuses-ef2cff36c43604da4df7b612e9df62f7afcf37126c87b2c2d6944d677dc5bfcd.png" class="lazyload" alt="A diagram showing the transition of fulfillment order statuses and request statuses, and fulfillment statuses" width="100%" height="3175"></figure>


## Use cases

Common use cases for order management apps include the following:

- Helping merchants with advanced shipping workflows
- Automating the buying of shipping labels
- Reassigning inventory based on availability
- Rescheduling upcoming shipments for a different date

## Webhooks

The following table describes the fulfillment order webhooks that your app can subscribe to in API version 2023-01 and higher. For more information, refer to [the payloads for fulfillment order webhooks](/docs/apps/build/orders-fulfillment/order-management-apps/build-fulfillment-solutions#webhooks).

<table>
  <tr>
    <th>Webhook topic</th>
    <th>Description</th>
  </tr>
  <tr>
    <td><code>fulfillment_orders/order_routing_complete</code></td>
    <td>Occurs when a fulfillment order is created and the order routing has been completed for the order</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/fulfillment_request_submitted</code></td>
    <td>Occurs when a merchant requests one or more fulfilment order line items be fulfilled by a fulfilment service</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/fulfillment_request_accepted</code></td>
    <td>Occurs when a fulfillment service accepts a merchant's request to fulfill one or more fulfillment order line items</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/fulfillment_request_rejected</code></td>
    <td>Occurs when a fulfillment service rejects a merchant's request to fulfill an order</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/placed_on_hold</code></td>
    <td>Occurs when a fulfillment order is placed on hold</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/hold_released</code></td>
    <td>Occurs when a fulfillment order hold is released</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/scheduled_fulfillment_order_ready</code></td>
    <td>Occurs when a scheduled fulfillment order is ready to be fulfilled</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/rescheduled</code></td>
    <td>Occurs when a fulfillment order is rescheduled</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/cancellation_request_submitted</code></td>
    <td>Occurs when a merchant requests to cancel a fulfillment order after the request was accepted by a fulfillment service</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/cancellation_request_accepted</code></td>
    <td>Occurs when a fulfillment service accepts a fulfillment cancellation request from a merchant</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/cancellation_request_rejected</code></td>
    <td>Occurs when a fulfillment service rejects a fulfillment cancellation request from a merchant</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/cancelled</code></td>
    <td>Occurs when a fulfillment service or merchant cancels a fulfillment order</td>
  </tr>
  <tr>
    <td><code>fulfillment_orders/fulfillment_service_failed_to_complete</code></td>
    <td>Occurs when a fulfillment service intends to close an assigned fulfillment order that was previously accepted for fulfillment. After this action, the fulfillment order transitions to an incomplete status. To continue the fulfillment process, the merchant or app needs to determine the next course of action.</td>
  </tr>
</table>


## Migrating your app

In Shopify, the [`FulfillmentOrder`](/docs/api/admin-graphql/latest/objects/FulfillmentOrder) object models an end-to-end fulfillment process and is available in the GraphQL Admin API. The `FulfillmentOrder` object enables fulfillment data to sync accurately between Shopify and apps.

> Deprecated:
> By API version 2023-07, all apps should be using the [`FulfillmentOrder`](/docs/api/admin-graphql/latests/objects/FulfillmentOrder) object to manage fulfillments.
> Apps using the following GraphQL Admin API objects to fulfill orders are using a legacy workflow that is no longer supported as of API version 2022-07:
>
> - [`Order`](/docs/api/admin-graphql/latest/objects/Order)
> - [`Fulfillment`](/docs/api/admin-graphql/latest/objects/Fulfillment)


### Benefits

Migrating your app to the fulfillment orders workflow provides the following benefits:

- You can fetch the assigned location of a given group of unfulfilled line items to determine where fulfillment should occur.
- You no longer need to match SKUs or filter out the items on an order that don’t apply to you before you can determine which items you need to fulfill.
- App users and apps can both add notes to requests, which can improve communication throughout the fulfillment process.
- The process of making fulfillment and cancellation requests is formalized.


### Implementing recommended workflows

To learn how to migrate your app, refer to [Migrate to fulfillment orders](/docs/apps/build/orders-fulfillment/migrate-to-fulfillment-orders).

If you maintain a third-party app or Shopify Flow workflow that relies on `Order` and `Fulfillment` API resources for order automation, then refer to [Track orders placed through third-party marketplaces](/docs/apps/build/orders-fulfillment/order-management-apps/track-orders-other-platforms).


## Developer tools and resources

Explore the following developer tools and resources to learn more about fulfilling orders.

<div class="resource-card-grid">
  <div>
  <a class="resource-card" href="/docs/api/admin-graphql/latest/objects/FulfillmentOrder" data-theme-mode="">
    <div class="resource-card__indicator-container"><img
     src="/assets/resource-cards/graphql"
     data-alt-src="/assets/resource-cards/graphql-dark"
     aria-hidden="true"
     class="resource-card__icon themed-image"></div>
    <h3 class="resource-card__title">
      FulfillmentOrder object
    </h3>
    <p class="resource-card__description">Consult the GraphQL Admin API reference to learn more about the FulfillmentOrder object.</p>
  </a>
</div>
</div>


## Next steps

- Learn how to [manage fulfillments as an order management app](/docs/apps/build/orders-fulfillment/order-management-apps/build-fulfillment-solutions).
- [Edit existing orders](/docs/apps/build/orders-fulfillment/order-management-apps/edit-orders) using the GraphQL Admin API.