Start exploring Nosto's GraphQL API on your account. GraphiQL is an in-browser IDE for exploring GraphQL. You don't need any access for using the GraphiQL Explorer.

Toy around, use the API and when you'd like API access to the endpoint for use through a library such as Apollo, please contact support.

Use the embedded GraphiQL explorer below to run queries. The GraphiQL Explorer is accessible at https://my.nosto.com/\[account-id]/graphql (please add your account ID).

Documentation

Documentation is a first-class citizen of GraphQL, and GraphiQL leverages it. The right-hand pane exists for you to explore the possible queries, mutations, fields, their types (if they’re required), the works. Even if your server doesn’t implement human-composed descriptions, you will always be able to explore the graph of possibilities.

Debugging

You don’t even have to read the documentation to discover our API. GraphiQL supports debugging as-you-type, giving hints and pointing out errors.

JSON Viewer

GraphiQL comes with a JSON viewer with all the niceties you’d expect: code folding, automatic indentation, copy support, and read-only so you won’t accidentally delete or edit.

GraphQL is a query language for APIs. What does this mean for you? Unlike regular SOAP or REST APIs, GraphQL gives you the ultimate flexibility in being able to specify in your API requests specifically what data you need and get back exactly that.

As a query language, it provides you with a lot of flexibility that most normal APIs will not. Without needing to recreate endpoints, you can provide developers with the same functionality as a bulk endpoint. Your queries will be cleaner and easier to understand by combining multiple queries into one request.

What’s the difference between GraphQL API and the regular API?

The regular API is very well structured and specifically defined. The endpoints have their set requests and responses and that’s what you get whether or not that matches your usage pattern. GraphQL lets you control all of this so that the way you consume the data matches exactly what you need.

This is both a pro and a con. If your use case does not require all of the data, GraphQL can speed up your requests as we do less work on the server-side to fulfill those requests. Conversely, if you need all of the data in one request, your requests could slow down as we do more work to fulfill these requests.

Should I use GraphQL over the regular API?

If you would like to access our intelligence engine, you must use GraphQL. The legacy REST APIs are primarily used for sending orders, products and exchange rates.

Limitations

Geo Segments:

Geo segments rely on the ability to determine the geographical location of the end customer. This typically requires a client-side script that can access the user's IP address. In case of a GraphQL only implementation, this should still be possible if the GraphQL calls are made directly from the end user to Nosto. If the calls are being proxied to a backend server and subsequently forwarded to Nosto, this will essentially hide the end-user's IP from the request and instead, send the backend server IP to Nosto, making it impossible to determine the geolocation of the end user.

The GraphQL endpoints provide functionality to make it easier to test against a real account.

Ignoring Test Requests

Every operation made against the GraphQL endpoints cause your website's data to be mutated. When doing performance testing or an equivalent, it is often necessary to exclude test traffic so as to not pollute your live account.

Using the header X-Nosto-Ignore: True will cause any traffic from being recorded. Queries and Mutations will work normally but any API calls containing this header will not be archived or accrue towards the statistics.

An example of how this header can be leveraged can be found on our Nosto's GraphQL Android Example app.

Debugging Requests

Every operation made against our GraphQL endpoint returns a unique request identifier contained in an X-Request-Id response header.

While we ensure that the APIs are as robust as possible if you do encounter an HTTP 5XX response from the endpoint, simply log the request identifier along with the error as the unique request identifier allows our engineers to troubleshoot the issue swiftly.

Mutations can be used to update the product catalog in Nosto. The updateProducts mutation allows you to update one or more products at a go.

Any validation errors in the product data are accessible in the response. The entire product object is accessible in the response too. In the event that a product validation error led to the product to not be updated, the response would contain the errors as well as the invalid product data.

The given example updates the product #101 and requests the details of the updated products and any associated errors.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation {
  updateProducts(products: [
    {
      productId: "101"
      url: "http://mridang.dev.nos.to:8890/product.htm"
      imageUrl: "https://example.com/product/sku-1.jpg"
      priceCurrencyCode: "EUR"
      price: 10
      skus: [
        {
          id: "sku-1"
          name: "One"
          availability: "InStock"
          price: 100
          listPrice: 111
          imageUrl: "https://example.com/product/sku-1.jpg"
        }
      ]
    }
  ]) {
    result {
      errors {
        field
        message
      }
      data {
        productId
      }
    }
  }
}
EOF

