Search Product Variants

Searching product variants

Overview
Permissions and Authentication
Headers
Query parameters
Sample request
Sample response

Overview

Call name: search-product-variants
Endpoint URL: https://{Services API hostname}/search/product-variants
Request methods: HTTP POST
Request Content-Type: application/x-www-form-urlencoded
Response Content-Type: application/json
Auth required: yes

This endpoint searches exclusively for product variants. The search matches against the product variant name and barcodes. Results are ranked by relevance, with stronger matches on the variant name weighted highest.

This endpoint returns only product variants. If you also need matching products in the same request, use the combined Search Products endpoint instead, which searches both products and product variants together.

Permissions and Authentication

This API call requires admin authentication:

The performing user must be logged in and have access to the chain specified in the request
A valid admin session is required (see Authentication)

Headers

The following headers are required:

Header	Description
X-Spaaza-Session-User-Id	Spaaza ID of the user obtained from the login endpoint
X-Spaaza-Session-Key	Session key obtained from the login endpoint
X-Spaaza-Session-Chain-Id	The ID of the Spaaza chain or retailer

Query parameters

This API accepts the following parameters, sent as application/x-www-form-urlencoded form data:

Parameter	Description
chain_id	(integer, required) The ID of the Spaaza chain or retailer
query	(string, required) The search term(s). Matches against the product variant name and barcodes
page	(integer, required) The page number of results (starting from 1)
count	(integer, optional) Number of results to return per page. Defaults to 10 if not specified

Sample request

curl -X POST \
  -H 'X-Spaaza-Session-User-Id: <your user ID>' \
  -H 'X-Spaaza-Session-Key: <your session key>' \
  -H 'X-Spaaza-Session-Chain-Id: <your chain ID>' \
  -d 'chain_id=<your chain ID>' \
  -d 'query=2000042436020' \
  -d 'page=1' \
  -d 'count=25' \
  'https://{Services API hostname}/search/product-variants'

Sample response

The response is a JSON array of product variant objects.

[
    {
        "barcodes": [
            {
                "barcode": "2000042436020",
                "created_date": "2026-03-15T10:30:00Z",
                "deleted": false,
                "id": 3,
                "last_modified_date": "2026-06-01T14:22:00Z",
                "product_variant_id": 12
            }
        ],
        "chain_id": 1743,
        "colour": "blue",
        "cost_price": 79.95,
        "created_date": "2026-03-15T10:30:00Z",
        "currency": {
            "id": 1,
            "code": "EUR",
            "name_en": "Euro",
            "symbol": "\u20ac"
        },
        "deleted": false,
        "id": 12,
        "image_url": "https://www.example.com/images/blue_arran.jpg",
        "last_modified_date": "2026-06-01T14:22:00Z",
        "name": "Men's Merino Aran Jumper - Blue M",
        "price": 99.95,
        "price_is_promotional": false,
        "product": {
            "brand": "Aran Brands Inc.",
            "category": "knitwear",
            "chain_id": 1743,
            "cost_price": 79.95,
            "created_date": "2026-03-15T10:30:00Z",
            "currency": {
                "id": 1,
                "code": "EUR",
                "name_en": "Euro",
                "symbol": "\u20ac"
            },
            "deleted": false,
            "description": "The Aran Jumper is a style of jumper that takes its name from the Aran Islands.",
            "id": 5,
            "image_url": "https://www.example.com/images/arran.jpg",
            "last_modified_date": "2026-06-01T14:22:00Z",
            "name": "Men's Merino Aran Jumper",
            "owner_code": "00024003",
            "price": 99.95,
            "price_is_promotional": false,
            "season": "",
            "web_url": "https://www.example.com/products/arran-jumper"
        },
        "size": "M",
        "web_url": "https://www.example.com/products/arran-jumper-blue-m"
    }
]

Product variant fields

Field	Type	Description
`barcodes`	array	Array of barcode objects (see below)
`chain_id`	integer	The chain ID the variant belongs to
`colour`	string	The colour of the variant
`cost_price`	float	The cost price of the variant
`created_date`	string	ISO 8601 datetime when the variant was created
`currency`	object	Currency information including `id`, `code`, `name_en`, `symbol`
`deleted`	boolean	Whether the variant has been deleted
`id`	integer	Unique product variant identifier
`image_url`	string	URL to the variant image
`last_modified_date`	string	ISO 8601 datetime when the variant was last modified
`name`	string	The variant name
`price`	float	The retail price of the variant
`price_is_promotional`	boolean	Whether the current price is a promotional price
`product`	object	The parent product object (see Product fields)
`size`	string	The size of the variant
`web_url`	string	URL to the variant on the retailer's website

Barcode fields

Field	Type	Description
`barcode`	string	The barcode value
`created_date`	string	ISO 8601 datetime when the barcode was created
`deleted`	boolean	Whether the barcode has been deleted
`id`	integer	Unique barcode identifier
`last_modified_date`	string	ISO 8601 datetime when the barcode was last modified
`product_variant_id`	integer	The ID of the product variant the barcode belongs to

Searching product variants​

Contents​

Overview​

Permissions and Authentication​

Headers​

Query parameters​

Sample request​

Sample response​

Product variant fields​

Barcode fields​