---
title: "Add an Order Status"
method: POST
path: "/order-statuses"
tags: ["Order Statuses"]
---

# Add an Order Status

`POST /order-statuses`

## Request

- Base URL: `https://api.smartroutes.io/v2`
- URL: `https://api.smartroutes.io/v2/order-statuses`
- Auth: none declared

Add a status to your organisation's catalogue. The status becomes available to every depot in your organisation and appears in the SmartRoutes web app.

The name is stored as you send it — surrounding whitespace is not trimmed. The response carries the name exactly as it will appear on orders; use that value when removing it later.

Adding a name your organisation already has, or one of the SmartRoutes defaults, returns `400`.

## Request body

- object
  - `status` string, required: The status name. Cannot be empty or whitespace only.

## Response `201`

The status is now available to your organisation.

- object
  - `order_status` OrderStatusOption: A status your organisation can apply to an order.
    - `status` string: The status name, exactly as it appears on an order. Use this value to remove the status via `DELETE /order-statuses/{status}`.
    - `is_custom` boolean: `true` for a status your organisation added. `false` for the SmartRoutes defaults every organisation has, which cannot be added or removed.

## Other responses

- `400`: Invalid input. The request body failed validation.
- `403`: Forbidden. Returned for rate-limit exhaustion (`name = FORBIDDEN`, with `details.retry_after_seconds` and `Retry-After` header) and permission gate failures (`name = PERMISSION`). Inspect `name` to disambiguate. Send `x-sr-api-features: rate-limit-429` to receive `429 RATE_LIMIT_EXCEEDED` for the rate-limit case instead, leaving `403` to mean permission failures only — see [API Features](#section/Getting-started/API-Features).
- `429`: Rate limit exceeded (`name = RATE_LIMIT_EXCEEDED`). **Only returned to callers that opt in** with the `x-sr-api-features: rate-limit-429` request header; without it the same condition returns `403` with `name = FORBIDDEN` and an otherwise identical body. See [API Features](#section/Getting-started/API-Features).
- `500`: An unexpected server error occurred. The body carries only `name` and `description`: internal details are never returned.

---

[API](https://skmtc.dev/smartroutes/apis/smartroutes-api.md) · [All operations](https://skmtc.dev/smartroutes/apis/smartroutes-api/llms.txt) · [OpenAPI document](https://skmtc.dev/smartroutes/apis/smartroutes-api/revisions/a7ea507afac7?raw)