This endpoint is used for initiating a personal-data takeout request. All requests to this endpoint are asynchronous and simply enqueue the email address for takeout. It may take up to 24 hours for the takeout process to complete. If the email address is found, a notification email (informing you about the takeout request) will be sent once the process has completed.

Token

This endpoint requires an Email token.

Usage

curl -v -X POST https://api.nosto.com/v1/customers/takeout/john.doe@nosto.com \
--user :WI0j2oN7TgG42tlblX3yzOQ5xvCYc2oYj9eWg79lghVq8R0nKQXlVE9wvihBUFOw

Nosto offers a multitude of APIs for different use cases. The APIs are not entirely RESTful but provide lightweight endpoints that expose similar usability.

All the APIs reside at https://api.nosto.com and must be accessed over HTTPS.

Note: If you happen to call the interface via HTTP using a valid API key, that API key will be invalidated immediately and a notice of the token revocation will be sent to the account owner.

Authentication

Authenticating with the API is done by using . You authenticate by using your API key as the password and the username is left empty.

You can see your API keys in the Nosto Backend under account settings. API key is always tied to a single store in your account.

Note: Keep your API key secret and delete it immediately if you think someone untrusted might have had access to it.

Requesting access

To get access to our APIs, please log in to your Nosto account at and contact support via chat. When you request API access, please provide following information:

• What is the API in question?

• What is the purpose for the API use?

• What is the volume of requests?

• What is the request distribution, on-demand or periodic?

Token types

Rate Limits

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.

This endpoint is used for blacklisting email addresses from receiving Nosto's triggered emails such as cart-abandonment emails, order-follow emails, and we-miss-you emails.

Having the corresponding email address in our system prior to blacklisting or unblacklisting is not a prerequisite. If the specified email record does not exist in our system, it will be created.

Token

This endpoint requires an Email token.

Blacklisting an email

You can specify multiple email addresses separated by a newline.

Unblacklisting an email

You can specify multiple email addresses separated by a newline.

This endpoint is used for toggling the marketing permission for an email. The marketing permission for an email is normally gathered .

This endpoint is only intended for use when the consent needs to be programmatically managed and should be a considered an advanced use case.

Token

This endpoint requires an Email token.

Usage

Granting consent

Revoking consent

While Nosto's crawler attempts to keep its copy of your catalog as fresh as possible, there are scenarios where we may not be able to update all the information as quickly as needed.

In these scenarios, we recommend that you implement our enhanced Products API which allows you push all your product metadata and have the changes instantly reflect across our entire engine.

For example, if you add a discount of -10% to all the products in your "Shirts" category, you can use the Products API to bulk update all the products.

Here's an example of a Curl request.

Sending the categories

Categories must always be delimited by a slash. For example, Home/Accessories or sale/summer/shirts/long-sleeve-shirts is a valid category while Home > Accessories is not.

How can I get an API token?

How many items can I update at a time?

The Products API takes an array of product metadata and has no hard limit on the number of items that you can specify and is only limited by the maximum size of the payload of 2 MB.

How often can I update products?

You can update products as often as you need although, initially you'll need to send the entire catalog to populate the replica of your catalog on Nosto.

When should I make an API call?

You should make an API call when any product information changes. If a non-critical field of the product e.g. description, has changed, you can delay the product update as descriptions are rarely visible to the end customer. When the price or availability of the product changes, you should make an API call right away as this will instantly reflect in the recommendations.

Is there any additional benefit of using the product API?

While the product API contains the full superset of the information in the tagging, it also allows you to pass sensitive information to us. Sensitive information is fields such as the supplier cost (margin) and the inventory level. These fields are only mutable via the API.

What fields are required?

The following fields are required:

• product_id

• name

• url

• image_url

• availability

• price

• price_currency_code

When using multi-currency, this endpoint is used to update the exchange rates for your account. When new rates are sent via this endpoint, the changes will reflect instantly on your store as the product prices are multiplied with the provided rates in real-time.

Note: This endpoint should only be used when using multi-currency. Please refer to our multi-currency guide prior to using this endpoint. Incorrect usage of these endpoints will result in a total outage of your personalization setup.

Token

This endpoint requires a Rates token.

Usage

