Techdocs
  • Introduction
  • Implementing Nosto
    • Implement on your website
      • Manual Tagging - Essentials
        • Setting up your account
        • Adding the Nosto Script
        • Adding the Cart Tagging
        • Adding the Customer information
        • Adding the Product Tagging
          • Default Product Tagging
          • Basic Tagging
        • Adding the Category/Brand Tagging
        • Adding the Search Tagging
        • Adding the Order Tagging
        • Defining Nosto placements
        • Tagging your page types
      • Advanced Usage
        • Extending tagging with SKUs
        • Adding support for multi-currency
        • Adding support for customer group pricing
      • FAQ
    • Implement on native mobile
    • Implement on a physical store
    • Implement Search & Categories
      • Using Search Templates
        • Using Search Templates
        • Implementing Search page
        • Implementing Autocomplete
        • Implementing Category pages
        • Testing & deployment
        • FAQ
      • Using the API
        • Use the Search & Categories API
        • Implement Search results page
        • Implement Autocomplete
        • Implement Category pages
        • FAQ
      • Using the JavaScript Library
        • Implement Autocomplete using the Nosto Autocomplete library
          • Installation
          • Initialization
            • Render results
            • Submit search
          • Create Autocomplete template
          • Further reading
    • Check your setup
    • Template customization
      • Starting points
      • Product cards
      • Styling
      • Scripting
  • APIs
    • GraphQL
      • The Playground
      • Using the API
      • Testing and Debugging
      • Using Mutations
        • Updating Products
        • Updating Categories
        • Updating Identities
        • GraphQL: Onsite Sessions
        • Working with Orders
          • GraphQL: Placing Orders
          • GraphQL: Updating Order Statuses
      • Using Queries
        • Querying Products
        • Querying Identities
        • Querying Orders
        • Querying Recommendations
        • Querying Segments
        • Querying Search
        • Querying Category Merchandising Products (CM 1.0)
      • For iOS & Android
      • For Headless
    • REST
      • GDPR
        • Redacting customer data
        • Initiating data takeouts
      • Customers
        • Blacklisting Customers
        • Toggling marketing consent
      • Products
        • Updating Products
        • Discontinuing Products
        • Recrawling Products
      • Other
        • Updating Rates
    • Frontend
      • Session API
        • Terminology
        • Setting up
        • Managing Sessions
        • Handling Placements
        • Tracking Events
        • Leveraging Features
        • Record Attribution
        • Advanced Usage
          • Supporting opt-out and do-not-track
          • Using external session identifiers
          • Adding support for multi-currency
          • Adding support for customer group pricing
        • FAQ
      • JS API
        • Initializing Nosto
        • Recommendations
          • Loading Recommendations
          • Recommendation Callbacks
          • Setting up dynamic filtering
          • Sending Product-View Events
          • Sending Add to Cart-Events
        • Popups
          • Listing Popup Campaigns
          • Opening a Popup
          • Enabling & Disabling Popups
          • Popup Callbacks
        • Advanced Usage
          • Sending email addresses to Nosto
          • Manually segmenting users
          • Dynamically sending the cart content
          • Sending Customer Information
        • Record Attribution
      • Open Source
        • Nosto JS
        • Search JS
        • Nosto React
        • Web Components
          • Loading Web components
  • User Generated Content
    • UGC Techdocs
  • 3rd party data integrations
    • Shopify
    • Magento 2
    • Magento
    • BigCommerce
    • Shopware 6
    • Shopware 5
    • Prestashop
    • Salesforce
    • PHP-SDK
Powered by GitBook
On this page
  • Session Lookup
  • Attribution
  • Automatic Attribution
  • Manual Attribution
  • Event handling
  • Pagination
  • Filtering Results

Was this helpful?

Export as PDF
  1. APIs
  2. GraphQL
  3. Using Queries

Querying Category Merchandising Products (CM 1.0)

PreviousQuerying SearchNextFor iOS & Android

Last updated 7 months ago

Was this helpful?

This documentation is only for the implementation of CM 1.0 and most likely this doc shouldn't be used anymore. If you'd like to implement CM 2.0, please check this . If you're not sure which version you'd like to implement, please contact your technical solutions manager or our support.

