> ## Documentation Index
> Fetch the complete documentation index at: https://api.basedock.us/llms.txt
> Use this file to discover all available pages before exploring further.

# Order Statuses: Reading, Writing, and Cancellations

> Learn how to read and set order statuses in Base.com, handle cancellations from marketplaces, and implement a safe two-way status sync pattern.

Statuses are fully user-defined in Base — every account names and numbers them differently. **Never hardcode status IDs without verifying them on the specific client account.** What is status `5` on one account may be "Shipped" on another and "Cancelled" on a third.

## Reading statuses

Retrieve the statuses configured on an account with these two methods:

* [`getOrderStatusList`](https://api.baselinker.com/index.php?method=getOrderStatusList) — returns the full list of statuses with their IDs, names, and colors.
* [`getOrderStatusGroups`](https://api.baselinker.com/index.php?method=getOrderStatusGroups) — returns status groups, which are a purely visual grouping used in the Base panel UI.

A status does nothing by itself. Its behavior — sending a tracking number to the customer, forwarding an invoice to a marketplace, triggering a warehouse pick — is defined via **Automatic Actions** and the settings of each specific integration (for example, *Integrations → Allegro → Order Statuses*). More on this mechanism in [Automation & Webhooks](/orders/automation-and-webhooks).

A typical baseline status setup looks like this:

| Status          | Purpose                                                                         |
| --------------- | ------------------------------------------------------------------------------- |
| *New Order*     | Neutral holding state, triggers nothing.                                        |
| *To Be Shipped* | Indicates the order is ready for the warehouse.                                 |
| *Shipped*       | Assigned when a tracking number is attached; may trigger customer notification. |
| *Delivered*     | Confirmed delivery.                                                             |
| *Cancelled*     | Order cancelled by customer or merchant.                                        |

Accounts that work with Alza Trade often add additional statuses such as *Cancelled by Alza* and *Rejected by Alza* — see the cancellations section below.

## Writing statuses

Three methods let you change or create statuses programmatically:

* [`setOrderStatus`](https://api.baselinker.com/index.php?method=setOrderStatus) — update the status of a single order.
* [`setOrderStatuses`](https://api.baselinker.com/index.php?method=setOrderStatuses) — bulk-update the status of multiple orders in one call.
* [`addOrderStatus`](https://api.baselinker.com/index.php?method=addOrderStatus) — create a new status programmatically. This is typically only needed during the initial integration setup, not in ongoing sync flows.

### Recommended pattern for two-way sync

A common mistake is writing a status back to Base on every change in your own system without checking what Base currently holds — this can race with a user who is editing the same order in the panel at the same time.

The recommended approach is:

1. Fetch the order's current state via [`getOrders`](https://api.baselinker.com/index.php?method=getOrders) (or from a recent cached copy).
2. Compare the current `order_status_id` in Base with the status you intend to write.
3. Only call `setOrderStatus` if the values differ.

This prevents redundant writes and avoids triggering Automatic Actions (which fire on every status change) for no reason.

## Cancelled orders

When a customer submits a cancellation request on a marketplace, that event reaches Base and needs to be reflected with the correct status. The mechanism for *catching* the cancellation event (an Automatic Action, `getJournalList`, or a webhook) is described in [Automation & Webhooks](/orders/automation-and-webhooks). This section focuses on **which status to set** once you have detected the cancellation.

For most channels the answer is straightforward: set the order to your *Cancelled* status. Alza Trade is a special case.

### Alza Trade: Cancelled vs. Rejected

Alza Trade distinguishes between two different cancellation outcomes depending on whether a shipping label has already been sent to Alza:

* **No label sent yet** — set the order to **Cancelled**. If a draft courier package exists, delete it first using [`deleteCourierPackage`](https://api.baselinker.com/index.php?method=deleteCourierPackage), then update the status.
* **Label already sent to Alza** (a Shipment Departure event has occurred) — set the order to **Rejected** instead. The same applies to shipments that were returned as unclaimed.

<Warning>
  If a shipping label has already been sent to Alza, **never delete it and never use the Cancelled status**. Always use **Rejected** in this scenario. Using the wrong status will cause a mismatch between Base and the Alza Trade system and can result in settlement errors.
</Warning>

## Complex status mappings

Non-trivial status mappings between Base and your ERP — for example, several Base statuses that all map to a single ERP status, or statuses that mean different things depending on the order source — should be fully planned before you go live. Getting the mapping wrong is much cheaper to fix before orders start flowing than after.