Skip to main content

Introduction to Catalog APIs

The Catalog APIs serve as the distribution and consultation engine for Webround Commerce catalogs. While the Commerce APIs handle back-office operations, the Catalog APIs are designed to deliver enriched commercial data to your frontends (Drafts, published sites, or any internet-connected tool).

This module is optimized to manage the complexity of multi-language and multi-currency catalogs, allowing you to retrieve everything needed to render a complete product page or entire catalog listings in a single call.

Data Philosophy: Enrichment on Demand​

In Webround, a product is not a static entity. It is a collection of references (assets, attributes, variants) that can be managed differentially. For instance, a catalog listing might only require names, assets, and prices, whereas a detail page should display all available data. For this reason, these APIs adopt an enrichment on demand philosophy.

Through a series of inclusion flags (e.g., includeAssets, includeAttributes), you can granularly decide which relations to include in the response.

  • Fast Listings: Request only basic data for navigation grids.
  • Product Pages: Enable all flags to retrieve variants, media galleries, and technical specifications in one go.

Localization and Dynamic Pricing​

The catalog never returns "flat" data. Every request is processed based on the context defined by mandatory parameters:

1. Currency & Price Cadence​

A product's price is tied to a specific currency (currencyCode) and payment frequency (cadence).

  • Flexibility: You can manage one-time purchase products and subscription services (daily, monthly, weekly, etc.) within the same catalog.
  • Filtering: The system filters the requested price based on parameters. Setting currencyCode to EUR will exclude all products that do not have a price in EUR. Note: Products without a price are always returned.

2. Language Code​

All text fields (names, descriptions, tags, attributes) are filtered via the langCode. If a translation is missing, the system automatically falls back to the store's default language to ensure no fields remain empty.

Advanced Search and Filtering​

To overcome URL length limitations and allow complex queries, catalog searches utilize the POST method on dedicated search endpoints.

Filter Logic (UUID & Range)​

The filtering system is designed to handle arrays of identifiers with full support for Tags, Filters, and text searches.

  • Tag Filtering (tagValueIds): Allows filtering products based on associated Tag Values.

    • OR Logic (Same Tag): If you input multiple values belonging to the same Tag (e.g., White and Black under the Color tag), the search returns products that have either the White or Black value.
    • AND Logic (Different Tags): If you input values from different Tags (e.g., White and Black + the Shoes tag from the Footwear category), the system builds an AND expression between OR operators.
    • Example: (White OR Black) AND Shoes.

  • Filtering via Filters (filterIds): Supports both static identifiers and range filters.

    • Range Filters: To search for values within an interval (e.g., price), use the UUID[min;max] syntax.
    • Example: To find products with a cost between 10 and 50 using a filter with ID "UUID", you would pass UUID[10;50]. If one of the two fields is left empty, the system falls back to the value configured for that filter in the back-office.

  • Collection Filtering: Since collections are logical groupings of filters, searching by collection is performed by passing all the identifiers that compose it into the filterIds field.

  • Textual Filtering (search): Supports full-text and fuzzy search through OpenSearch integration.

    • Relevance (Scoring): The system prioritizes the product and variant names, calculating a total match score.
    • Coverage: The search analyzes product names, variant names, tag values, and attribute values. The more specific the metadata (Tags and Attributes), the more accurate the textual search results will be.

Data Integrity and Performance​

Catalog APIs read "pre-processed" data to guarantee lightning-fast response times.

Publication Status

Only published products belonging to an active store (with a valid Webround Commerce subscription) are accessible via the public Catalog APIs. If a product is not public, it will not appear in search results even if the ID is correct. If you cannot find a product after publication, try resetting its visibility status, ensuring it is set to visible.

Authentication​

  • Public Access: Consultation endpoints (Search, Detail, Reviews) are publicly accessible but always require store identification via header or parameter.
  • Context: Requests must include the store-id to load the correct price list and localization configurations.