Nosto's category merchandising APIs are meant to be used for resorting your existing product listing pages. It has support for listing the products in the order defined within Nosto for different categories, including paging and filtering support. It doesn't support taking over the product listing pages fully as it doesn't include support for creating category specific filters and calculating their facet counts. The expected implementation leveraging these APIs would keep on using their current solution for building most of the product list pages, but swap the shown products with the information retrieved from this APIs results.

You can query using the query below:

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  session(by: BY_CID, id: $customerId) {
    id
    recos(
      preview: false,
      image: VERSION_ORIGINAL,
      addAttributionParameters: true) {
      category(
        category: $categoryName,
        minProducts: 1,
        maxProducts: 10
      ) {
        primary {
          productId
          url
        }
        batchToken
        totalPrimaryCount
        resultId
      }
    }
  }
}
EOF

Session Lookup

Attribution

Automatic Attribution

Setting the addAttributionParameters parameter to true, causes attribution parameters to be automatically rendered in product URLs. For example, the url https://example.com/product becomes https://example.com/product?nosto_source=cmp&amp;nosto=5e5e09f060b232790cbbccbf. These parameters allow our client script to track the performance of Category Merchandising results.

Manual Attribution

If you wish to handle attribution parameters manually, the addAttributionParameters parameter can either be set to false or can be omitted.

Product views resulting from clicking products of a category listing need to contain the required attribution parameters:

  • type: VIEWED_PRODUCT

  • target: (product id)

  • ref: (resultId from the category merchandising response)

  • refType: CATEGORY_MERCHANDISING

For example, given the following category merchandising response:

{
  "data": {
    "updateSession": {
      "recos": {
        "category": {
          "resultId": "623473861055d80027efe482",
          "primary": [{
            "productId": "9497180547",
            "name": "Cool Kicks",
            "url": "https://example.com/products/cool-kicks"
          }]
        }
      }
    }
  }
}

If a customer clicks on Cool Kicks, the following GraphQL query should be sent to fetch the product's details and to attribute the product view to the category merchandising result:

mutation($sessionId: String!) {
  updateSession(by: BY_CID, id: $sessionId, params: {
    event: {
      type: VIEWED_PRODUCT
      target: "9497180547"
      ref: "623473861055d80027efe482"
      refType: CATEGORY_MERCHANDISING
    }
  }) {
    primary {
      productId
      url
      name
      description
      priceText
    }
  }
}

Event handling

Graphql calls using Category Merchandising methods are treated as a category view by default. This behavior can be changed by including skipVCEvent: true into the graphql request. All product URLs on a category page must be appended with #nosto\_cmp fragment. An example of such a product URL would be www.test-store.com/product1#nosto\_cmp where #nosto\_cmp is the added fragment.

Pagination

The batchToken can be used the next batch of results. This is useful if you only wish to fetch the first 10 products when there may be thousands of results. To fetch the next batch, use the batchToken in the next query like in the example below:

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  session(by: BY_CID, id: $customerId) {
    id
    recos(
      preview: false,
      image: VERSION_ORIGINAL,
      addAttributionParameters: true) {
      category(
        category: $categoryName,
        minProducts: 1,
        maxProducts: 10,
        batchToken: "n200MjA2NDc0OTUyNzg1+z/wAAAAAAAA/w=="
      ) {
        primary {
          productId
          url
        }
        batchToken
        totalPrimaryCount
        resultId
      }
    }
  }
}
EOF

If you wish to skip the first number of pages, you can use the skipPages parameter instead of the batchToken. A page size is calculated from the maxProducts parameter.

Filtering Results

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  session(by: BY_CID, id: $customerId) {
    id
    recos(
      preview: false,
      image: VERSION_ORIGINAL,
      addAttributionParameters: true) {
      category(
        category: $categoryName,
        minProducts: 1,
        maxProducts: 10,
        include: {
          customFields: [{
            attribute: "color",
            values: ["white"]
          }]
        }
        exclude: {
          discounted: true
        }
      ) {
        primary {
          productId
          url
        }
        batchToken
        totalPrimaryCount
        resultId
      }
    }
  }
}
EOF

In order to be able to provide personalized results, we will need to look up a session either by id or by reference. You read more about managing sessions on our wiki page.

Results can be filtered by specifying the include and exclude parameters. You can explore more parameters in the

documentation
category merchandising products
onsite sessions
GraphQL Playground