Orders

Endpoints under /api2/order for paginated listings, detailed lookup by ID or increment_id, and administrative operations: cancel, hold and unhold. This page is the entry point of the orders family — from here, browse to Invoices, Shipments, Credit memos and Order history.

REST JSON Bearer Token New in 2026

Overview

The /api2/order family consolidates the order lifecycle on the Yep Platform — from initial lookup to final refund. This page covers the Orders root resource; the remaining resources have their own pages.

200

Max limitPer page across all listings.

Default limitWhen limit is missing or invalid.

Admin operationslist, get, cancel, hold, unhold.

opt

Metadatatotal, last_page, has_next with include_pagination=1.

InvoicesList, lookup, capture (full/partial) and resend email. ShipmentsCreate shipment with tracking, add tracks and resend email. Credit memosCreate credit memo from invoice or order, online or offline. Order historyList history, add comments and change order status.

Family rules

Conventions shared by every order endpoint. Base URL in examples: /api2. Protected endpoints require Authorization: Bearer {{token}} and Content-Type: application/json on POST verbs.

Listings accept filters either via query string or JSON body. When the same field exists in both places, the query-string value wins.
Default pagination: page=1, limit=20. Maximum: 200. Aliases page_size, per_page and pageSize are also accepted.
Dates must use YYYY-MM-DD or YYYY-MM-DD HH:MM:SS. Invalid dates return 400.
Sorting: use sort and direction (asc or desc). Accepted fields vary per resource.
On operational endpoints that accept items, every item must use order_item_id or sku and a positive qty.
Errors follow the {"error": "message"} shape.

HTTP statuses

Status	Usage
`200`	Lookup or update completed.
`201`	Invoice, shipment, track, history or credit memo created.
`400`	Invalid parameter, invalid JSON or operation ambiguity.
`401`	Missing or invalid token.
`404`	Order, invoice, shipment or credit memo not found.
`409`	Save conflict, duplicate or deadlock handled by the module helper.
`503`	Resource temporarily unavailable due to lock wait or DB contention.
`500`	Unexpected error handled by the module helper.

GET/api2/order

List orders with filters and deterministic pagination.

ListingFilters

page Optional

Current page. Default 1.

limit Optional

Records per page. Default 20, max 200.

include_pagination Optional

When 1, returns total, last_page and has_next.

status Optional

Single status, comma-separated list, or array in body. e.g. pending,processing.

state Optional

Single state, comma-separated list, or array in body.

increment_id Optional

Increment number. A single value returns the detailed order; comma-separated list or array works as a list filter.

customer_id Optional

Customer ID.

customer_email / email Optional

Customer email. Case-insensitive comparison.

store_id Optional

Store ID, for deterministic results in multi-store environments.

created_from / created_to Optional

Created-at range. Aliases: created_at_from, created_at_to, from, to.

updated_from / updated_to Optional

Updated-at range. Aliases: updated_at_from, updated_at_to.

sort, direction Optional

Accepted fields: entity_id, created_at, updated_at, increment_id, grand_total.

Example — query string

GET /api2/order?page=1&limit=50&status=pending,processing&include_pagination=1&sort=created_at&direction=desc
Authorization: Bearer {{token}}

Example — JSON body

{
  "page": 1,
  "limit": 50,
  "include_pagination": 1,
  "status": ["pending", "processing"],
  "customer_email": "customer@example.com",
  "created_from": "2026-01-01",
  "created_to": "2026-12-31",
  "sort": "created_at",
  "direction": "desc"
}

Sample response

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 137,
  "last_page": 3,
  "has_next": true,
  "orders": [
    {
      "order_id": 123,
      "increment_id": "100000123",
      "status": "processing",
      "state": "processing",
      "grand_total": 459.90,
      "customer_id": 34,
      "customer_email": "customer@example.com",
      "omnichat_sales_person_id": "seller-123",
      "omnichat_sales_person_name": "Salesperson name",
      "created_at": "2026-04-22 14:33:10",
      "updated_at": "2026-04-23 09:11:02"
    }
  ]
}

When the Omnichat integration is active on the store, orders that originated from Omnichat include omnichat_sales_person_id and omnichat_sales_person_name. For orders without an Omnichat link, both fields return null.

GET/api2/order

Get a single order by id or increment_id. The response uses the singular order key.

GET /api2/order?id=123
Authorization: Bearer {{token}}

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

A plural alias /api2/orders exists and accepts the same parameters.

POST/api2/order/cancel

Cancels the order following Yep's native rules. When canCancel() returns false, the API responds with 400.

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

{
  "order_increment_id": "100000123",
  "comment": "Canceled by integration."
}

Also accepts order_id instead of order_increment_id.

POST/api2/order/hold

Puts the order on hold when canHold() allows.

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

{
  "order_id": 123,
  "comment": "Order under review."
}

POST/api2/order/unhold

Removes the hold when canUnhold() allows.

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

{
  "order_id": 123,
  "comment": "Review completed."
}

Supported usage patterns

Tested and certified combinations for the Orders resource.

List open ordersGET /api2/order?status=pending,processing&include_pagination=1

Order by numberGET /api2/order?increment_id=100000123

Order by IDGET /api2/order?id=123

Incremental syncGET /api2/order?updated_from=2026-04-01&sort=updated_at&direction=asc

Cancel orderPOST /api2/order/cancel

Hold orderPOST /api2/order/hold

Unhold orderPOST /api2/order/unhold

Integration recommendations

Consolidated best practices for ERP, OMS, CRM and marketplace integrations syncing orders with the Yep Platform.

Identify orders preferentially by order_increment_id — it is stable and human-readable.
Use include_pagination=1 in sync routines to safely terminate loops via has_next.
Combine updated_from/updated_to for incremental (delta) syncs.
Use store_id in multi-store environments for deterministic results.

Avoid

Mixing order_id and order_increment_id in the same payload — pick a single identifier per request.
Forcing cancel/hold/unhold without checking the current state — Yep returns 400 when the transition is not allowed.
Relying on implicit ordering between pages — always pass sort and direction.

Incremental sync tip

For OMS/ERP integrations, combine updated_from + limit=100 + include_pagination=1 + sort=updated_at&direction=asc. You get a deterministic delta, a reliable stop condition and predictable ordering to resume from a checkpoint.

Common errors

Status	Sample body	When it happens
`400`	`{"error": "Invalid date format"}`	Dates outside `YYYY-MM-DD` or `YYYY-MM-DD HH:MM:SS`.
`400`	`{"error": "Order cannot be canceled"}`	`canCancel()`, `canHold()` or `canUnhold()` returned false for the current order state.
`401`	`{"error": "Unauthorized"}`	Missing `Authorization` or expired token.
`404`	`{"error": "Order not found"}`	Unknown `order_id` or `increment_id`.
`503`	`{"error": "Resource temporarily unavailable"}`	Lock wait or transient contention — retry with backoff.