curl -v -X POST https://api.nosto.com/exchangerates \
--user :WI0j2oN7TgG42tlblX3yzOQ5xvCYc2oYj9eWg79lghVq8R0nKQXlVE9wvihBUFOw \
-H "Content-Type: application/json" -d '
{
  "rates":{
    "GBP":{
      "rate":0.77,
      "price_currency_code":"GBP"
    },
    "EUR":{
      "rate":0.91,
      "price_currency_code":"EUR"
    }
  },
  "valid_until":"2015-02-27T12:00:00Z"
}'

How can I get an API token?

You can request an API token (API_PRODUCTS) by getting in touch with our support personnel. Once the token has been granted, you will be able to find it listed in the authentication tokens section in the admin.

How often should I send exchange-rates?

You can send exchange rates as often as you like but at the bare minimum, the exchange rates should be sent when they are changed.

While Nosto's crawler attempts to keep its copy of your catalog as fresh as possible, there are scenarios where we may not be able to update all the information as quickly as needed.

In these scenarios, we recommend that you implement our Discontinue API which allows you to push all your product identifiers to discontinue them and have the changed instantly reflect across our entire engine.

Here's an example of a Curl request.

curl -v --user :WI0j2oN7TgG42tlblX3yzOQ5xvCYc2oYj9eWg79lghVq8R0nKQXlVE9wvihBUFOw -H "Content-Type: application/json" -X POST https://api.nosto.com/v1/products/discontinue -d '
[
  '101',
  '102' 
]'

How can I get an API token?

You can request an API token (API_PRODUCTS) by getting in touch with our support personnel. Once the token has been granted, you will be able to find it listed in the authentication tokens section in the admin.

How many items can I update at a time?

The Discontinue API takes an array of product metadata and has no hard limit on the number of items that you can specify and is only limited by the maximum size of the payload of 2 MB.

How often can I discontinue products?

You can discontinue products as often as you need.

When should I make an API call?

You should make an API call when any product is discontinued and removed from your catalog. If a product has simply gone out of stock, we recommend making an API to update the product with the correct availability.

Is there any additional benefit of using the Discontinue API?

While Nosto crawls your site and automatically discontinues products that are no longer available, it may lag behind when your site has a large catalog. In these environments, it is recommended to use the Discontinue API to immediately discontinue the product.

While Nosto's crawler attempts to keep its copy of your catalog as fresh as possible, there are scenarios where we may not be able to update all the information as quickly as needed.

In these scenarios, we recommend that you implement our lightweight Recrawl API which allows you programmatically instruct our crawler to reindex a given URL.

For example, if you add a discount of -10% to all the products in your "Shirts" category, you can use the Recrawl API to recrawl all the given URLs and update the prices.

Here's an example of a Curl request.

curl -v --user :WI0j2oN7TgG42tlblX3yzOQ5xvCYc2oYj9eWg79lghVq8R0nKQXlVE9wvihBUFOw -H "Content-Type: application/json" -X POST https://api.nosto.com/products/recrawl -d '{  
  "products":[  
    {  
      "product_id":"339",
      "url":"https://magento1.plugintest.nos.to/retro-chic-eyeglasses.html?___store=default"
    }
  ]
}'

How can I get an API token?

You can request an API token (API_PRODUCTS) by getting in touch with our support personnel. Once the token has been granted, you will be able to find it listed in the authentication tokens section in the admin.

How many items can I recrawl at a time?

The Recrawl API takes an array of product ids and URLs and has no hard limit on the number of items that you can specify.

How often can I invoke a recrawl?

You can recrawl as often as you need but bear in mind that every recrawl adds an extra page load to your server.

This endpoint is used for redacting all personal data associated with an email. All requests to these endpoints are asynchronous and simply enqueue the email address for redaction. It may take up to 24 hours for the redaction process to complete. If the email address is found, a notification email (informing you about the redaction) will be sent once the process has completed.

Token

This endpoint requires an Email token.

Usage

curl -v -X DELETE https://api.nosto.com/v1/customers/redact/john.doe@nosto.com \
--user :WI0j2oN7TgG42tlblX3yzOQ5xvCYc2oYj9eWg79lghVq8R0nKQXlVE9wvihBUFOw