> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.bglobale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Status Updates (from Merchant)

> Cancel an order with a reason, or move an order to a processing status, via the UpdateOrderStatus API.

## UpdateOrderStatus

The UpdateOrderStatus API lets you:

* Cancel an order with a reason (and notify the customer accordingly)
* Move an order to a processing status (used by Global‑e or specific cases not covered in this guide)

Based on this description, this guide focuses on cancelling orders prior to dispatch.

## Prerequisites

The **following attributes are required** in the system (OMS/ERP/MW) when executing the calls:

* Global‑e order number (and not ecommerce platform or another system)
* Status and reasons codes mapped on the Global‑e side (for example, for cancellation reasons)

<div className="api-ref-card">
  <Card title="Update Order Status — reference & playground" icon="code" href="/api-reference/update-order-status">
    The `orderStatus` query parameter, the `ResponseInfo` response class, response examples, and the interactive playground for `POST /Order/UpdateOrderStatus`.
  </Card>
</div>

## Request

The whole payload is passed as a **single query-string parameter**, `orderStatus`, whose value is a URL-encoded, JSON-serialized object — there is **no request body**:

```
POST /Order/UpdateOrderStatus?orderStatus={ ...the object below, URL-encoded... }
```

Only `OrderId` is required; the other fields are optional.

### `orderStatus` object

| Field                     | Type                       | Description                                                                                                                                                     |
| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OrderId`                 | String                     | Global‑e order unique identifier (previously submitted to the Merchant's SendOrderToMerchant method when the order had been created with the Global‑e checkout) |
| `OrderStatus`             | Object (OrderStatus)       | The order status                                                                                                                                                |
| `OrderStatusReason`       | Object (OrderStatusReason) | Reason for the order status                                                                                                                                     |
| `ConfirmationNumber`      | String                     | Merchant's Order confirmation number                                                                                                                            |
| `DeliveryReferenceNumber` | String                     | Merchant's internal Delivery Reference Number for this order                                                                                                    |
| `OrderComments`           | String                     | Merchant's comments for the order                                                                                                                               |
| `TrackingNumber`          | String                     | Reference number valid for the tracking service used by the Merchant for this order                                                                             |
| `TrackingServiceName`     | String                     | Name of the tracking service used by the Merchant for this order                                                                                                |
| `TrackingServiceSite`     | String                     | URL of the tracking service site used by the Merchant for this order                                                                                            |
| `TrackingURL`             | String                     | Full tracking URL on the tracking service site used by the Merchant (if specified overrides all other "Tracking…" properties)                                   |

### `OrderStatus` object

| Field             | Type   | Description                                                                               |
| ----------------- | ------ | ----------------------------------------------------------------------------------------- |
| `Name`            | String | Order status name                                                                         |
| `OrderStatusCode` | String | Code denoting the order status on the Merchant's site (to be mapped on the Global‑e side) |

### `OrderStatusReason` object

| Field                   | Type   | Description                                                                                      |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `Name`                  | String | Order status reason name                                                                         |
| `OrderStatusReasonCode` | String | Code denoting the order status reason on the Merchant's site (to be mapped on the Global‑e side) |

## Use Cases

### Cancel an order prior to dispatch

Send the Global‑e `OrderId`, the target `OrderStatus`, and an `OrderStatusReason` describing why the order is being cancelled. The reason must be mapped on the Global‑e side so the appropriate notification can be sent to the customer.

```json theme={null}
{
    "OrderId": "GE1235436GB",
    "OrderStatus": {
        "OrderStatusCode": "cancelled",
        "Name": "cancelled"
    },
    "OrderStatusReason": {
        "OrderStatusReasonCode": "1010",
        "Name": "CustomerCancel"
    }
}
```

The full request and response classes, along with success and failure response examples, are rendered on the [API Reference page](/api-reference/update-order-status).

## Order Status Reasons

<Note>
  **Reasons (in addition to statuses) must be mapped in the Global‑e configuration so that appropriate notifications can be sent to the customer.**
</Note>

Possible cancellation reasons:

* Cancellation because of out-of-stock
* Cancellation at the customer's request
* Cancellation for technical reasons (default in case of no reason mapping declared)