Storefront
Result cards
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
Merchants design the search result card for each content type in the Searcio dashboard, with a visual builder. This endpoint delivers the published designs to search widgets as precompiled HTML and CSS, so a widget renders exactly what the merchant designed without shipping a rendering engine of its own.
Base: https://searcio.com/api/v1/sites/{site}, or key-relative
https://searcio.com/api/v1 (the site is resolved from the search key).
Auth: search key (?key=sk_… or X-Search-Key). It works only on the
site's own domain.
GET /card-templates
| Param | Type | Default | Notes |
|---|---|---|---|
type |
string (≤ 100) | None | Only templates for one content type. |
filter[lang] |
string | None | The page's language: the templates for it and those for every language. Without it, all templates. |
key |
string | None | The search key (or X-Search-Key). |
Each template carries lang, the language its texts are in, or null when it
serves every language. On a multilingual shop, send the page's language, so an
English page gets the English template with its "View" button and a German page
the German one.
Served from a server-side cache and not metered as a search. Fetch the templates once per page load (or cache them on the client), not once per query.
Response: 200 OK
{
"templates": [
{
"id": 12,
"type": "product",
"is_default": false,
"priority": 1,
"conditions": [
{ "field": "category", "operator": "equals", "value": "cap" }
],
"html": "<a class=\"sct-12 sct-12-root\" href=\"{{url}}\">…</a>",
"css": ".sct-12-root { … } @media (max-width: 767px) { … }"
},
{
"id": 9,
"type": "product",
"is_default": true,
"priority": 0,
"conditions": [],
"html": "…",
"css": "…"
}
]
}Conditional templates come first (in ascending priority) and the default
template comes last, so the array is already in evaluation order.
Widget rendering contract
For each search hit:
- Take the templates whose
typematches the hit'stype. - Walk them in array order and use the first whose
conditionsall match the hit (is_defaultacts as the catch-all). If there is no template, use your built-in card markup. - Inject the template's
cssonce per template, for example in a<style>tag keyed by template id. All selectors are scoped undersct-{id}. - Replace every
{{field}}placeholder with the hit's HTML-escaped field value. Placeholders also appear insidesrcandhrefattributes. A missing field is replaced with an empty string. - Remove any element whose
data-sc-ifattribute (a JSON array of conditions) does not fully match the hit. This is how conditional badges such as "SALE" work. - If an element has
data-sc-rating-field, set the CSS variable--sc-rating-percenton it tovalue / 5 * 100percent. - If an element has a
data-sc-priceattribute, compute and fill in its price display as described below.
The compiled CSS already holds the layout the builder draws, so the card looks
the same on the site as in the builder: the card and its containers stack their
children in a column, other components flow inline, and an image is a block no
wider than its box. Each component's own styles come after these and win.
Inside a card that links to the product, a button is compiled as a span,
because a link cannot hold another link; the card takes the click.
Price components
A price component compiles to one wrapper carrying data-sc-price, the
field mapping and the number format, and up to four child spans marked
with data-sc-price-part="prefix|regular|current|suffix":
| Attribute | Meaning |
|---|---|
data-sc-price-field |
Field holding the plain effective price (e.g. price). |
data-sc-regular-field |
Field holding the original price before a sale (e.g. regular_price). |
data-sc-sale-field |
Field that, when not empty, means the item is on sale (e.g. sale_price). |
data-sc-min-field / data-sc-max-field |
Fields for a variable product's price range (e.g. price_min / price_max). |
data-sc-currency |
Currency symbol, e.g. €. On a price set to the shop's currency it is already the symbol of the currency the plugin last reported (currency in the search configuration), filled in when the templates are served, so it follows the shop without the template being published again. |
data-sc-currency-source |
shop on a price set to the shop's currency; absent on a price with its own symbol. Informational: the widget formats with data-sc-currency either way. |
data-sc-currency-position |
before, before_space, after, or after_space. |
data-sc-decimals |
Number of decimal places (0 to 4). |
data-sc-decimal-sep |
Decimal separator, e.g. ,. |
data-sc-thousand-sep |
Thousands separator, e.g. . (may be empty). |
For a hit, decide in this order:
- Range: if the min and max fields are both present and differ, the
product is variable. Show only the
[data-sc-price-part="current"]span, set to the min field's value, with the"prefix"span (its compiled text, e.g. "ab" in a German template) before it. Hide"regular". - Sale: otherwise, if the sale field is present and not empty, show
"regular"(the regular field's value, which the template normally strikes through) followed by"current", set to the sale field's value. Hide"prefix". - Plain: otherwise, show only
"current", set to the price field's value. Hide"prefix"and"regular".
The prefix the merchant leaves empty is compiled in the template's language: "ab" in German, "from" in English, "à partir de" in French, "desde" in Spanish, "da" in Italian, "vanaf" in Dutch and "od" in Polish. A template without a language takes the site's first language.
The space after the prefix and after the regular price is drawn by the compiled
CSS (::after), so setting a part's textContent keeps it, and a hidden part
takes its space along.
Format every amount with the currency, decimals and separator attributes above
(they mirror typical WooCommerce price settings) before writing it into the
span. Hide a part with display: none rather than removing it, so it can be
shown again when the card is rendered for another hit. Each part already has
its own compiled class for the typography and colour the merchant chose, so the
widget only sets textContent and toggles visibility, never inline styles.
Condition operators
exists, not_exists, equals, not_equals, gt, lt, contains,
is_true and is_false. Multiple conditions are combined with AND. equals
compares loosely as strings; gt and lt compare numerically.
Errors
| Status | When |
|---|---|
401 |
Missing or invalid search key |
403 |
Site disabled, or Origin not the site's own domain |