BrowseCategory resource - browsing a category 'page'

This is a read-only resource that allows you to retrieve everything that would usually be displayed on a category page including:

  • Category details: code; name; description; image etc
  • Category link
  • A list of products that are in the specified category (or any of its descendant categories)
  • Each product has a list of all product information required to display it including:
    • General information: sku; title; image/thumb
    • Link to the product page
    • The calculated price of the product. Note: if a _session_token has been passed, if the user is logged in, this price will reflect any user or group discounts as well as anything else that would affect the pricing on the website (including multi-currency, applied coupon codes etc).
      • Pricing is one of the more expensive things to calculate, so to avoid sluggish responses from the API, make sure you utilise the pagination feature if you are expecting large recordsets to be returned, or finding the API response a bit slow for your requirements.
    • Any promotion information - discount & featured message
    • Any options, detail about each option, default selected settings
  • If the website uses access control, only products that the user would usually have access to will be visible. If the website requires login to access certain products a _session_token will need to be passed in the querystring to ensure that users logged in state is carried across to your request. See the API session documentation for more information.
@TODO: there currently is no way to request quantity pricing for a product.

Overview

Supported HTTP "verbs"

VERB HTTP Method Description
fetch GET /api/v3/BrowseCategory/$category_code Browse a category
list NOT SUPPORTED
create/update NOT SUPPORTED
update NOT SUPPORTED

Supported parameters

Parameter Values Description
_with_products 0 (default) or 1 Include products
_with_prices 0 (default) or 1 Include prices.
_with_product_fields Colon seperated list of product fields Product fields to include
_search search string Search for products within the category (note this parameter does not support the 'SQL like' filtering that the search parameter normally support)
_start integer index to start from (zero-based). BrowseCategory is built for pages of results, so this number must be divisible by _results (it will round to the nearest page number) Standard API Pagination
_results Number of results to return Standard API Pagination

Standard category retrieval

To pull data from this resource submit a GET request to /API/V3/BrowseCategory/$code where $code is the category code.

By default a category retrieval will only retrieve the category data (with no product listing). To retrieve & control the product listing, use the options listed below.

Retrieving products

To include a list of products within the category, include the argument _with_products=1 in the querystring. E.g. /API/V3/BrowseCategory/4012?_with_products=1.

The resulting list of products will include all products in the specified category, but also all products in any of the category tree beneath this category.

Retrieving products with price

To include a list of products within the category with a price object, include the argument _with_products=1 and _with_prices=1 in the querystring. E.g. /API/V3/BrowseCategory/4012?_with_products=1&_with_prices=1.

Pagination

By default a product retrieval will retrieve the category page default page size as configured by the website.

For larger ecommerce websites, this product list can grow quite large for categories high up the category tree. It is therefore important in these situations to paginate the results.

This API supports the standard pagination arguments used in the rest of the API (_start=$index&_results=$number_of_results_to_return) to determine which page of results to retrieve.

So /API/V3/BrowseCategory/4012?_with_products&_start=0&_results=20 would retrieve the first 20 products for category 4012, along with all of the category data.

Search Product within a category

To search a product within a category, specify a querystring parameter called search with the phrase you want to limit the results to. E.g. /API/V3/BrowseCategory/4012?_with_products=1&_search=foo.

The resulting list of products will include all products within the category that match the specified search phrase.

If an API result is limited by a search phrase, the specified phrase will be included in the results under a node called search.

Later pages of products

If you request a page of products > 1, the system will assume you already have all of the category data from your first request. Because this data does not change, we will not keep sending it back to you every page request. So /API/V3/BrowseCategory/4012?_with_products&_start=20&_results=20 will return results 21-40, and no category data aside from the essentials (code etc).

Example response

The following response is an example response from a website selling linen products using a fake url:

https://www.mysite.net/API/V3/BrowseCategory/00411?_with_products=1&_start=0&_results=3

