---
title: "Warehouse State Updates"
method: POST
path: "/2024-09/shipments/warehouse_state_updates"
tags: ["eFulfillment"]
---

# Warehouse State Updates

`POST /2024-09/shipments/warehouse_state_updates`

Update the warehouse state of one or multiple shipments.

Required authorization scope: `public.shipment:write`, `public.efulfillment:write`

> This endpoint is only available to eFulfillment clients with shipments fulfilled at one of Easyship's integrated warehouses.

> If a shipment contains the `metadata` object, it will persist unless you change existing keys or create new ones: in this case, corresponding keys will be updated or added.

The `warehouse_state` field has the following possible statuses:
<table>
  <tr>
    <th>warehouse_state</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>
      <code>created</code>
    </td>
    <td>
      An order has been created in the warehouse management system and is ready to be fulfilled.<br><br><i>Note:</i> This update is not needed if a success response is sent when Easyship sends the label callback.
    </td>
  </tr>
  <tr>
    <td>
      <code>failed</code>
    </td>
    <td>
      The order creation was rejected for an internal reason by the WMS. This can happen if the order information doesn't meet the WMS' requirements, or a product SKU is not defined in your WMS.<br><br>A message can be added using the message parameter. This will allow the client and Easyship to understand the reason for rejection.
    </td>
  </tr>
  <tr>
    <td>
      <code>packed</code>
    </td>
    <td>
      The order has been processed and packed and is waiting to be handed over to the courier
    </td>
  </tr>
  <tr>
    <td>
      <code>shipped</code>
    </td>
    <td>
      The order has been handed over to the courier and has left the warehouse.<br><br><i>Note:</i> This status update will trigger the following:
      <ul>
        <li>If the shipment was created through a store integration, Easyship will mark the order as "shipped" on the store</li>
        <li>If the company has the email notification option turned on, Easyship will send an email notification to the receiver, with the tracking number and the tracking page URL</li>
        <li>Easyship will start tracking the shipment, and update its status based on the courier's tracking events</li>
      </ul>
    </td>
  </tr>
  <tr>
    <td>
      <code>cancellation_requested</code>
    </td>
    <td>
      A cancellation request has been sent to the warehouse management system. It is awaiting confirmation by the warehouse.<br><br><i>Note:</i> This status is set by clients requesting a cancellation through the dashboard. It should not be set by a warehouse.
    </td>
  </tr>
  <tr>
    <td>
      <code>cancelled</code>
    </td>
    <td>
      The order has been cancelled in the warehouse management system.<br><br><i>Note:</i> This status update will trigger Easyship to cancel the shipment.
    </td>
  </tr>
  <tr>
    <td>
      <code>cancelled_no_stock</code>
    </td>
    <td>
     The order has been cancelled in the warehouse management system because the products are out of stock.<br><br><i>Note:</i> This status update will trigger Easyship to cancel the shipment.
    </td>
  </tr>
  <tr>
    <td>
      <code>backorder_no_stock</code>
    </td>
    <td>
      The order is set as backorder because of the products are out of stock. It may be packed and shipped at a later date.
    </td>
  </tr>
  <tr>
    <td>
      <code>returned</code>
    </td>
    <td>
      The package was returned by the courier or by the receiver, and received at the warehouse.
    </td>
  </tr>
</table>

## Request body

- ShipmentWarehouseStateUpdate — Data for updating shipments warehouse state
  - `shipments` ShipmentWarehouseState[]
    - `easyship_shipment_id` EasyshipShipmentId — unresolved $ref
    - `warehouse_state` 'created' | 'failed' | 'packed' | 'shipped' | 'cancelled' | 'cancelled_no_stock' | 'backorder_no_stock' | 'returned' — Warehouse state
    - `message` string — An message can be added if the status is `creation_failed` to explain the reason for rejection.
    - `metadata` object — Set of key-value pairs that you can attach to a shipment. This can be useful for storing additional information about the object in a structured format.

## Response `200`

shipment warehouse state successfully updated

- ShipmentWarehouseStateList — List of shipment warehouse states
  - `status` string
  - `shipments` ShipmentWarehouseStateResponse[]
    - `easyship_shipment_id` EasyshipShipmentId — unresolved $ref
    - `status` string
    - `errors` string[]
  - `meta` object
    - `status` string
    - `request_id` RequestId — unresolved $ref

## Other responses

- `202` — shipment warehouse state partially updated
- `422` — failure

---

[API](https://skmtc.net/easyship/apis/easyship-public-api.md) · [All operations](https://skmtc.net/easyship/apis/easyship-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/easyship/easyship-public-api/revisions/71d737a5fcbf/schema)