Connect your shop with Aqurate via API

☝️ All data is pushed to Aqurate using our RESTful API. Exact documentation here.

1. Authentication

To push your shop data to Aqurate, you need to generate an API key on the API Keys page. You can choose the Shop via API preset, or generate a custom key with the scope: write:input_tables

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.

💡If you want to use the same API key to retrieve product recommendations, also enable the read:item_recs and read:user_recs scope. More details on the how-to guide.

2. The required data types

The data model for computing Aqurate Personalize includes 8 tables. However, not all tables and columns are mandatory. The table below gives you an overview of what we need:

Table

Details

Required

Orders The orders and their customers. Yes (can be partially replaced by Website Events)
Line Items The line items corresponding to the orders. Yes (can be partially replaced by Website Events)
Items The items and their details. Yes
Items Categories

The mapping of items into categories.

Yes
Categories The mapping of categories. Yes
Stock The current stock level for all available items. No, but recommended
Website Events The interactions with the website. Yes (can be partially replaced by Orders + Line Items)
Customers  The email addresses of customers No (only needed for recommendations via email)

3. The tables and structures

Orders (orders)

Field name

Details

Type

Required

order_id The unique identifier of the order. String Yes
customer_id The unique identifier of the customer. String Yes
order_date The date and time at which the order was placed by the customer. The format is ISO 8601 in UTC. Timestamp Yes
order_status The status of the order. Accepted values are: 'processing', 'completed', 'returned', 'canceled’ String for Aqurate Segmentation

Line Items (line_items)

Field name

Details

Type

Required

order_id The unique identifier of the order. String Yes
product_id The unique identifier of the item. String Yes
quantity The quantity of items. Float for Aqurate Segmentation
price_per_unit The net price of one item. Float for Aqurate Segmentation

 

Items (items)

Field name

Details

Type

Required

product_id The unique identifier of the item. String Yes
item_parent_id The unique identifier of the parent item. String  
sku The SKU number of the item. String  
name The display name of the item. String Yes
description The description of the item. String  
brand The name of the item’s brand. String  
price The gross price of the item. Float  
currency The 3-letter currency denomination (e.g. EUR, RON, USD, HUF) String  
photo_url The URL of the main product picture. String  
item_uri The item’s publicly accessible URL. String  
is_active 1 or 0, depending on whether the item is currently listed on the shop’s website. Boolean  
attribute_1_name This is a placeholder for the name of any attributes that are highly relevant to the item. String  
attribute_1_value This is a placeholder for the value of any attributes that are highly relevant to the item. String  
attribute_2_name This is a placeholder for the name of any attributes that are highly relevant to the item. String  
attribute_2_value This is a placeholder for the value of any attributes that are highly relevant to the item. String  
attribute_3_name This is a placeholder for the name of any attributes that are highly relevant to the item. String  
attribute_3_value This is a placeholder for the value of any attributes that are highly relevant to the item. String  
attribute_4_name This is a placeholder for the name of any attributes that are highly relevant to the item. String  
attribute_4_value This is a placeholder for the value of any attributes that are highly relevant to the item. String  

Item Categories (item_categories)

Field name

Details

Type

Required

product_id The unique identifier of the item. String Yes
category_id The unique identifier of the category of the item. String Yes
is_primary To be used when a primary category is defined for the item. For example, an item in "shoes" and "bestsellers" would have the main category "shoes". Boolean  

⚠️ One item can be in multiple categories. This table is not unique at row level on product_id, but on the combination of product_id and category_id.

Categories (categories)

Field name

Details

Type

Required

main_category_id The unique identifier of the main category. String Yes
main_category The name of the main category. String Yes
subcategory_1_id The unique identifier of the first-level subcategory. String  
subcategory_1 The name of the first-level subcategory. String  
subcategory_2_id The unique identifier of the second-level subcategory. String  
subcategory_2 The name of the second-level subcategory. String  
subcategory_3_id The unique identifier of the third-level subcategory. String  
subcategory_3 The name of the third-level subcategory. String  
subcategory_4_id The unique identifier of the fourth-level subcategory. String  
subcategory_4 The name of the fourth-level subcategory. String  

Stock (stock)

Field name

Details

Type

Required

product_id The unique identifier of the item. String Yes
stock_quantity The number of units in stock. String Yes
stock_type One of "own", "dropshipping", " at_supplier". String  

 

Website Events (website_events)

⚠️ Please note that page_type and event have specific valid entries.

Field name

Details

Type

Required

timestamp The time and date of the observation. The format is ISO 8601 in UTC. Timestamp Yes
session_id The unique identifier of the session. String Yes
cookie_id The unique identifier of the cookie. String Yes
user_id The unique identifier of the user. String  
product_id The unique identifier of the item. String Yes
page_type The type of page on which the event happens. Valid entries: detail_page, checkout String Yes
event The type of event. Please check the example input for valid entries. Valid entries: page_view, add_to_cart, add_to_wishlist, purchase String  Yes

Customers

⚠️ Optional - Only needed to send recommendations via email.

Field name

Details

Type

Required

customer_id The unique identifier of the customer. String Yes
email The email of the customer. String Yes

 

 

 

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