# List orders

Paged list of the supplier's orders, newest first, with a reduced projection of each order and its lines
(`Order_Items` carry `id`, `item_no`, `qty`, `note` and the item's `id`, `name`, `sku`).
**API key and secret only.** Requests without `x-apiKey` / `x-apiSecret` are rejected with a plain-text `400`.

Endpoint: GET /v1/orders
Version: 1.19
Security: ApiKey, ApiSecret

## Security:

  - `ApiKey` (unknown)
    apiKey in header x-apiKey

  - `ApiSecret` (unknown)
    apiKey in header x-apiSecret

## Query parameters:

  - `limit` (integer)
    Number of rows per page.

  - `offset` (integer)
    Zero-based **page number**. The server skips `offset * limit` rows.

  - `from_updated_at` (string)
    Return only orders updated at or after this UTC timestamp (`YYYY-MM-DD HH:mm:ss` or ISO-8601).

  - `name` (string)
    Filter by order number (contains match).

  - `guid` (string)
    Return the single order with this GUID.

## Response 200:

  - `200` (unknown)
    A page of orders.

## Response 200 fields (application/json):

  - `orders` (array, required)

  - `orders.id` (integer)

  - `orders.guid` (string)

  - `orders.name` (string)
    Order number as displayed, e.g. `ABC-10000`.

  - `orders.api_guid` (string)
    Client-supplied idempotency key, when the order was created through the API.

  - `orders.supplier_id` (integer)

  - `orders.vendor_id` (integer)

  - `orders.user_id` (integer)

  - `orders.catalog_id` (integer)

  - `orders.price_group_id` (integer)

  - `orders.category_id` (integer)

  - `orders.parent_order_id` (integer)

  - `orders.client_id` (integer)

  - `orders.project_id` (integer)

  - `orders.sales_rep_id` (integer)

  - `orders.ship_to_id` (integer)

  - `orders.order_state_id` (integer)
    Current workflow state id (1 = PRELIMINARY, 2 = SUBMITTED, 8 = SHIPPED, 9 = COMPLETED, 23 = CANCELLED, ...).

  - `orders.order_source_id` (integer)
    Origin of the order (1 = ORDERWERKS, 20 = OTHER, 21 = APP, ...).

  - `orders.po_no` (string)

  - `orders.invoice_no` (string)

  - `orders.description` (string)

  - `orders.note` (string)

  - `orders.internal_note` (string)

  - `orders.shipping_instructions` (string)

  - `orders.is_quote` (boolean)

  - `orders.is_sample` (boolean)

  - `orders.is_local_pickup` (boolean)

  - `orders.is_local_delivery` (boolean)

  - `orders.is_shipped` (boolean)

  - `orders.partially_shipped` (boolean)

  - `orders.is_on_hold` (boolean)

  - `orders.is_cancelled` (boolean)

  - `orders.sub_total` (number)

  - `orders.tax` (number)

  - `orders.shipping` (number)

  - `orders.labor` (number)

  - `orders.discount` (number)

  - `orders.discount_total` (number)

  - `orders.other` (number)

  - `orders.grand_total` (number)

  - `orders.delivery_date` (string)

  - `orders.ship_date` (string)

  - `orders.do_not_ship_before_date` (string)

  - `orders.created_at` (string)

  - `orders.updated_at` (string)

  - `orders.Order_Items` (array)

  - `orders.Order_Items.id` (integer)

  - `orders.Order_Items.guid` (string)

  - `orders.Order_Items.order_id` (integer)

  - `orders.Order_Items.catalog_item_id` (integer)

  - `orders.Order_Items.catalog_item_guid` (string)

  - `orders.Order_Items.parent_order_item_id` (integer)

  - `orders.Order_Items.item_no` (integer)
    Line number within the order.

  - `orders.Order_Items.sku` (string)

  - `orders.Order_Items.name` (string)

  - `orders.Order_Items.description` (string)

  - `orders.Order_Items.qty` (number)
    Quantity ordered. Never reduced by shipments.

  - `orders.Order_Items.qty_shipped` (number)

  - `orders.Order_Items.qty_backordered` (number)

  - `orders.Order_Items.qty_pending` (number)

  - `orders.Order_Items.qty_reserved` (number)

  - `orders.Order_Items.is_manual_price` (boolean)

  - `orders.Order_Items.list_price_frozen` (number)
    Unit price captured when the line was created.

  - `orders.Order_Items.net_price` (number)

  - `orders.Order_Items.discount` (number)

  - `orders.Order_Items.discount_total` (number)

  - `orders.Order_Items.tax` (number)

  - `orders.Order_Items.total` (number)

  - `orders.Order_Items.is_credit` (boolean)

  - `orders.Order_Items.is_backordered` (boolean)

  - `orders.Order_Items.note` (string)

  - `orders.Order_Items.width` (number)

  - `orders.Order_Items.height` (number)

  - `orders.Order_Items.depth` (number)

  - `orders.Order_Items.selected_options` (array)

  - `orders.Order_Items.Catalog_Item` (object)
    A product. With API key authentication the paged list endpoint returns exactly the fields below; other endpoints (and user session calls) return the full model, which has many more optional fields.

  - `orders.Order_Items.Catalog_Item.id` (integer)

  - `orders.Order_Items.Catalog_Item.guid` (string)

  - `orders.Order_Items.Catalog_Item.catalog_id` (integer)

  - `orders.Order_Items.Catalog_Item.category_id` (integer)

  - `orders.Order_Items.Catalog_Item.sku` (string)

  - `orders.Order_Items.Catalog_Item.upc` (string)

  - `orders.Order_Items.Catalog_Item.name` (string)

  - `orders.Order_Items.Catalog_Item.description` (string)

  - `orders.Order_Items.Catalog_Item.manufacturer` (string)

  - `orders.Order_Items.Catalog_Item.color` (string)

  - `orders.Order_Items.Catalog_Item.style` (string)

  - `orders.Order_Items.Catalog_Item.active` (boolean)

  - `orders.Order_Items.Catalog_Item.is_taxable` (boolean)

  - `orders.Order_Items.Catalog_Item.msrp` (number)

  - `orders.Order_Items.Catalog_Item.cost_per_uom` (number)
    Supplier cost. Omitted for customer (vendor) users.

  - `orders.Order_Items.Catalog_Item.pricing` (object)
    Price per price group, keyed by price group name. `"N/A"` means not offered to that group.
    Example: {"Retail":99.99,"Wholesale":79.99,"Distributor":"N/A"}

  - `orders.Order_Items.Catalog_Item.has_inventory` (boolean)
    Whether stock is tracked for this item.

  - `orders.Order_Items.Catalog_Item.qty_on_hand` (number)

  - `orders.Order_Items.Catalog_Item.qty_incoming` (number)

  - `orders.Order_Items.Catalog_Item.reserved_qty_on_hand` (number)

  - `orders.Order_Items.Catalog_Item.qty_backordered` (number)

  - `orders.Order_Items.Catalog_Item.qty_held_for_backorders` (number)

  - `orders.Order_Items.Catalog_Item.min_qty_on_hand` (number)

  - `orders.Order_Items.Catalog_Item.max_qty_on_hand` (number)

  - `orders.Order_Items.Catalog_Item.min_order_qty` (number)

  - `orders.Order_Items.Catalog_Item.allow_backorder` (boolean)

  - `orders.Order_Items.Catalog_Item.qty_break` (number)
    Quantity at which `qty_break_price` applies.

  - `orders.Order_Items.Catalog_Item.qty_break_price` (number)

  - `orders.Order_Items.Catalog_Item.has_serials` (boolean)

  - `orders.Order_Items.Catalog_Item.has_lots` (boolean)

  - `orders.Order_Items.Catalog_Item.has_exp_date` (boolean)

  - `orders.Order_Items.Catalog_Item.width` (number)

  - `orders.Order_Items.Catalog_Item.height` (number)

  - `orders.Order_Items.Catalog_Item.depth` (number)

  - `orders.Order_Items.Catalog_Item.item_weight` (number)

  - `orders.Order_Items.Catalog_Item.shipping_weight` (number)

  - `orders.Order_Items.Catalog_Item.is_product_group` (boolean)

  - `orders.Order_Items.Catalog_Item.product_group_type` (string)
    Enum: "flat", "multi", "null"

  - `orders.Order_Items.Catalog_Item.product_group_display_style` (string)

  - `orders.Order_Items.Catalog_Item.group_parent_catalog_item_id` (integer)

  - `orders.Order_Items.Catalog_Item.group_sequence` (integer)

  - `orders.Order_Items.Catalog_Item.group_title` (string)

  - `orders.Order_Items.Catalog_Item.subsection_id` (integer)

  - `orders.Order_Items.Catalog_Item.third_party_sku` (string)

  - `orders.Order_Items.Catalog_Item.third_party_pricing` (string)

  - `orders.Order_Items.Catalog_Item.third_party_size` (string)

  - `orders.Order_Items.Catalog_Item.Category` (object)

  - `orders.Order_Items.Catalog_Item.Category.id` (integer)

  - `orders.Order_Items.Catalog_Item.Category.guid` (string)

  - `orders.Order_Items.Catalog_Item.Category.catalog_id` (integer)

  - `orders.Order_Items.Catalog_Item.Category.parent_category_id` (integer)

  - `orders.Order_Items.Catalog_Item.Category.name` (string)

  - `orders.Order_Items.Catalog_Item.Category.sequence` (integer)

  - `orders.Order_Items.Catalog_Item.Category.hide_category` (boolean)

  - `orders.Order_Items.Catalog_Item.Category.created_at` (string)

  - `orders.Order_Items.Catalog_Item.Category.updated_at` (string)

  - `orders.Order_Items.Catalog_Item.CategoryHierarchy` (array)
    Root-to-leaf category path, when category retrieval is not skipped.

  - `orders.Order_Items.Catalog_Item.created_at` (string)

  - `orders.Order_Items.Catalog_Item.updated_at` (string)

  - `orders.Order_Items.Catalog_Item.deleted_at` (string)
    Present only in delta-sync responses for soft-deleted items.

  - `orders.Order_Items.created_at` (string)

  - `orders.Order_Items.updated_at` (string)

  - `orders.Ship_To` (object)
    A billing or shipping address. Additional internal fields may be present.

  - `orders.Ship_To.id` (integer)

  - `orders.Ship_To.guid` (string)

  - `orders.Ship_To.vendor_id` (integer)

  - `orders.Ship_To.order_id` (integer)

  - `orders.Ship_To.name` (string)
    Contact name at this address.

  - `orders.Ship_To.company_name` (string)

  - `orders.Ship_To.address_line_one` (string)

  - `orders.Ship_To.address_line_two` (string)

  - `orders.Ship_To.address_line_three` (string)

  - `orders.Ship_To.city` (string)

  - `orders.Ship_To.state` (string)

  - `orders.Ship_To.postal_code` (string)

  - `orders.Ship_To.country` (string)

  - `orders.Ship_To.phone` (string)

  - `orders.Ship_To.fax` (string)

  - `orders.Ship_To.email` (string)

  - `orders.Ship_To.note` (string)

  - `orders.Ship_To.address_internal_id` (string)
    Your own identifier for this address, if one was supplied.

  - `orders.Ship_To.is_vendor_main_ship_to` (boolean)

  - `orders.Ship_To.verified` (boolean)
    True when the address was verified against a postal database.

  - `orders.Ship_To.lat` (number)

  - `orders.Ship_To.lng` (number)

  - `orders.Ship_To.created_at` (string)

  - `orders.Ship_To.updated_at` (string)

  - `orders.Vendor` (object)
    A customer of the supplier. The full model includes many integration-specific fields (QuickBooks, Stripe, FastBound, routing); only the commonly used ones are listed here.

  - `orders.Vendor.id` (integer)

  - `orders.Vendor.guid` (string)

  - `orders.Vendor.supplier_id` (integer)

  - `orders.Vendor.parent_vendor_id` (integer)

  - `orders.Vendor.customer_internal_id` (string)
    Your own identifier for this customer.

  - `orders.Vendor.name` (string)

  - `orders.Vendor.email` (string)

  - `orders.Vendor.shipping_email` (string)

  - `orders.Vendor.phone` (string)

  - `orders.Vendor.cell` (string)

  - `orders.Vendor.fax` (string)

  - `orders.Vendor.address_line_one` (string)

  - `orders.Vendor.address_line_two` (string)

  - `orders.Vendor.city` (string)

  - `orders.Vendor.state` (string)

  - `orders.Vendor.postal_code` (string)

  - `orders.Vendor.country` (string)

  - `orders.Vendor.active` (boolean)

  - `orders.Vendor.tax_exempt` (boolean)

  - `orders.Vendor.resale_tax_id` (string)

  - `orders.Vendor.lock_catalog_id` (integer)
    When set, the customer can only order from this catalog.

  - `orders.Vendor.price_group_id` (integer)
    Price group used for this customer's pricing.

  - `orders.Vendor.payment_type_id` (integer)

  - `orders.Vendor.payment_term_id` (integer)

  - `orders.Vendor.require_payment` (boolean)

  - `orders.Vendor.credit_limit` (number)

  - `orders.Vendor.open_balance` (number)

  - `orders.Vendor.is_ecomm_user` (boolean)
    True for Orderwerks Online (e-commerce) customers.

  - `orders.Vendor.net_term_ecomm_user` (boolean)

  - `orders.Vendor.require_po` (boolean)

  - `orders.Vendor.standing_po` (string)

  - `orders.Vendor.hide_pricing` (boolean)

  - `orders.Vendor.currency_id` (integer)

  - `orders.Vendor.notes` (string)

  - `orders.Vendor.default_order_category_id` (integer)

  - `orders.Vendor.route_id` (integer)

  - `orders.Vendor.route_stop_order` (integer)
    Standing stop order of the customer on its route; null = unordered (sorts last, by name).

  - `orders.Vendor.timezone` (string)

  - `orders.Vendor.bill_to_id` (integer)

  - `orders.Vendor.ship_to_id` (integer)

  - `orders.Vendor.created_at` (string)

  - `orders.Vendor.updated_at` (string)

  - `orders.Vendor.deleted_at` (string)
    Present only in delta-sync responses for soft-deleted customers.

  - `orders.Catalog` (object)

  - `orders.Catalog.id` (integer)

  - `orders.Catalog.guid` (string)

  - `orders.Catalog.supplier_id` (integer)

  - `orders.Catalog.name` (string)
    Example: Main Catalog

  - `orders.Catalog.email` (string)

  - `orders.Catalog.version` (string)

  - `orders.Catalog.active` (boolean)

  - `orders.Catalog.order_item_type_id` (integer)

  - `orders.Catalog.currency_id` (integer)

  - `orders.Catalog.order_prefix_override` (string)
    Prefix used for order numbers created from this catalog, if overridden.

  - `orders.Catalog.last_inventory_update` (string)

  - `orders.Catalog.Price_Groups` (array)

  - `orders.Catalog.Price_Groups.id` (integer)

  - `orders.Catalog.Price_Groups.guid` (string)

  - `orders.Catalog.Price_Groups.catalog_id` (integer)

  - `orders.Catalog.Price_Groups.value` (string)
    Price group name. This is the key used in a catalog item's `pricing` object.
    Example: Wholesale

  - `orders.Catalog.Price_Groups.is_main` (boolean)

  - `orders.Catalog.Price_Groups.percentage` (number)

  - `orders.Catalog.Price_Groups.price_upcharge_type_id` (integer)

  - `orders.Catalog.Price_Groups.created_at` (string)

  - `orders.Catalog.Price_Groups.updated_at` (string)

  - `orders.Catalog.Price_Groups.deleted_at` (string)

  - `orders.Catalog.created_at` (string)

  - `orders.Catalog.updated_at` (string)

  - `orders.Order_State` (object)

  - `orders.Order_State.id` (integer)

  - `orders.Order_State.guid` (string)

  - `orders.Order_State.name` (string)

  - `orders.User` (object)
    User who created the order.

  - `orders.User.id` (integer)

  - `orders.User.guid` (string)

  - `orders.User.name` (string)

  - `orders.User.email` (string)

  - `orders.Supplier` (object)

  - `orders.Supplier.id` (integer)

  - `orders.Supplier.guid` (string)

  - `orders.Supplier.name` (string)

  - `orders.Supplier.email` (string)

  - `orders.Client` (object)
    End client on behalf of whom the customer placed the order, if any.

  - `orders.Client.id` (integer)

  - `orders.Client.guid` (string)

  - `orders.Client.name` (string)

  - `orders.Parent_Order` (object)

  - `orders.Parent_Order.id` (integer)

  - `orders.Parent_Order.guid` (string)

  - `orders.Parent_Order.name` (string)

  - `orders.Order_Detail` (object)
    Supplier-specific extra fields.

  - `orders.Order_State_Logs` (array)
    State transition history.

  - `orders.Order_State_Logs.created_at` (string)

  - `orders.Order_State_Logs.User` (object)

  - `orders.Order_State_Logs.User.name` (string)

  - `orders.Order_State_Logs.User.email` (string)

  - `orders.Order_State_Logs.Order_State` (object)

  - `orders.Order_State_Logs.Order_State.name` (string)

  - `orders.Assigned_Users` (array)

  - `orders.Assigned_Users.id` (integer)

  - `orders.Assigned_Users.guid` (string)

  - `orders.Assigned_Users.name` (string)

  - `orders.Assigned_Users.email` (string)

  - `count` (integer, required)
    Number of orders in this page (not the total).

## Response 400:

  - `400` (unknown)
    Missing API key or secret (plain-text body `Invalid API Payload`).

## Response 500:

  - `500` (unknown)
    Unexpected server error. Some legacy endpoints return the message as `text/plain` instead of JSON.

## Response 500 fields (application/json):

  - `message` (string, required)
    Human-readable error message.
    Example: Invalid Catalog GUID

  - `error` (string)
    Underlying error detail, when available.

  - `code` (string)
    Machine-readable code for specific failures (for example `INVALID_DELTA_CURSOR`).