Search sales orders and quotes

GET/v2/api/store/{team_slug}/search/orders

v2Operation ID v2_public_search_orders_get

Finds sales orders and quotes by a word or number, for a search box or a picker. It returns at most 30 matches, with no paging, highest order number first.

The text in q matches anywhere inside ("contains") any of: the order number, the order name, the customer PO number, the customer's name, and every part of the shipping and billing addresses (label, street lines, city, state, country, postcode). Several words also match when each word is found in a different field, so northwind 1188 finds Northwind Apparel's order with PO number PO-1188. Without q, you get the first 30 in the same order.

Send the same fields as query parameters with GET, or as a JSON body with POST. To search quotes only, send quote=1 in the query string (GET .../search/orders?q=northwind&quote=1) or "quote": true in a POST body; quote=0 or false gives sales orders only. quote=true in a query string is refused with 422.

Each result is the same order or quote object Get a sales order or quote returns, without items. Amounts come in two encodings:

Thousandths, an older encoding: calc_subtotal, calc_tax, calc_total, and paid_amount (270000 is 270.00). The calc_* fields count only invoiced amounts, so they are 0 on an order with no invoice.
Decimal pairs: order_item_cart_total (the lines' value), order_balance_due, and invoiced_total. The amount is value ÷ 10^dp ({"value": 2700000, "dp": 4} is 270.00). Read dp every time.

For more than 30 results, or for filters, use the sales order and quote list operations.

Permission

Needs permission to view orders. With "view all orders" you search every order; with "view own orders" only the orders you created or are assigned to.

Business rules

q and query are at most 255 characters.
customer_id must be a customer id of this team.
Searching is "contains" and ignores case. % and _ are matched as plain characters.

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team

Query parameters

qstring
What to look for. Leave it out to list orders by order number.
- At most 255 characters
- Example northwind
querystring
Another name for q. q wins when both are sent.
- At most 255 characters
customer_idstring
Only this customer's orders. A customer id.
quoteinteger
1 for quotes only, 0 for sales orders only. Leave it out for both. In the query string true and false are refused with 422; with POST, a JSON true or false works.
- One of: 0, 1
- Example 1
hide_draftinteger
Does not hide drafts, despite its name. Don't use it; check internal_status in the results instead. Like quote, it takes 1 or 0 in the query string.
- One of: 0, 1
- Example 0

Request body

This operation takes no request body.

Response

200Successful response.

dataarray of objectsrequired
At most 30 orders and quotes. Each is the same object Get a sales order or quote returns, without items; the main fields are listed here.
- At most 30 items
Fields of each item (30)
- approval_statusstring | null
- billing_addressobject | null
- calc_subtotalinteger | number | string | null
  Invoiced subtotal: what has been invoiced so far, 0 until the order is invoiced. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- calc_taxinteger | number | string | null
  Invoiced tax, 0 until the order is invoiced. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- calc_totalinteger | number | string | null
  Invoiced total, 0 until the order is invoiced. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities. For the value of the order's lines, read order_item_cart_total.
- created_atstring (date-time) | null
- customerobject | null
  The customer, with id and name.
- customer_idstring | null
- customer_po_numberstring | null
- due_datestring (date-time) | null
  Production due date.
- idstring
  The order's id. Use it in the order operations.
- internal_statusstring | null
  draft or published. Null on orders from before drafts existed.
  - One of: "draft", "published"
- invoiced_totaldecimal pair
  Total of the order's invoices. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1350000, "dp": 4 } is 135.00). Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- is_draftboolean
  True when mode is create. Older field; prefer internal_status.
- is_quoteboolean
  True for a quote. Same as object_type quote.
- is_rushboolean
- issue_datestring (date-time) | null
- modestring
  create: a draft. edit: being edited. view: saved.
  - One of: "create", "edit", "view"
- namestring | null
- object_typestring
  What it is. Prefer this field.
  - One of: "sales_order", "quote"
- order_balance_duedecimal pair
  Invoiced total minus payments. A decimal pair: the amount is value ÷ 10^dp ({ "value": 850000, "dp": 4 } is 85.00). Read dp every time: it can differ between fields and records.
  - See Money and quantities.
- order_item_cart_totaldecimal pair
  The value of the order's lines, invoiced or not. A decimal pair: the amount is value ÷ 10^dp ({ "value": 2500000, "dp": 4 } is 250.00). Read dp every time: it can differ between fields and records. Stored amounts usually have 4 decimal places; an order with no amount yet can come as { "value": 0, "dp": 0 }.
  - See Money and quantities.
- paid_amountinteger | number | string | null
  Payments received. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- scoped_idstring
  The order or quote number people see, such as SO1001. Not an id.
- shipping_addressobject | null
- statusobject | null
  That status, with its label.
- status_idstring | null
  The order's status id in your team's statuses.
- trashedboolean
- typestring
  The same thing in older words: order for a sales order.
  - One of: "order", "quote"
- unique_keystring
  The order's unique key (ord_...), for the operations that take one.
statusintegerrequired
successbooleanrequired

Errors

401The API key is missing or wrong (unauthenticated).
403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.
When
Your role can't view orders (unauthorized).
Fix
Ask a team admin for permission to view orders.
404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.
422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
When
q is longer than 255 characters, customer_id is not a valid id, or quote or hide_draft is not a boolean. In a GET query string, quote=true is refused this way (validation_failed; error.fields names the field).
Fix
In the query string send quote=1 (quotes) or quote=0 (sales orders). In a POST body, JSON true or false work.

Notes

Results have no relevance ranking: every match counts the same, sorted by order number as text, highest first. Past 9,999 orders that text order is uneven (SO9999 comes before SO010000). Narrow the text if what you want is not in the first 30.
Draft orders are included. Deleted orders are not.
Quotes are searched with your order permissions.
The whole text is matched as one phrase, and the first 5 different words are also matched one by one; words after the fifth are not.
hide_draft does not hide drafts. It compares the order's status with one fixed status record that belongs to at most one team, so for almost every team it changes nothing. To leave drafts out, skip results whose internal_status is draft (or mode is create).
Search results, Get order and the order lists share field names: object_type (sales_order or quote) is the same fact as type (order or quote) and is_quote.

Example request

curl

curl 'https://secure.yoprint.com/v2/api/store/your-team/search/orders' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1'

Example response 200

{
  "data": [
    {
      "approval_status": null,
      "billing_address": null,
      "calc_subtotal": 125000,
      "calc_tax": 10000,
      "calc_total": 135000,
      "created_at": "2026-11-03T09:30:00+00:00",
      "customer": {
        "id": "63KcENAAsKuipY",
        "is_external": false,
        "name": "Northwind Apparel",
        "tax_exempt": false
      },
      "customer_id": "63KcENAAsKuipY",
      "customer_po_number": "PO-1188",
      "due_date": "2026-11-14T00:00:00+00:00",
      "id": "V4keXwwxMQyXw7",
      "internal_status": "published",
      "invoiced_total": {
        "dp": 4,
        "value": 1350000
      },
      "is_draft": false,
      "is_quote": false,
      "is_rush": false,
      "issue_date": "2026-11-03T00:00:00+00:00",
      "mode": "view",
      "name": "Spring team shirts",
      "object_type": "sales_order",
      "order_balance_due": {
        "dp": 4,
        "value": 850000
      },
      "order_item_cart_total": {
        "dp": 4,
        "value": 1250000
      },
      "paid_amount": 50000,
      "scoped_id": "SO1001",
      "shipping_address": {
        "address1": "100 Example Street",
        "city": "Springfield",
        "country_code": "US",
        "id": "RNG2OuYC20YzXs",
        "label": "Head office",
        "postcode": "62701",
        "state_code": "IL"
      },
      "status": {
        "color": "#2196f3",
        "customer_label": "In Progress",
        "id": "52CuV8sWcDZLPm",
        "label": "In production",
        "position": 2,
        "role": "order",
        "trashed": false,
        "type": "in_progress"
      },
      "status_id": "52CuV8sWcDZLPm",
      "trashed": false,
      "type": "order",
      "unique_key": "ord_EXAMPLEuniqueKey"
    }
  ],
  "status": 200,
  "success": true
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com