The given example updates the price of #101 and requests the details of the updated products and any associated errors.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation {
  updateProducts(products: [
    {
      productId: "101"
      url: "http://mridang.dev.nos.to:8890/product.htm"
      price: 10
    }
  ]) {
    result {
      errors {
        field
        message
      }
      data {
        productId
      }
    }
  }
}
EOF

In order to use the GraphQL endpoints, you'll need to authenticate yourself. You will need a Apps token to access this endpoint. Only a subset of the endpoints can be accessed with a public token. This makes it possible to access functionality like querying product recommendations in an environment where it's not possible to protect the token, for example in a web browser. Each publicly accessible endpoint is denoted in the embedded documentation inside the playground.

Note: Nosto does not rate-limit the API usage but follows a fair-use policy. Nosto reserves the right to revoke API access for any abusive API usage patterns.

Sending JSON GraphQL queries

You can send your GraphQL requests as JSON to our API and have it correctly interpolate variables passed into it. To do so, set the Content-Type header to application/json.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/json' \
-d @- << EOF
{
  "query": "query { recos (preview: false, image: VERSION_7_200_200) { toplist(hours: 168, sort: BUYS, params: { minProducts: 1 maxProducts: 10 } ) { primary { name productId } } } }"
}
EOF

Sending raw GraphQL queries

If you want to send raw GraphQL queries to the API, you can still do so but you must set the Content-Type header to application/graphql.

Note: If you do not set the correct Content-Type header, the request will be interpreted as JSON and will fail.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  recos (preview: false, image: VERSION_7_200_200) {
    toplist(hours: 168, sort: BUYS, params: {
      minProducts: 1
      maxProducts: 10
    }) {
      primary {
        name
        productId
      }
    }
  }
}
EOF

Using Fetch

You can use the browser's fetch API to request data from GraphQL. You will need to authenticate yourself and set the appropriate content-type headers.

Sending JSON GraphQL queries

You can send your GraphQL requests as JSON to our API and have it correctly interpolate variables passed into it. To do so, set the Content-Type header to application/json.

const body = JSON.stringify({
  query: `
  query {
    order(id: "5192009") {
      number
      reference
      items {
        productId
        skuId
        unitPrice
        priceCurrencyCode
        quantity
      }
      recos(preview: true, image: VERSION_1_170_170) {
        related(params: {
          minProducts: 1,
          maxProducts: 5
        }) {
          primary {
            productId
            name
            price
          }
        }
      }
    }
  }
`});

fetch('https://api.nosto.com/v1/graphql', {
  method: 'POST',
  headers: new Headers({
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa(":" + "<token>")
  }),
  mode: 'cors',
  body
})
  .then((response) => response.json())
  .then((json) => {
    console.log(json);
  });

Sending raw GraphQL queries

If you want to send raw GraphQL queries to the API, you can still do so but you must set the Content-Type header to application/graphql.

**NOTE:**If you do not set the correct Content-Type header, the request will be interpreted as JSON and will fail.

const body = `
query {
  order(id: "5192009") {
    number
    reference
    items {
      productId
      skuId
      unitPrice
      priceCurrencyCode
      quantity
    }
    recos(preview: true, image: VERSION_1_170_170) {
      related(params: {
        minProducts: 1,
        maxProducts: 5
      }) {
        primary {
          productId
          name
          price
        }
      }
    }
  }
}
`;

fetch('https://api.nosto.com/v1/graphql', {
  method: 'POST',
  headers: new Headers({
    'Content-Type': 'application/graphql',
    'Authorization': 'Basic ' + btoa(":" + "<token>")
  }),
  mode: 'cors',
  body
})
  .then((response) => response.json())
  .then((json) => {
    console.log(json);
  });

The mutation methods allow you to change the session on Nosto's end and request personalized recommendations. Each mutation operation allows you to update the cart and customer information, all while giving you access to recommendations for the sessions.

Any mobile experience built atop Nosto's GraphQL API should use the mutation operation as it feeds data into to the recommender systems while providing personalization data.

