☝️ 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 |
| The email of the customer. | String | Yes |
Questions about getting started? We're excited to help: support@aqurate.ai