---
title: "Change PO State"
method: PATCH
path: "/v2/po/{poID}/state"
tags: ["Routes", "Purchase Orders", "State"]
---

# Change PO State

`PATCH /v2/po/{poID}/state`

Updates the state of the specified PO. 

Important Note: Currently POs can only move forward one state per state change request.

Parameters:

| Parameter | In | Type | Required | Default | Description |
| --- | --- | --- | --- | --- | --- |
| poID | path | integer | yes | | Purchase Order identifier |
| newState | body | string | yes | | All PO states: 0 (setup), 1–96 (custom), 97 (ready_to_receive), 98 (partially_received), 99 (fully_received), 100 (closed), 101 (disapproved). API accepts numbers, standard names, or custom_step_N |
| reason | body | string | no | | Optional note (max 500 chars) |

Responses:

- 200 OK: State changed.

- 400 Bad Request: Invalid transition or failed validation.

- 404 Not Found: PO not found.

Response data:

success | Boolean, if this operation was successful
state | JSON object describing current state.
previousState | JSON object describing previous state.
validNextStates | JSON object with a list of possible next states.

## Response `200`

200 OK

- object
  - `success` boolean
  - `message` string
  - `currentState` string

## Other responses

- `400` — The requested state transition is not allowed from the resource's current state.
- `401` — No `Authorization` header was provided on the request.
- `403` — The supplied credentials are invalid, the customer account is inactive, or the credentials do not have permission to perform this action.
- `404` — The referenced resource does not exist or is not visible to the authenticated customer.
- `409` — The request conflicts with the current state of the resource (e.g. a uniqueness constraint or a referenced parent that is in the wrong state).
- `429` — The per-minute or per-hour rate limit for this credential and method has been exhausted. Inspect the `X-RateLimit-*` headers to determine when to retry.
- `500` — An unhandled server-side error. The body message is generic (`System unavailable...`) when the underlying cause is a database fault; otherwise it reflects the raised error.

---

[API](https://skmtc.net/limblecmms/apis/limble-api-v2.md) · [All operations](https://skmtc.net/limblecmms/apis/limble-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/limblecmms/limble-api-v2/versions/20801e23f7f2/schema)