_The given example updates the customer's information and his current shopping cart contents sends an event that the customer is currently viewing product number 400 and requests the personalized recommendations associated with a given product for him aliased as front_page_1.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation MySession {
  updateSession(id: "ad8f0d0e-1156-4df2-b385-10e03f8f8a44",
    params: {
      customer: {
        firstName: "John"
        lastName: "Doe"
        marketingPermission: true
        customerReference: "319330"
      }
      event: {
        type: VIEWED_PRODUCT
        target: "400"
      }
      cart: {
        items: [
          {
            productId: "100",
            skuId: "100-1",
            name: "#100",
            unitPrice: 199,
            priceCurrencyCode: "EUR",
            quantity: 1
          },
          {
            productId: "200",
            skuId: "200-1",
            name: "#200",
            unitPrice: 299,
            priceCurrencyCode: "EUR",
            quantity: 2
          },
          {
            productId: "300",
            skuId: "300-1",
            name: "#300",
            unitPrice: 399,
            priceCurrencyCode: "EUR",
            quantity: 3
          },
        ]
      }
    }) {
      id,
      recos (preview: false, image: VERSION_8_400_400) {
        front_page_1: related(productIds: ["525834092559"],
          relationship: VIEWED_TOGETHER
          params: {
            minProducts: 3,
            maxProducts: 5
        }) {
        primary {
          productId
        }
      }
    }
  }
}
EOF

Mutations can be used to update the category listing in Nosto. The upsertCategories mutation allows you to update one or more category at one go. If the category doesn't already exist, a new one is created.

A category can have the following fields:

• id The category identifier. If a category with this id doesn't already exist, a new one is created.

• name The displayed name for the category.

• urlPath The path that can be used to generate the URL of the category listing.

• available If the category is visible on the store. This can be set to false to soft delete the category in an upsert.

Some stores support hierarchical categories i.e. a category may have parent and child categories. The following fields can be used for hierarchical categories:

• parentId The identifier of the parent category.

• fullName The name of every category in the hierarchy.

Creating a session

When a new user comes to the app, you can use this method to get a new session. It will return you a customer-id that can save on the device and use for future requests. This would be ideal.

Updating a session

When a customer logs in, you can update the existing customer with the customer-reference. This would merge the online and mobile sessions. If not needed, I would omit this for now.

Working with recommendations

On the Product Page

In order to use the GraphQL session mutation to fetch recommendations for your search page, the event, in this case, must be VIEWED_PRODUCT and you should specify the product-identifier of the current product being viewed.

On the Category Page

In order to use the GraphQL session mutation to fetch recommendations for your category page, the event, in this case, must be VIEWED_CATEGORY and you should specify a fully qualified category path of the current category. For example, if you have a category called "Dresses" under the category "Women", the FQCN would be "/Women/Dresses".

On the Search Page

In order to use the GraphQL session mutation to fetch recommendations for your search page, the event, in this case, must be SEARCHED_FOR and you should specify the search term of the query.

On the Cart Page

In order to use the GraphQL session mutation to fetch recommendations for your cart or checkout page, the event, in this case, must be VIEWED_PAGE and you should specify a fully qualified URL of the page as the target.

On the Front Page

In order to use the GraphQL session mutation to fetch recommendations for your home or front page, the event, in this case, must be VIEWED_PAGE and you should specify a fully qualified URL of the page as the target

Attribution of Recommendation Results

Recommendation results can be attributed to events by setting a session event's ref to the recommendation result's resultId.

Here is an example of some recommendations for a front page. You can see recommendation result's resultId is "frontpage-nosto-1".

If a customer selects to view the Cool Kicks product, you can generate the following request. Note that the event's ref is set to "frontpage-nosto-1".

GraphQL from mobile applications

When making GraphQL queries from mobile applications, it's essential to define the user agent string in your HTTP headers. Ideally, the user agent should represent the mobile environment, including details such as the platform, device type, and application version. Avoid using terms like "bot" in the user agent string, as this might lead to unintended behavior or rejection of the query/session. Sending an empty user agent will also lead to be catch by the bot detection mechanism.

Mutations can be used to update the email identities in Nosto. An "identity" is the personal information associated with an email address.

Upserting Identities

The upsertIdentity mutation allows you to upsert the details of an identity. The given example updates the customer attributes for the email john.doe@nosto.com and requests the details of all the attributes of the identity.

If the identity for john.doe@nosto.com does not exist, a new identity will be created.

