1 of 8

Using Mutations

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

Updating Products

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

Updating Categories

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.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation {
  upsertCategories(categories: [{
    id: "123",
    name: "Shoes",
    parentId: "456",
    urlPath: "/categories/mens/shoes",
    fullName: "/Mens/Shoes",
    available: true
  }]) {
    categoryResult {
      errors {
        field
        message
      }
      category {
        id
        name
        parentId
        urlPath
        fullName
        available
      }
    }
  }
}
EOF

Updating Identities

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.

curl -0 -v -X POST https://api.nosto.com/v1/graphql \
-u ":<token>" \
-H 'Content-Type: application/graphql' \
-d @- << EOF
mutation {
  upsertIdentity(identity: {
    email: "john.doe@nosto.com",
    attributes: [
      {name: "loyalty-tier", value: "Gold"},
      {name: "shoe-size", value: "42"},
    ]
  }) {
    email,
    attributes {
      name,
      value
    }
  }
}
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.

Deleting Identities

There is currently no way to delete an identity.

GraphQL: Onsite Sessions

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.

mutation {
  newSession(referer: "https://google.com?q=shoes")
}

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.

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_PRODUCT
        target: "11923861519"
        ref: "front-page-slot-1"
      }
    }
  ) {
    pages {
      forProductPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, product: "11923861519") {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

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".

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_CATEGORY
        target: "/Shorts"
      }
    }
  ) {
    pages {
      forCategoryPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, category: "Shorts") {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

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.

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: SEARCHED_FOR
        target: "black shoes"
      }
    }
  ) {
    pages {
      forSearchPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, term: "black shoes") {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

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.

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_PAGE
        target: "https://example.com/cart"
      }
    }
  ) {
    pages {
      forCartPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, value: 100) {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

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

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_PAGE
        target: "https://example.com"
      }
    }
  ) {
    pages {
      forFrontPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }) {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

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".

{
  "data": {
    "updateSession": {
      "pages": {
        "forFrontPage": [
          {
            "resultId": "frontpage-nosto-1",
            "primary": [
              {
                "productId": "9497180547",
                "name": "Cool Kicks",
                "url": "https://example.com/products/cool-kicks"
              },
              {
                "productId": "9497180163",
                "name": "Awesome Sneakers",
                "url": "https://example.com/products/awesome-sneakers"
              },
              {
                "productId": "4676165861430",
                "name": "Free gift",
                "url": "https://example.com/products/free-gift"
              },
              {
                "productId": "2188051218486",
                "name": "Furry Dice",
                "url": "https://example.com/products/furry-dice"
              },
              {
                "productId": "9497180611",
                "name": "Gnarly Shoes",
                "url": "https://example.com/products/gnarly-shoes-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".

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_PRODUCT
        target: "9497180547"
        ref: "frontpage-nosto-1"
      }
    }
  ) {
    pages {
      forProductPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, product: "9497180547") {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

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.

Working with Orders

GraphQL: Placing Orders

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

mutation {
  placeOrder(by:BY_REF, id: "514421fce84abcb61bd45241", params: {
    customer: {
      firstName: "Mridang"
      lastName: "Agarwalla"
      email: "mridang@nosto.com"
      marketingPermission: false
    }
    order: {
      number: "25435"
      orderStatus: "paid"
      paymentProvider: "klarna"
      ref: "0010"
      purchasedItems: [
        {
          name: "Shoe"
          productId: "1"
          skuId: "11"
          priceCurrencyCode: "EUR"
          unitPrice: 22.43
          quantity: 1
        }
      ]
    }
  }) {
    id
  }
}

Orders can be associated with a customer either by customer reference or by customer id. The customer id matches the Nosto cookie (this cookie is typically called 2c.cId).

Tracking orders by customer id looks like the following:

mutation {
  placeOrder(by:BY_CID, id: "5d3ef53010b4f8a24c2acf9a", params: {
    customer: {
      firstName: "Mridang"
      lastName: "Agarwalla"
      email: "mridang@nosto.com"
      marketingPermission: false
    }
    order: {
      number: "25435"
      orderStatus: "paid"
      paymentProvider: "klarna"
      ref: "0010"
      purchasedItems: [
        {
          name: "Shoe"
          productId: "1"
          skuId: "11"
          priceCurrencyCode: "EUR"
          unitPrice: 22.43
          quantity: 1
        }
      ]
    }
  }) {
    id
  }
}

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.

mutation {
  placeOrder(by:BY_REF, id: "514421fce84abcb61bd45241", params: {
    customer: {
      firstName: "Mridang"
      lastName: "Agarwalla"
      email: "mridang@nosto.com"
      marketingPermission: false
    }
    order: {
      number: "25435"
      orderStatus: "paid"
      paymentProvider: "klarna"
      ref: "0010"
      purchasedItems: [
        {
          name: "Shoe"
          productId: "1"
          skuId: "11"
          priceCurrencyCode: "EUR"
          unitPrice: 22.43
          quantity: 1
        }
      ]
    }
  }) {
    id
    pages {
      forOrderPage(value: "25435", params: {
        imageVersion: VERSION_3_90_70
        isPreview: true
      }) {
    divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

GraphQL: Updating Order Statuses

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

GraphQL: Onsite Sessions

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.

mutation {
  newSession(referer: "https://google.com?q=shoes")
}

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

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_PRODUCT
        target: "11923861519"
        ref: "front-page-slot-1"
      }
    }
  ) {
    pages {
      forProductPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, product: "11923861519") {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

On the Category Page

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_CATEGORY
        target: "/Shorts"
      }
    }
  ) {
    pages {
      forCategoryPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, category: "Shorts") {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

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.

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: SEARCHED_FOR
        target: "black shoes"
      }
    }
  ) {
    pages {
      forSearchPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, term: "black shoes") {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

On the Cart Page

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_PAGE
        target: "https://example.com/cart"
      }
    }
  ) {
    pages {
      forCartPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, value: 100) {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

On the Front Page

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_PAGE
        target: "https://example.com"
      }
    }
  ) {
    pages {
      forFrontPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }) {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}

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".

{
  "data": {
    "updateSession": {
      "pages": {
        "forFrontPage": [
          {
            "resultId": "frontpage-nosto-1",
            "primary": [
              {
                "productId": "9497180547",
                "name": "Cool Kicks",
                "url": "https://example.com/products/cool-kicks"
              },
              {
                "productId": "9497180163",
                "name": "Awesome Sneakers",
                "url": "https://example.com/products/awesome-sneakers"
              },
              {
                "productId": "4676165861430",
                "name": "Free gift",
                "url": "https://example.com/products/free-gift"
              },
              {
                "productId": "2188051218486",
                "name": "Furry Dice",
                "url": "https://example.com/products/furry-dice"
              },
              {
                "productId": "9497180611",
                "name": "Gnarly Shoes",
                "url": "https://example.com/products/gnarly-shoes-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".

mutation {
  updateSession(by: BY_CID, id: "5b1a481060b221115c4a251e",
    params: {
      event: {
        type: VIEWED_PRODUCT
        target: "9497180547"
        ref: "frontpage-nosto-1"
      }
    }
  ) {
    pages {
      forProductPage(params: {
        isPreview: false, imageVersion:  VERSION_8_400_400
      }, product: "9497180547") {
        divId
        resultId
        primary {
          productId
        }
      }
    }
  }
}