1. The Aqurate knowledge base
  2. Custom shop via RESTful API

Set up Aqurate Personalize via RESTful API

Learn which endpoints you need to call, what resources to access, and what fields to request.

⏳ Duration: 30 minutes 
🎚️ Complexity: high

πŸ“Œ Prerequisites

1. An Aqurate account (get it at aqurate.ai)

2. An active integration of your Shop data (connect your shop here)

3. An active subscription with Aqurate Personalize

πŸ“– Resources

Check out and test our endpoints in the Recommendation section of our docs.

Table of contents:

1. Authentication

2. Get product recommendations

2.1 Item-to-item recommendations

2.1.1 Item-to-item recommendations by product_id

2.1.2 Item-to-item recommendations by batches

2.2 User-to-item recommendations

1. Authentication

To query the endpoints, you need to generate an API key on the API Keys management page. You should generate a custom key with the scopes read:item_recs and read:user_recs.

When making API calls, use the generated API key for the X-Auth-Token parameter.

⚠️ Keep your API keys safe, as they can be used to access the data in your Aqurate account. For your security, API keys can only be viewed once. If you lose an API key, you can easily revoke it and generate a new one.

πŸ’‘ Optionally, you can also enable the read:item_features and read:user_features to enable the /item and /user endpoints respectively. There endpoints deliver item and user information.

If you want to use the same API key to connect your shop to Aqurate, also enable the write:input_table scope. More details on the Shop integration via API guide.

2. Get product recommendations

The Aqurate Personalize API offers two types of endpoints:

  • Item-to-item endpoints
  • User-to-item endpoints

2.1 Item-to-item recommendations

Item-to-item recommendations are centered around items, and are usually used on Product Detail Pages, Shopping Cart, and Pop-ups. There are multiple different resources, like ...recs/item/similar, ...recs/item/cross-sell, ...recs/item/substitutes etc.

All of these endpoints:

  • have the same parameters
  • deliver responses of the same JSON structure
  • require choosing the number of recommendations you want to retrieve for each product. This number can be specified with the top parameter. The default value is 10.

2.1.1 Item-to-item recommendations by product_id

↗️ Request

Querying by product_id simply involves passing the identifier of a specific product as an argument to the product_id parameter.

πŸ’‘ Example API call: .../recs/item/similar?top=10&product_id=12345.

↩️ Response

If recommendations are available for the product, you get a response that looks like this:

{
    "recs":
    [
        {
            "product_id": "45678",
            "sku_name": "45678",
            "rec_product_id": "901011",
            "position": 1
        },
        {
            "product_id": "45678",
            "sku_name": "45678",
            "rec_product_id": "12131415",
            "position": 2
        },
        <...>
    ]
}

 

The response contains a list of recommendations (the recs object) which have these fields:

  1. product_id corresponds to the argument value passed to the query in the first place
  2. rec_product_id specifies the recommended product
  3. position provides the rank in the set of all recommendations. 
πŸ’‘ Recommendations with smaller position values are evaluated as a better fit and should be shown first to the user (e.g. in a website widget).

🚧 The sku_name field is deprecated and will be removed from the response in future versions of the API.

 

2.1.2 Item-to-item recommendations by batches (optional)

⚠️Querying the API by batches can put a strain on your resources. Adding retry logic to your code is advised.

↗️ Request

A more efficient way of querying the complete set of recommendations is using the endpoint's batch functionality. You can do so by specifying the limit parameter (instead of the product_id parameter).

With the limit parameter, you can choose how many recommendations you want to retrieve per API call. This number should not be higher than 5,000 as the response may take too long.

πŸ’‘ Example of an initial API call: .../recs/item/similar?top=10&limit=1000.

↩️ Response

The first call to the API will give a response of this format:

{
    "recs":
    [
        {
            "product_id": "1234",
            "sku_name": "1234",
            "rec_product_id": "4567",
            "position": 1
        },
        {
            "product_id": "1234",
            "sku_name": "1234",
            "rec_product_id": "8910",
            "position": 2
        },
                <...>,
        {
            "product_id": "898989",
            "sku_name": "898989",
            "rec_product_id": "787878",
            "position": 3
        }
    ],
    "links":
    {
        "next": "https//api.aqurate.ai/recs/item/similar?top=10&limit=1000&marker=898989"
    }
}

 

The response contains two objects:

  1. recs β†’ similar to the one described in the previous section
  2. next β†’ contains the next field, which holds the URL that can be used to retrieve the next batch

By calling the next link after each API call, you retrieve the entire set of recommendations in our database. The responses have the same structure as the response above. Again, the product_id field corresponds to the item for which the rec_product_id is recommended.

You then perform API calls until the next field is null, which means that all recommendations have been retrieved:

{
    "recs":
    [
        {
            "product_id": "676767",
            "sku_name": "676767",
            "rec_product_id": "2233",
            "position": 1
        },
                <...>
    ],
    "links":
    {
        "next": null
    }
}

2.2 User-to-item recommendations

User-to-item recommendations are centered around users, and are usually used on Home Pages, Pop-ups, and via Email. The resource to use is: ...recs/user.

πŸ’‘ If you are using one of our native email integrations, you do not need to use the user-item endpoint, as recommendations are automatically populated in the email automation tool.

 

↗️ Request

Querying by user simply involves passing the identifier of a specific user as an argument to as follows:

Identifier Description Source
customer_id The customer id assigned by the shop platform. Shop integration
email The email of the user.

Shop integration

Aqurate Pixel

user_id The user_id assigned on the website.

Aqurate Pixel

Website via API

cookie_id The cookie_id assigned on the website.

Aqurate Pixel

Website via API.

πŸͺ To use the cookie_id generated by the Aqurate Pixel, find the cookie with the format _sp_id.xxxx. The value of the cookie is the string before the first period: ae78a4a0-abe9-4892-bf27-dd1eed5479db.1684413904.9.[...].

Other valuable parameters are the clicks, order_quantity, and seen parameters. This allows you to exclude products that have already been seen, bought, or clicked by the customer, if your customers usually do not make repeat purchases of the same product. For example, if you do not want customers to be shown recommendations for products that have been seen or bought more than 2 times, set the value to 2.

πŸ‘† The default value of the seen parameter is 0, meaning that only items that were not seen or bought before will be provided.

πŸ’‘ Example API call: /recs/user?seen=0&top=10&email=support@aqurate.ai.

 

↩️ Response

If recommendations are available for the user, you get a response that looks like this:

{
"recs": [
{
"user_id": "support@aqurate.ai",
"seen": 0,
"product_id": "787878",
"position": 0
}
],
"links": {
"next": "string"
}
}

You’re done πŸŽ‰!

 

Questions about getting started? We're excited to help: support@aqurate.ai