⏳ 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.
⚠️ Please note that the /input/{table} endpoint has a rate limit of 1 request per second. We recommend implementing a delay and a retry mechanism.
3. The required data types
The data model for computing Aqurate Personalize includes the tables below. However, not all tables and columns are mandatory.
|
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 |
| Custom Item Attributes | The items and their corresponding attributes | No |
| 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 |
| 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 |
| storefront | The storefront where the order was placed (e.g. shop.com, shop.de, Amazon.com, Physical retail, etc.) | String | No |
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 |
Custom Item Attributes (custom_item_attributes)
|
Field name |
Details |
Type |
Required |
|---|---|---|---|
| product_id | The unique identifier of the item. | String | Yes |
| attributes |
List of attribute objects of the item. Each object consists of two keys:
The values within "attribute_values" should be consistent across type. |
List | No |
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 |
Customers (customers)
|
Field name |
Details |
Type |
Required |
|---|---|---|---|
| customer_id | The unique identifier of the customer. | String | Yes |
| The email of the customer. | String | Yes |
This table is optional. It is only needed to send recommendations via email.
5. Scheduling the API calls 🕒
5.1 First upload
For the initial training of the AI model, we recommend sending up to 4 years of historical data.
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 Rate limit and retry logic
The /input/{table} endpoint has a rate limit of 1 request per second and 5000 requests per day.
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.
We recommend implementing a delay and a retry mechanism.
To ensure all data reaches us, please retry requests that fail with status codes 429 or greater than 499. However, retries should not replace proper rate-limiting; it's important to time your requests accordingly. Additionally, you can batch up to 1000 rows of data in a single request to reduce the number of requests you need to make.
Questions about getting started? We're excited to help: support@aqurate.ai