Update purchase order status

Sets the purchase order status directly.

No transition guard is applied: any status may transition to any other status, including backward (e.g. done → draft). This mirrors core behavior.

PUThttps://rest.boxhero-app.com/v1/purchase-orders/{order_id}/status

Autorisation

Authorizationstringobligatoire

En-tête d’authentification Bearer au format Bearer <token>, où <token> est votre jeton d’API.

Paramètres de chemin

order_idintegerminimum 0, maximum 2147483647obligatoire

Corps de la requête

statusstringobligatoire

Order status. Purchase and sales orders may also be draft.

Valeurs possiblesdraftconfirmedin-progressdone

revisionintegerminimum 0, maximum 9007199254740991

Latest observed revision. Omit to use the current revision.

Réponses

200The updated purchase order’s id.

idintegerminimum 0, maximum 2147483647obligatoire

Updated order id.

401Missing or invalid API token.

idstringobligatoire

Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.

typestringobligatoire

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

Valeurs possibles/errors/not-found/errors/invalid-request/errors/invalid-team-mode/errors/tokens/invalid/errors/tokens/required/errors/too-many-requests/errors/core/usage-limit-exceeded/errors/core/forbidden/errors/core/unhandled/errors/unhandled

titlestringobligatoire

Human-readable summary of the error, in English.

correlationIDstringobligatoire

Request correlation id (rq_ followed by 32 lowercase hex chars, no dashes — e.g. rq_01abf3...). Identical to the X-Correlation-Id response header. Pass an X-Correlation-Id request header to thread your trace through to ours.

instancestringobligatoire

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.

codestring

Sub-reason code surfaced from upstream BoxHero core (on core-mapped 4xx) or from the gateway itself (e.g. not-available-for-api-token on 403). Use this for fine-grained branching after dispatching on type.

errorsarray of object

Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.

Afficher les propriétés

patharray of string | numberobligatoire

messagestringobligatoire

404No purchase order with the given id was found in this team.

idstringobligatoire

Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.

typestringobligatoire

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringobligatoire

Human-readable summary of the error, in English.

correlationIDstringobligatoire

instancestringobligatoire

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.

codestring

errorsarray of object

Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.

Afficher les propriétés

patharray of string | numberobligatoire

messagestringobligatoire

409The supplied revision is stale.

idstringobligatoire

Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.

typestringobligatoire

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringobligatoire

Human-readable summary of the error, in English.

correlationIDstringobligatoire

instancestringobligatoire

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.

codestring

errorsarray of object

Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.

Afficher les propriétés

patharray of string | numberobligatoire

messagestringobligatoire

429Rate limit exceeded. Check RateLimit, Retry-After, and X-RateLimit-* response headers before retrying.

idstringobligatoire

Unique exception id (ex_ followed by 32 lowercase hex chars, no dashes — e.g. ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a). Quote this in support tickets so we can find the request in our logs.

typestringobligatoire

Stable, machine-readable error code (RFC 7807-style URI fragment). Branch your error handling on this, not on title.

titlestringobligatoire

Human-readable summary of the error, in English.

correlationIDstringobligatoire

instancestringobligatoire

Pointer to the specific failing resource (e.g. /items/12345). Path-only, no /v1 version prefix.

codestring

errorsarray of object

Field-level error details. Present on /errors/invalid-request (400) responses. Each entry locates a single failure via JSONPath-like path segments and a human-readable message.

Afficher les propriétés

patharray of string | numberobligatoire

messagestringobligatoire

Requête

curl --request PUT \
  --url 'https://rest.boxhero-app.com/v1/purchase-orders/{order_id}/status' \
  --header "Authorization: Bearer $BOXHERO_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "done",
    "revision": 3
  }'

const response = await fetch("https://rest.boxhero-app.com/v1/purchase-orders/{order_id}/status", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "status": "done",
    "revision": 3
  }),
});
const data = await response.json();

import os
import requests

response = requests.put(
    "https://rest.boxhero-app.com/v1/purchase-orders/{order_id}/status",
    headers={
        "Authorization": "Bearer " + os.environ["BOXHERO_API_TOKEN"],
    },
    json={
        "status": "done",
        "revision": 3,
    },
)
data = response.json()

PUT /v1/purchase-orders/{order_id}/status HTTP/1.1
Host: rest.boxhero-app.com
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "done",
  "revision": 3
}

Réponse

{
  "id": 90101
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/tokens/required",
  "title": "Missing API token. Provide a Bearer token in the Authorization header.",
  "example": "Bearer wqnot0dlysdg5vymubzi4kiv"
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/not-found",
  "title": "No purchase order with the given id was found in this team.",
  "instance": "/purchase-orders/12345/status"
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/invalid-request",
  "title": "The supplied revision is stale.",
  "instance": "/purchase-orders/12345/status"
}

{
  "id": "ex_8f5c0c8e-0e0a-4a3c-9b3f-4f2c4f6c8d2a",
  "correlationID": "01J9X8K9XZ4ZWV9T8MQ8B7H7C2",
  "type": "/errors/too-many-requests",
  "title": "Too many requests.",
  "instance": "/purchase-orders/12345/status",
  "retryAfter": 60
}