Introduction
Guides
API Reference
SPI CRM v2
SPI CRM v1
SPI Events
SPI Gift Card
SPI Payment
SPI Product Recommendations
SPI Product Search
Journals v3
Purchase Prices v3
Shipments v3

Sitoo Product Search SPI

Search Products

get /product-search

Get list of products and available filters based on search parameters.

PARAMETERS
return_only_filters
boolean
query

If a value of true is sent for this parameter, then the endpoint will return an empty list of products and the default set of filters to display for a new search.

Default: false
Example: /product-search?return_only_filters=true
search_text
string
query

Text to search for.

Example: /product-search?search_text=strato
filter
object
query

Filter for the product search. The keys must follow the pattern ^[a-zA-Z][a-zA-Z0-9_-]{0,31}$.

Example: /product-search?filter[CATEGORY]=CLOTHES&filter[BRANDS]=Nike&filter[BRANDS]=Adidas
lang
string
query
REQUIRED

Language to use for localized fields in returned products (ISO 3166-1, alpha-2 uppercased).

Example: /product-search?lang=FR
currency
string
query
REQUIRED

Currency for product prices. (ISO 4217, alpha-3 uppercased).

Example: /product-search?currency=EUR
store_id
string
query

Store ID (External ID of the Store in Sitoo).

Example: /product-search?store_id=WA123
customer_id
string
query

ID of the customer.

Example: /product-search?customer_id=4572348
start
integer
query

Start index of products. Used for pagination.

Default: 0
num
integer
query

Number of products to return.

Default: 10
Returns

Returns a product search result object.

product_search_result
gethttps://crm.example.com/product-search?search_text=Stratosphere
RESPONSE JSON
{
  "products": {
    "count": 1,
    "items": [
      {
        "sku": "234.788.14",
        "name": "Shirt Stratosphere",
        "variant_text": "White",
        "product_group": "Apparel",
        "custom_attributes": {
          "style": "v-neck",
          "material": "cotton",
          "images": [
            {
              "name": "T-shirt Stratosphere White",
              "url": "https://www.example.com/images/t-shirt-stratosphere-white.png"
            },
            {
              "name": "T-shirt Stratosphere White Back",
              "url": "https://www.example.com/images/t-shirt-stratosphere-white-back.png"
            }
          ]
        },
        "additional_data": {
          "code": "140-155",
          "product-group-1": "Apparel",
          "product-group-2": "Women"
        },
        "offer_text": "Summer Sale",
        "unit_regular_price": "129.00",
        "unit_price": "99.00",
        "unit_sales_taxes": [
          {
            "name": "Tax 25%",
            "amount": "19.80",
            "percentage": 25
          }
        ]
      }
    ]
  },
  "filters": [
    {
      "id": "CATEGORY",
      "title": "Category",
      "type": "single-enum",
      "options": [
        {
          "id": "CLOTHES",
          "name": "Clothes",
          "num_products": 42,
          "options": [
            {
              "id": "NEWARRIVALS",
              "name": "New Arrivals",
              "num_products": 18
            },
            {
              "id": "COATS",
              "name": "Coats",
              "num_products": 24
            }
          ]
        }
      ]
    }
  ],
  "search_text_used": null
}
HTTP Status Code Summary
200Returns a product search result object.
400Invalid request. Data sent from client is invalid.
401Missing or bad authentication.
403User is not authorized to perform operation.
500Internal Server Error.

Objects

filter
object

Filter for product search.

PROPERTIES
id
string
REQUIRED

ID of the filter.

Pattern: ^[a-zA-Z][a-zA-Z0-9_-]{0,31}$
Example: ""CATEGORY""
title
string
REQUIRED

Heading for the filter

Example: ""Category""
type
string
REQUIRED

Type of filter.

VALUES
single-enum
multi-enum
bool
options
array
(filter_option)

Array of available options for this result. NOTE! Only applies for type single-enum or multi-enum

filter_option
object

PROPERTIES
id
string
REQUIRED

