Orders

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.

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

Order items

Looking up an order also returns the list of items in the items key, inside the order object. Each item describes the purchased product, the quantities at each stage of the cycle (ordered, invoiced, shipped, refunded) and the amounts. Use order_item_id (or sku) as the item identifier in partial invoice, shipment and credit memo operations.

Response — order with items

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

{
  "success": true,
  "order": {
    "order_id": 123,
    "increment_id": "100000123",
    "status": "processing",
    "grand_total": 459.90,
    "customer_id": 34,
    "customer_email": "[email protected]",
    "items": [
      {
        "order_item_id": 1001,
        "product_id": 555,
        "sku": "CAM-AZUL-M",
        "name": "Blue T-shirt M",
        "product_type": "simple",
        "qty_ordered": 2,
        "qty_invoiced": 2,
        "qty_shipped": 0,
        "qty_refunded": 0,
        "qty_canceled": 0,
        "price": 199.95,
        "original_price": 229.95,
        "row_total": 399.90,
        "tax_amount": 0,
        "discount_amount": 60.00,
        "row_total_incl_tax": 399.90
      }
    ]
  }
}

Supported usage patterns

Tested and certified combinations for the Orders resource.

Integration recommendations

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

Recommended

• 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.

Common errors