Note: If a specified attribute already exists on that identity, it will be overwritten.

What can identity attributes be used for?

Deleting Identities

There is currently no way to delete an identity.

The query methods allow you to fetch basic recommender data and does not require any sessions. Query operations are light and do not give you the benefit of personalization but can be used to fulfill simple use cases e.g. an in-store display that always shows the top 10 viewed products.

_The given example simply fetches products related to a given search term aliased as q_related and also fetches the most viewed products within the last week.

When a user places an order onsite or offsite, you must send the conversion tracking information to Nosto.

Tracking orders by customer id looks like the following:

Working with recommendations

On the Order-Confirmation Page

To fetch the recommendations for the order-confirmation page, simply use the GraphQL field called forOrderPage to fetch all the recommendations for the order-confirmation page.

If you would like to update the order-status for a given order, you can do so using the following request.

You can query identities using the GraphQL Identities endpoint. An "identity" is the personal information associated with an email address.

So long as you are able to specify the email address, you will be able to query the identity, its associated customer affinity and the personalized recommendations for that identity.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  identity(email:"john.smith@example.com") {
    email,
    attributes {
      name,
      value
    }
    recos(preview: true, image: VERSION_ORIGINAL) {
      history(params: {
        minProducts: 3,
        maxProducts: 10,
        showRelatedProducts: true,
        skipProductsInCart: true,
        skipBoughtProducts: true
      }) {
        primary {
          url
          imageUrl
        }
      }
    }
  }
}
EOF

What can identity attributes be used for?

The attributes associated with an identity can be used to segment users. This works similarly to how the attributes can be leveraged when importing them via a CSV.

You can query all the configured segments using the GraphQL Segments endpoint. You are able to query all the names and identifiers of the segments.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  segments{
    segments{
      id,
      name
    }
  }
}
EOF

Sample Output

{
  "data": {
    "segments": {
      "segments": [
        {
          "id": "5a497a000000000000000001",
          "name": "First-Time Visitors"
        },
        {
          "id": "5b71f1500000000000000006",
          "name": "Returning Visitors"
        },
        {
          "id": "5a497a000000000000000002",
          "name": "Prospects"
        },
        {
          "id": "5a497a000000000000000003",
          "name": "First-Time Customers"
        },
        {
          "id": "5a497a000000000000000004",
          "name": "Repeat Customers"
        },
        {
          "id": "5a497a000000000000000005",
          "name": "Loyal Customers"
        },
        {
          "id": "5a497a000000000000000000",
          "name": "All Customers"
        }
      ]
    }
  }
}

You can query orders using the GraphQL orders endpoint. So long as you are able to specify the order number or an external order reference, you will be able to query the order.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  order(id: "M2_2") {
    number
    reference
    items {
      productId
      skuId
      unitPrice
      priceCurrencyCode
      quantity
    }
    recos(preview: true, image: VERSION_1_170_170) {
      related(params: {
        minProducts: 1,
        maxProducts: 5
      }) {
        primary {
          productId
          name
          price
        }
      }
    }
  }
}
EOF

List Products

Querying products gives access to Nosto's product catalogues current state. It can be useful for backend integration and verification purposes. It is not meant for online use purposes as it doesn't include any concepts related to user sessions or attribution, for those refer to GraphQL For Headless

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  products(
    limit: 5
    offset: 0
    sort: {field: PRICE, reverse:true},
    filter: {categories: "shoes"}
  ) {
    products {
      productId
      url
      price
      categories
    }
  }
}
EOF

Query by Product ID

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
query {
  product(id: "5358") {
    productId
    name
    url
    price
    listPrice
    imageUrl
    attributes {
      key
      value
    }
    skus {
      name
      price
      listPrice
      availability
      imageUrl
      url
    }
  }
}
EOF

Search GraphQL API uses different API endpoint. For more information see:

GraphQL is a query language for the APIs for getting your data. It is an alternative for the REST APIs. It is not specific to a single platform and works for all type of clients including Android, iOS or the web. It stands between your server and client and helps you to query your data in a more optimized way.

Building for Android

If you would like to leverage Nosto's intelligence engine in your Android app, please see our example app and the docs.

Building for iOS

Leveraging Nosto's intelligence engine on iOS is just as easy as on Android. While an example app is yet to be provided, please read the Apollo docs.

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:

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&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:

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:

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:

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

