Status & order history

Endpoints under /api2/history to change the order status (e.g. invoice_issued, shipped, awaiting_payment or any custom status) with automatic validation against configured Yep statuses, and list the full history with comments, transitions and system events.

REST JSON Bearer Token New in 2026

Overview

The history resource serves two complementary purposes: auditing (chronological view of what happened on the order) and orchestration (record comments and trigger status transitions from external systems such as ERP, OMS or WMS). For shared family rules (pagination, dates, HTTP statuses), see the main Orders page.

Identifiersorder_id, order_increment_id or increment_id.

opt

Status changestatus applies and records the transition.

Automatic emailThis route does not send customer emails.

No plural aliasUse /api2/history only.

GET/api2/history

List the order history. Identify the order with order_id, order_increment_id or increment_id.

By `order_id`

GET /api2/history?order_id=123
Authorization: Bearer {{token}}

By `order_increment_id`

GET /api2/history?order_increment_id=100000123
Authorization: Bearer {{token}}

By `increment_id` (alias)

GET /api2/history?increment_id=100000123
Authorization: Bearer {{token}}

By JSON body

{
  "order_id": 123
}

POST/api2/history

Create a history entry on the order. When status is provided, the entry is recorded and the order receives that status (validated against the configured statuses).

order_id / order_increment_id

Order identifier.

comment

History comment text.

status Optional

When provided, applies the status to the order. Validated against configured statuses.

is_customer_notified Optional

Only stores the flag in the history entry. This endpoint does not send emails to the customer.

is_visible_on_front Optional

Defines whether the comment shows up to the customer in the storefront.

Internal comment (no status change)

POST /api2/history
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_id": 123,
  "comment": "Comment created by API.",
  "is_customer_notified": false,
  "is_visible_on_front": false
}

Status change with visible comment

POST /api2/history
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "order_increment_id": "100000123",
  "comment": "Order sent to picking.",
  "status": "processing",
  "is_customer_notified": true,
  "is_visible_on_front": true
}

About `is_customer_notified`

This flag only marks the history entry as "customer notified" for reporting purposes. It does not send emails. To trigger customer communication, use POST /api2/invoice/email or POST /api2/shipment/email as appropriate.

There is no plural alias — use /api2/history only.

Supported usage patterns

Tested and certified combinations for the History resource.

History by IDGET /api2/history?order_id=123

History by numberGET /api2/history?order_increment_id=100000123

Internal commentPOST /api2/history + comment

Status changePOST /api2/history + status

Customer-visible commentPOST /api2/history + is_visible_on_front=true

Integration recommendations

Validate the status value against the Yep configuration before sending — only configured statuses are accepted.
Use is_visible_on_front=true only on comments that are genuinely relevant to the customer; keep internal logs with is_visible_on_front=false.
For WMS/OMS integrations, record significant transitions via POST /api2/history + status to build an audit trail.

Avoid

Expecting is_customer_notified=true to send emails — it only stores the flag.
Trying /api2/histories or /api2/historic — the resource is singular.
Changing status without a comment — auditing becomes harder to trace later.

Audit trail

For integrations that must justify transitions for internal audit or compliance, standardize the comment format: e.g. "[ERP-XYZ #1234] Status updated by sync job.". It eases later searches in the order history.

Common errors

Status	Sample body	When it happens
`400`	`{"error": "Invalid status"}`	`status` sent does not match any configured Yep status.
`400`	`{"error": "Comment is required"}`	Body without `comment`.
`401`	`{"error": "Unauthorized"}`	Missing `Authorization` or expired token.
`404`	`{"error": "Order not found"}`	Unknown `order_id` or `increment_id`.
`409`	`{"error": "Conflict on save"}`	Duplicate or deadlock on concurrent writes.