Paloma Catalog API

Updated: 14.01.2020 18:53

The Paloma Catalog API provides access to category and product data.

https://[organization].paloma.one/api/catalog/v2

Products

Products are the main entities of the catalog. A Product object contains basic information about the product, its attributes, price, availability, images and variants.

A product itself cannot be purchased, only one of its variants. Therefore, each product comes with at least one variant. Each variant comes with a SKU (variants[n].sku) which identifies the variant and can be used for example to add an item to a shopping cart.

Example

GET /api/{channel}/{locale}/products/{itemNumber}

See Catalog API Reference.

Variants

A product can have multiple variants. A variant can have its own attributes, price and images. If applicable, each variant has a list of options which define the variant (e.g. "size" or "color").

Example

"options": {
  "color": {
    "option": "color",
    "label": "Farbe",
    "value": "000"
  },
  "size": {
    "option": "size",
    "label": "Grösse",
    "value": "35"
  }
}

Attributes

Attributes consist of a type, label and one or multiple values. The type can be used as an identifier in case some logic needs to be applied for certain attributes. Attributes can also be used to filter product search results.

Values
An attribute's value contains localized content to be displayed in the front-end. Some attributes additionally come with valueCode, which is a language-independent identifier for an attribute.

Multi-valued attributes have those values listed in values and valueCodes respectively.

"origin": {
    "type": "origin",
    "label": "Herkunft",
    "value": "Belgien, Deutschland, Frankreich, Luxemburg, Niederlande",
    "valueCode": "origin_be, origin_de, origin_fr, origin_lu, origin_nl",
    "values": [
        "Belgien",
        "Deutschland",
        "Frankreich",
        "Luxemburg",
        "Niederlande"
    ],
    "valueCodes": [
        "origin_be",
        "origin_de",
        "origin_fr",
        "origin_lu",
        "origin_nl"
    ]
}

Price

The base price for the product can be found in the master.pricing object. This pricing object contains the following:

  • Currency (the currency is usually the same for all products in a channel)
  • Gross price (formatted and unformatted): This is usually the price that should be displayed to a customer (pricing.grossPriceFormatted).
  • Net price (formatted and unformatted): This is usually the gross price before VAT.
  • Taxes (usually VAT): Applicable taxes for the product. This contains tax label, rate and actual amount.

Be aware that each variant of a product can have its own price. The product base price should only be used to display on product views (e.g. category product listings) where no individual variants are visible

Images

Each product image comes in different (pre-configured) sizes. You can either chose the appropriate size for the view you want do display or use all sizes for image source maps.

"images": [
    {
        "name": "1716.839_Rosenkohl_15_25mm_uc.jpg",
        "title": "Hauptbild",
        "caption": null,
        "set": "image_main_jpg_rgb",
        "sources": [
            {
                "size": "full",
                "url": "https://..."
            },
            {
                "size": "large",
                "url": "https://..."
            },
            {
                "size": "medium",
                "url": "https://..."
            },
            {
                "size": "small",
                "url": "https://..."
            }
        ]
    }
]

Categories

Shop categories are organized in a hierarchical fashion. Each category has a parent category (except for the top-level categories) and a list of sub-categories.

A category is uniquely identified by its code.

Each category also has a slug, which should be included when rendering category links. Note: slugs are not unique or constant, so you should always use the category code as identifier in category links.

Example

{
    "code": "11",
    "channel": "b2c",
    "catalog": "b2c",
    "locale": "de_CH",
    "parent": "8",
    "position": 1,
    "level": 2,
    "subCategories": [
        {
            ...
        }
    ],
    "name": "Schuhe",
    "slug": "damen/damenschuhe",
    "h1Title": "Damenschuhe",
    "pageTitle": "Damenschuhe online kaufen jetzt im ACME Onlineshop",
    "metaDescription": "Damenschuhe online kaufen! Jetzt bei ACME, Ihrem Onlineshop für hochwertige Lederwaren.",
    "aliases": "Damenschuhe, Damenschuh, Damnschuhe, Danenschuhe, Frauenschuhe",
    "ancestors": [
        {
            "code": "8",
            "name": "Damen",
            "slug": "damen",
            "level": 1
        }
    ]
}

Search

Product search is used for all views with product listings. This can be a search results page or a category details page. In the latter case, search is simply restricted to the current category using the category parameter.

See Catalog API Reference.

For search suggestions ("as you type") a separate method is available.

There are three ways to search for products, all of which can be used in conjunction.

1. Filter by category code: Only products listed in the given category are found.

POST /api/catalog/v2/{channel}/search
{
  "category": "123" # from category.code
}

2. Search query: The query parameter is intended for search field scenarios. Any input the user puts into a search field can be used here.

POST /api/catalog/v2/{channel}/search
{
  "query": "banana"
}

3. Filters: Search results are filtered by the given property and values.

POST /api/catalog/v2/{channel}/search
{
  "filters": [
    {
      "property": "variants.options.size.value" # filter by 'size' option
      "values": [ "L", "XL" ]
    }
  ]
}

Search Filters

A common use case in shop front-ends is faceted search through the application of search filters.

The data for displaying those filters can be obtained when using the "Search products" operation with the filterAggregates flag turned on.

POST /{channel}/{locale}/search
{
  "category": "123",
  "filterAggregates": true
}

The return value will contain aggregated filter values alongside the normal search results:

{
  "content": [ ... ],
  "aggregates": [
    {
      "property": "variants.options.color.value",
      "label": "Color",
      "values": [
        {
          "value": "black",
          "count": 90
        },
        {
          "value": "blue",
          "count": 64
        },
        ...
      ]
    }
  ],
  ...
}

Screenshot 2019-12-06 at 13.45.13.png

After the user has selected the preferred filter values, the search can be executed again. Note the use of the property field from the search response (aggregates[n].property).

POST /{channel}/{locale}/search
{
  "category": "123",
  "filterAggregates": true,
  "filters": [
    {
      "property": "variants.options.color.value",
      "values": [ "bordeaux", "brown" ]
    }
  ]
}

The return value will contain the filtered search results as well as the updated filter values for the current search.

Screenshot 2019-12-06 at 13.45.44.png

Next: Carts & Checkout