You can generic recommendations using the GraphQL orders endpoint. The recommendations offered here don't use sessions so they aren't personalized but still offer enough flexibility to support a multitude of use-cases.

Fetching toplists recommendations

The endpoint can be used to fetch toplist recommendations i.e. best-sellers. Toplists recommendations are either sorted by views or buys.

Fetching random recommendations

The endpoint can be used to fetch random recommendations i.e. previews. Random recommendations are a totally randomized selection of products and often used for testing purposes.

Fetching related recommendations

The endpoint can be used to fetch related recommendations i.e. cross-sellers. Cross-sell recommendations allow you fetch related products to a given set of products.

Example: If you were to use this to add recommendations to a product page, the productIds parameter would be a single-item array containing the product identifiers of the product that is being viewed.

Example: If you were to use this to add recommendations to an order-follow email, the productIds parameter would be an array containing the product identifiers of the products that were purchased.

Fetching search recommendations

The endpoint can be used to fetch recommendations related to a search term.

Example: If you were to use this to add recommendations to a search page, the term parameter would be the entire search term as queries by the user.

Note: This endpoint cannot be used for building auto-complete style integrations.

Add inclusive or exclusive filters

In case some cases it is desired to filter products by their properties. include and exclude fields of primary should be used to achieve this. The former will filter only the products that match the specified attribute, the later will filter out the products that match the attribute.

include field expects a type of InputIncludeParams, whose attributes are

exclude field expect type InputFilterParams whose attributes are:

Here is an example of a query including filters

Nosto's GraphQL APIs can be used for simplified implementations for headless frontends. While we recommend using our JS API for use in headless environments, there are scenarios where a GraphQL based implementation might be more fruitful.

🚨Implementing Nosto over GraphQL will not allow you to leverage the entire Nosto suite. When Nosto is implemented over tagging and/or Javascript APIs it can modify web-pages automatically with Javascript, which means many things can work out of the box. For example inserting recommendations dynamically onto a webpage, rendering of templates, tracking of user behaviour. GraphQL instead is only an API which can be called from anywhere, so it cannot directly run Javascript or modify web-pages, instead those need to be implemented by the caller of the API. The following features are not available through GraphQL API:

• Facebook Ads: As the pixel events aren't dispatched.

• Content Personalization: As the GraphQL API only handles the personalization and not onsite experiences.

• Popups: As the GraphQL API only handle the personalization and not onsite experiences.

• AB-testing & dynamic placements: Because the current GraphQL API works with recommendation identifiers directly and not through placements.

Each customer who visits a site is uniquely identified with a session identifier. When a new customer comes to the site, a GraphQL session mutation call must be made to initiate a session. The resultant session identifier must be persisted and reused for all consecutive calls.

💡The session-duration is 30 minutes from the last activity.

We recommend using the following flow to creating and resuming sessions.

1. Read the session-identifier from the cookie.

2. If the session-identifier doesn't exist, initiate a new session and store the resultant session identifier in a cookie.

3. Read the session identifier from the cookie, and leverage the mutations for the outlined page types.

Starting a new session

In order to start a new session when a session-identifier doesn't exist, you'll need to use the newSession mutation

The newSession mutation will return a unique session-identifier that you must persist.

⚠️ How you persist the session-identifier is entirely dependant upon your implementation. For example, you can persist it into a cookie or even application storage.

Using a session

If you already have a session-identifier, you can pass that using the updateSession mutation.

The example below is a generic example of how you update a session and pass the appropriate event to Nosto but in practice, you'll be using one of the page-specific mutations as shown in the section "Implementing on pages".

Implementing on pages

In order to use Nosto the different pages, you'll need to make the appropriate mutations for the different page types.

Every page-specific mutation requires you to pass the event for the specific page. These events are used to pass signals to Nosto's intelligence engine. Each of the page-specific mutations also allows you to fetch the recommendations for the given page type.

Sending the cart

When you mutate a session, it is imperative that you send the full cart contents.

If the current shopping cart is empty, this can be omitted.

Adding to cart with attribution

If you want to add a new item to the cart, without any page changes you should pass a new parameter of skipEventsthis will prevent analytics to count new page view event while still adding product to the cart.

