Developer guide Read as Markdown Agent skill

SureDone product search

This grammar applies to authenticated product searches and product scopes. Order and page searches have separate field rules. A search can return plausible results even when a condition is wrong; a nonzero match count does not validate the query.

Discover, validate, then read

  1. Read the current account's field catalogue with GET /v3/search/fields, using the normal paired API credentials. Installed channels and custom fields change which names exist. The catalogue requires product-editor view permission.
  2. Compose a query using those names and the rules below. Field names are case sensitive.
  3. Send POST /v3/search/validate with Content-Type: application/json and a body containing only the query string. Queries are limited to 4096 UTF-8 bytes. Validation does not search products. It returns valid, separate errors and warnings, and spanEncoding: utf-16. Findings contain a code, severity, message, and half-open start/end offsets in UTF-16 code units, matching browser string positions.
  4. Review every finding before executing a proposed query. valid: true means there are no errors; warnings can still identify an unavailable field or an unintended comparison. A valid query may correctly match zero products.
  5. For an authorized read, URL-encode the complete query as one path segment in GET /v3/search/items/{query}. Keep paging explicit. Validation is advisory and does not rewrite saved queries or change the search engine.

Conditions and operators

A condition is field:value, with its operator immediately after the colon. Supported operators are >=, >, <=, <, !=, -=, =, and -. The last means does not contain; -= aliases !=. Without an operator, the operand is a contains search. Numeric and date fields apply their own conversions.

Spaces combine conditions with AND. Parentheses around space-separated alternatives form an OR group. Groups cannot nest, and a single condition without internal whitespace is treated as ordinary text. The words AND and OR are ordinary text terms, not operators. Depending on the data, they can broaden or narrow the result.

Use ASCII spaces when composing a query. The parser collapses ASCII whitespace, including inside phrases. Nonbreaking spaces and other Unicode separators are not interchangeable with ASCII spaces; a pasted byte-order mark can become an extra search term. Review unexpected characters instead of silently normalizing a saved query.

Double quotes or paired asterisks preserve a phrase, including spaces; they do not imply equality. Use the equality operator when equality is intended. A lone trailing asterisk is literal. Percent and underscore are literal characters in contains operands. A leading caret or trailing dollar sign removes the corresponding contains wildcard.

Backslashes do not escape phrase delimiters. Either a double quote or an asterisk can end a phrase, so paired asterisks do not protect an embedded double quote. There is no general escape syntax for arbitrary literal phrases; do not substitute an approximate query when the intended literal cannot be represented.

An unquoted contains operand loses one trailing lowercase s. Quoting or using an explicit operator suppresses that compatibility behavior. The parser also accepts mixed quote/asterisk delimiter pairs; prefer matching delimiters for clarity.

An absent operand means nonempty. An equality with no operand means empty. GUID uses NULL comparisons instead of empty-string comparisons; do not extend string empty-value behavior to dates or numeric fields without checking their types.

The special product type field requires an explicit operator. A bare parent, children, or variation value silently emits no filter. Use the examples below.

An unknown field becomes a full-text term, including its colon. An operand naming another searchable field becomes a column comparison for non-contains operators, even if quoted; there is no literal escape for that ambiguity. Use the bare field name, not a $field prefix. For example, price:>cost compares two catalogue fields when both exist, while price:>$cost can coerce the operand to zero. Recheck the live catalogue before interpreting such a comparison.

Parser-verified examples

These examples are generated from the same fixture tested against the product parser and browser linter. They illustrate syntax, not a universal list of fields available to every account.

Query Product parser behavior
sku_type:=parent Parent products compare sku = guid.
sku_type:=variation Products with variations compare total_variation > 1.
brand: Field exists and is nonempty; GUID uses IS NOT NULL.
brand:= Empty string equality; GUID uses IS NULL.
brand:!= Nonempty string; -= is an alias for !=.
brand:nikes Unquoted contains strips one trailing s.
brand:"nikes" Quotes preserve spaces and suppress trailing s stripping; still contains.
brand:*nikes* Paired asterisks also preserve a phrase; they are not wildcards.
brand:=nikes Equality retains a trailing s.
sku:^ABC Leading ^ removes the leading contains wildcard.
sku:ABC$ Trailing $ removes the trailing contains wildcard.
sku:^ABC$ Both anchors constrain the entire string using LIKE.
brand:=cost A non-LIKE operand naming a field compares columns, even when quoted.
sku_type:=children Children compare sku != guid; parent uses sku = guid.
guid:= GUID equality with an empty value means NULL.
guid:!= GUID inequality with an empty value means NOT NULL.
total_stock:>0 Total stock supports numeric comparisons.
brand:=nike (brand:=adidas brand:=puma) Spaces combine conditions with AND; a spaced group combines alternatives with OR.
guid:ABC123 GUID contains ABC123; use = for equality.
price:>$cost A dollar-prefixed operand is a literal; price comparison coerces it to zero.
price:>"$cost" Quoting a dollar-prefixed numeric operand still coerces it to zero.
title:"a\" b\" c" Backslash does not escape the closing quote; the rest can become plain text.
brand:=nike stock:>0 A nonbreaking space is retained in the brand operand, not a condition separator.
title:chars=0 Character count equality includes blank or missing values at zero.
title:chars-=150 The chars -= operator aliases !=; the threshold is a nonnegative integer.
title:chars>150 Lowercase unquoted chars compares the character count of the stored field text.
(title:chars<20 brand:=nike) Character count conditions work inside OR groups.
price:chars=5 Character count uses stored text without numeric or date operand conversion.
title:chars>=0005 Leading zeros are retained in the threshold; integer-sized limits do not apply.
title:"chars>150" Quoted chars syntax remains a literal contains search.
sku_type:chars>5 Synthetic product fields retain their existing behavior for chars operands.

Automated assistants

The SureDone product-search skill follows the discover–validate–read procedure. It carries no account field list. Authentication and access remain subject to the customer's existing permissions; installing a skill grants no credentials or authority to change products.