⏳ Duration: 60 minutes
🎚️ Complexity: high
📌 Prerequisites
1. An Aqurate account (get it at aqurate.ai)
2. An active subscription with Aqurate Personalize
☝️ 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 API endpoint for sending the data
When making API calls, please use the POST /input/{table} endpoint. You can find it in the API Documentation here. The expected data structure is detailed under point 4 below.
3. 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 |
| Line Items | The line items corresponding to the orders. | Yes |
| Items | The items and their details. | Yes |
| Item Categories |
The mapping of items into categories. |
Yes |
| Categories | The mapping of categories. | Yes |
| Stock | The current stock level for all available items. | Yes |
| Website Events | The interactions with the website. | Yes. Can be replaced by the Aqurate Pixel. |
| Customers | The email addresses of customers | Only required for recommendations via email. |
4. 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 | Yes |
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 |
| sku |
The SKU number of the item. | String | |
| quantity | The quantity of items. | Float | Yes |
| price_per_unit | The price of one item. Should be the same type (net/gross) as the price field in the Items table. | Float | Yes |
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 price of the item. Should be the same type (net/gross) as the price field in the Line Items table. | Float | Yes |
| currency | The 3-letter currency denomination (e.g. EUR, RON, USD, HUF) | String | |
| photo_url | The URL of the main product picture. | String | Yes |
| item_uri | The item’s publicly accessible URL. | String | Yes |
| is_active | 1 or 0, depending on whether the item is currently listed on the shop’s website. | Boolean | Yes |
| created_at | The date and time at which the item was created. The format is ISO 8601 in UTC. | Timestamp | Yes |
| 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 | Yes |
⚠️ 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 (to be paired with the event field) |
The type of page on which the event happens. Valid entries: "detail_page", "checkout", null. |
String | Yes |
|
event (to be paired with the page_type field) |
The type of event. Please check the example input for valid entries. Valid entries: "page_view", "add_to_cart", "add_to_wishlist", "purchase", "link_click". | String | Yes |
❗ Following combinations of page_type - event are accepted:
-
"detail_page" - "page_view"
-
"detail_page" - "add_to_wishlist"
-
"detail_page" - "add_to_cart"
-
"checkout" - "add_to_wishlist"
-
"checkout" - "add_to_cart"
- "checkout" - "purchase"
- null - "link_click"
Customers (customers)
⚠️ Optional - Only needed to send recommendations via email.
|
Field name |
Details |
Type |
Required |
|---|---|---|---|
| customer_id | The unique identifier of the customer. | String | Yes |
| The email of the customer. | String | Yes |
5. Scheduling the API calls 🕒
5.1 First upload
For the initial training of the AI model, we recommend sending historical data as follows:
- Orders and Line items - for up to 4 years.
- Website events - up to 6 months.
5.2 Daily runs
The AI model is trained every 24 hours, so we recommend sending updated data every 24 hours, too.
The system always focuses on the latest entry for each entity.
Example:
Let's take an item with the product_id '67.' To determine whether this product is currently available on the webpage, we review the recent uploads and narrow down to the most recent update involving the product identified by ID '67.' If, in this update, the 'is_active' attribute was marked as 'true,' we consider the item active. This determination remains valid until the product is modified through a new API call to the 'items' table, at which point the 'is_active' field is set to 'false'.
5.3 Retry logic
We are doing the best to always provide enough server capacity to handle all incoming requests. But due to unexpected spikes, it is possible that a small number of requests will result in a server error.
To make sure all data eventually reach us, please retry failed requests that have a status code greater than 499.
Questions about getting started? We're excited to help: support@aqurate.ai