if the add to cart happens as a result of a click on a recommendation element, you must pass the attribution along with the event as the ref parameter.

Sending the customer

When you mutate a session, it is imperative that you send the details of the currently logged-in customer. If no customer if currently logged in, this can be omitted.

Sending attribution parameters

When navigating between pages, if the navigation happens as a result of a click on a recommendation element, you must pass the identifier as part of the route and on the next page load, read the attribution parameter and pass it along with the event as the ref parameter.

⚠️ If you do not pass the attribution parameter, the recommendations statistics will be inaccurate but will not affect the quality of the recommendations.

Previewing the recommendations

All default the recommendation results are returned when the recommendations are enabled and the account is a live account. If you would like to preview the recommendations, all the recommendation fields accept a boolean isPreview parameter.

⚠️ Any recommendation requests when the preview mode is enabled do not accrue towards the statistics or skew the product relations.

On your home page

Sending the event

In order to use the GraphQL session mutation to fetch recommendations for your home or front page, the event, in this case, must be VIEWED_PAGE and you should specify a fully qualified URL of the home page as the target.

The pages query for home page also supports filtering recommendation for a specific Slot ID using the slotIds parameter in forFrontPage request, as shown below:

Note: slotIds accepts an array of String parameters

Fetching Recommendations

The forFrontPage field will return the result of all the recommendations that are configured for the front page. When slotIds filtering is used, the result will only contain the recommendations for the specified Slot Ids.

On your Category pages

Sending the event

In order to use the GraphQL session mutation to fetch recommendations for your category page, the event, in this case, must be VIEWED_CATEGORY and you should specify a fully qualified category path of the current category. For example, if you have a category called "Dresses" under the category "Women", the FQCN would be "/Women/Dresses".

The pages query for category page also supports filtering recommendation for a specific Slot ID using the slotIds parameter in forCategoryPage request, as shown below:

Note: slotIds accepts an array of String parameters

Fetching Recommendations

The forCategoryPage field will return the result of all the recommendations that are configured for the category page. When slotIds filtering is used, the result will only contain the recommendations for the specified Slot Ids.

On your Product pages

Sending the event

In order to use the GraphQL session mutation to fetch recommendations for your search page, the event, in this case, must be VIEWED_PRODUCT and you should specify the product-identifier of the current product being viewed.

The pages query for product page also supports filtering recommendation for a specific Slot ID using the slotIds parameter in forProductPage request, as shown below:

Fetching Recommendations

The forProductPage field will return the result of all the recommendations that are configured for the product page. When slotIds filtering is used, the result will only contain the recommendations for the specified Slot Ids.

On your search page

Sending the event

In order to use the GraphQL session mutation to fetch recommendations for your search page, the event, in this case, must be SEARCHED_FOR and you should specify the search term of the query.

The pages query for search page also supports filtering recommendation for a specific Slot ID using the slotIds parameter in forSearchPage request, as shown below:

Fetching Recommendations

The forSearchPage field will return the result of all the recommendations that are configured for the search page. When slotIds filtering is used, the result will only contain the recommendations for the specified Slot Ids.

On your cart/checkout page

Sending the event

In order to use the GraphQL session mutation to fetch recommendations for your cart or checkout page, the event, in this case, must be VIEWED_PAGE and you should specify a fully qualified URL of the cart page as the target.

The pages query for cart page also supports filtering recommendation for a specific Slot ID using the slotIds parameter in forCartPage request, as shown below:

Fetching Recommendations

The forCartPage field will return the result of all the recommendations that are configured for the front page. When slotIds filtering is used, the result will only contain the recommendations for the specified Slot Ids.

On the order page

Sending the event

In order to use the GraphQL session mutation to fetch recommendations for your cart or checkout page, you must use a different mutation as compared to the rest of the pages.

⚠️ The customer, in this case, is the details of the customer making the purchase.

The pages query for order page also supports filtering recommendation for a specific Slot ID using the slotIds parameter in forOrderPage request, as shown below:

Fetching Recommendations

The forOrderPage field will return the result of all the recommendations that are configured for the order-confirmation page. When slotIds filtering is used, the result will only contain the recommendations for the specified Slot Ids.

Other page type fields are:

forNotFoundPage - 404 page

forLandingPage - landing page

forGeneralLayoutPage - general layout page