ID of the option.

name
string
REQUIRED

Name of the option.

num_products
integer

Number of products available for this option.

options
array
(filter_option)

Used if values should be presented in a tree structure.

Example: { "id": "CLOTHES", "name": "Clothes", "num_products": 42, "options": [ { "id": "NEWARRIVALS", "name": "New Arrivals", "num_products": 18 }, { "id": "COATS", "name": "Coats", "num_products": 24 } ] }

image
object

Image attribute.

PROPERTIES
url
string
(url)
REQUIRED

Url to the image.

name
string

Name of the image.

Example: { "name": "T-shirt Stratosphere White", "url": "https://www.example.com/images/t-shirt-stratosphere-white.png" }

images
array

Image attribute.

array
object
(image)
image

money
string

Money value with fixed (2) number of digits.

Pattern: ^[-+]?[0-9]+\.[0-9]{2}$
Example: "100.00"

product
object

The product object.

PROPERTIES
sku
string
REQUIRED

Stock Keeping Unit. Unique value to identify the product.

Max Length: 32
name
string
REQUIRED

The name of the product.

variant_text
string

Product variant data for the product. (eg. Size: Medium)

product_group
string
REQUIRED

Name of the product group. Can be used for grouping values in reports (eg. Z-reports).

custom_attributes
object

Attributes for the product. NOTE! To be displayed properly by the client, attributes of type string and integer should match the custom attribute definitions in the Sitoo system.

<*>
object
Properties with values of type `string`, `integer`, `image` or `images`.
additional_data
object

Additional data that will be added to order items when the product is purchased.

<*>
string
Properties with values of type `string` is allowed.
offer_text
string

The text presented if the product is discounted (ie. unit_price < unit_regular_price).

unit_regular_price
money

Regular price per unit incl. sales tax. The normal price for the product. If set, it should have a value greater than unit_price.

unit_price
money
REQUIRED

Price per unit incl. sales tax. What the customer pays for the product. Must be a value greater than "0.00".

unit_sales_taxes
array
(sales_tax)
REQUIRED

Sales taxes included per unit. Must contain exactly 1 sales_tax, which for a Sitoo system will be mapped to the vat values of the order item.

Example: { "sku": "234.788.14", "name": "Shirt Stratosphere", "variant_text": "White", "product_group": "Apparel", "custom_attributes": { "style": "v-neck", "material": "cotton" }, "additional_data": { "code": "140-155", "product-group-1": "Apparel", "product-group-2": "Women", "images": [ { "name": "T-shirt Stratosphere White", "url": "https://www.example.com/images/t-shirt-stratosphere-white.png" }, { "name": "T-shirt Stratosphere White Back", "url": "https://www.example.com/images/t-shirt-stratosphere-white-back.png" } ], "offer_text": "Summer Sale", "unit_regular_price": "129.00", "unit_price": "99.00", "unit_sales_taxes": [ { "name": "Tax 25%", "amount": "19.80", "percentage": 25 } ] } }

product_search_result
object

Envelope for the product search endpoint.

PROPERTIES
products
object
REQUIRED
count
integer

The maximum number of available products for the current search. If this number is greater than the number of items returned, then pagination can be done using the start parameter.

items
array
(product)

An array of products returned for this search.

filters
array
(filter)
REQUIRED

The filters available for this result.

search_text_used
string

If set then the search_text provided, resulted in no products, but instead a search was done for this text instead, returning the included products.

Example: ""Stratosphere""

sales_tax
object

The sales tax object.

PROPERTIES
name
string
REQUIRED

The name of the tax (eg. "Regular VAT").

Example: ""Regular VAT""
amount
money
REQUIRED

The amount of tax (eg. "20.00").

Example: ""20.00""
percentage
number
REQUIRED

The tax percentage (eg. 25.0).

Example: "25"
Example: { "name": "Regular VAT", "amount": "20.00", "percentage": 25 }
Copyright © 2024 Sitoo AB. All rights reserved.