<?xml version="1.0" encoding="utf-8" ?>
<ResultSet page="1" session="yjipIL8BeUWxrFq" totalResults="42" totalResultsReturned="3" xmlns="http://www.zeald.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.zeald.com https://www.mysite.net/API/V3/BrowseCategory.xsd">
    <Category href="https://www.mysite.net/API/V3/BrowseCategory/00411" id="Ecommerce::Category00411">
        <Product href="https://www.mysite.net/API/V3/EcommerceProduct/03984" id="Ecommerce::Product::03984">
            <default_options></default_options>
            <discount></discount>
            <featured></featured>
            <inactive>0</inactive>
            <link>https://www.mysite.net/shop/Sheets/Double/Blossom_Comforter/x_sku/03984.html</link>
            <option>
                <code>101260</code>
                <description></description>
                <group>Sizes</group>
                <height></height>
                <label>Sizes</label>
                <sort>10</sort>
                <value>
                    <code>Cushion</code>
                    <label>Cushion (60cmx40cm) each</label>
                </value>
                <value>
                    <code>Comforter</code>
                    <label>Comforter (200cmx150cm)</label>
                </value>
                <widget>select</widget>
                <width></width>
            </option>
            <option_display_type>seperate</option_display_type>
            <option_type>Simple</option_type>
            <sku>03984</sku>
            <stock_message></stock_message>
            <stock_quantity>5</stock_quantity>
            <image>https://www.mydomain.nz/images/items/blossom-comforter-LR.jpg</image>
            <thumb>https://www.mydomain.nz/images/thumb/blossom-comforter-LR.jpg</thumb>
            <title>Rabo Sheets - Blossom Cushion and Comforter</title>
        </Product>
        <Product href="https://www.mysite.net/API/V3/EcommerceProduct/04238" id="Ecommerce::Product::04238">
            <default_options></default_options>
            <discount></discount>
            <featured></featured>
            <inactive>0</inactive>
            <link>https://www.mysite.net/shop/Sheets/Double+-+Ocean+Comforter++Pillowcases+and+Euros+sold+separately/x_sku/04238.html</link>
            <option>
                <code>04238-Sizes</code>
                <description></description>
                <group>sizes</group>
                <height></height>
                <label>Sizes</label>
                <sort>10</sort>
                <value>
                    <code>EuropeanPillowcase</code>
                    <label>European Pillowcase (65 x 65cm) (Each)</label>
                </value>
                <value>
                    <code>Cushion</code>
                    <label>Cushion (60cmx40cm) each</label>
                </value>
                <value>
                    <code>Comforter200</code>
                    <label>Comforter (200cmx150cm)</label>
                </value>
                <value>
                    <code>Comforter240</code>
                    <label>Comforter (240cmx150cm)</label>
                </value>
                <widget>select</widget>
                <width></width>
            </option>
            <option>
                <code>04238-Colour</code>
                <description></description>
                <group>colour</group>
                <height></height>
                <label>Colour</label>
                <sort>20</sort>
                <value>
                    <code>R</code>
                    <label>Red</label>
                </value>
                <value>
                    <code>B</code>
                    <label>Blue</label>
                </value>
                <widget>select</widget>
                <width></width>
            </option>
            <option_display_type>seperate</option_display_type>
            <option_type>Simple</option_type>
            <sku>04238</sku>
            <stock_message>More back on Monday</stock_message>
            <stock_quantity>0</stock_quantity>
            <image>https://www.mydomain.nz/images/items/Black large comforter and cushion LR-222.1.jpg</image>
            <thumb>https://www.mydomain.nz/images/thumb/Black large comforter and cushion LR-222.1.jpg</thumb>
            <title>Rabo Sheets - Black large Comforter</title>
        </Product>
        <Product href="https://www.mysite.net/API/V3/EcommerceProduct/01748" id="Ecommerce::Product::01748">
            <default_options></default_options>
            <discount></discount>
            <featured></featured>
            <inactive>0</inactive>
            <link>https://www.mysite.net/shop/Sheets/Double/super-euros/x_sku/01748.html</link>
            <option_display_type>seperate</option_display_type>
            <option_type>Simple</option_type>
            <options></options>
            <sku>01748</sku>
            <image>https://www.mydomain.nz/images/items/super-euros.jpg</image>
            <thumb>https://www.mydomain.nz/images/thumb/super-euros.jpg</thumb>
            <title>Rabo Sheets - Super Euros</title>
            <stock_message></stock_message>
            <stock_quantity>13</stock_quantity>
        </Product>
        <code>00411</code>
        <description>&lt;p&gt;Express your style with beautiful Sheets by Rabo sheets. Super comfy - you won't regret it!

&lt;h5 style=&quot;text-align: center;&quot;&gt;FREE SHIPPING ON ALL NEW ZEALAND ORDERS&lt;/h5&gt;</description>

        <!-- an optional image for this category -->
        <image>https://www.mydomain.nz/images/items/category-image.jpg</image>
        <link>https://www.mysite.net/shop/Sheets/Double/x_cat/00411.html</link>
        <name>Rabo Sheets</name>
    </Category>
</ResultSet>