File schemas are used to identify the data that you are sending to ReSci from your system, via flat files through the SFTP. Each filetype that you send has a specific schema that describes what the data in each column contains. The schema should be sent as the column header with the relevant data underneath.
See below for file schema types, as well as a table containing each schema field name, status, data type, and a brief description:
![]() |
Important: Please note, the status of each field as the required fields must be sent exactly as listed for that filetype to be properly ingested into our system. |
Categories
Fields |
Status |
Type | Description |
---|---|---|---|
record_id | Required | String | Primary unique key of category in your database |
name | Required | String | Name of category |
description | Optional | String | Description of category |
parent_record_id | Optional | String | Primary key of parent category in your database |
Example:
Fields | Value |
---|---|
record_id | 12 |
name | Pants |
description | Contains all types of pants |
parent_record_id | 1 |
Context/Considerations:
- record_id: This is your category id that is associated in items.
Items
Fields | Status | Type | Description |
---|---|---|---|
record_id | Required | String | Primary unique key of item in your database |
name | Required | String | Name of item |
price | Required | Float | Price of item |
price_b | Optional | Float | Alternate price for item (MSRP or Original Price) |
active | Required | Integer | Active: 1, Inactive: 0 |
item_url | Required | String | URL of item |
item_type | Optional | String | Indicating the type of item (No special characters) |
manufacturer | Optional | String | Manufacturer of item |
model | Optional | String | Model of item |
quantity | Optional | Integer | Quantity of item in stock |
image_list | Required | String | URL of hosted item image |
categories | Optional | String | Category Record IDs of item, comma-separated (no spaces) |
parent_record_id | Required | String | Primary key of parent item in your database Send NULL value (not empty string) if there is no parent item |
replenish_interval | Optional | Integer | Integer of days predicting when item should be repurchased |
do_not_recommend | Optional | Integer | Not Recommendable: 1, Recommendable: 0 |
description | Optional | String | item description to display when recommended in email |
display_name | Optional | String | item display name |
Example:
Fields | Value |
---|---|
record_id | 2345L |
name | Large Fuji Apple |
price | 1.99 |
active | 1 |
item_url | http://example.com/fruit/apples/fuji |
item_type | subscription |
manufacturer | Nature |
model | A-LF |
quantity | 100 |
image_list | http://example.com/fruit/apples/fuji/image_1.jpg |
categories | 123,123A |
parent_record_id | 2345 |
replenish_interval | 20 |
Context/Considerations:
-
active: This column is critical as it will determine if RS will recommend a product or not in emails. (e.g. if 0, the item will not be recommended).
-
item_url: When Cortex generates emails with item recs, these URLs will navigate the user to the item they wish to purchase.
-
item_type: Assign the value “subscription” if you are using Subscription Cortex. Note: "subscription" should be sent as lowercase. This is used to determine which items are subscriptions vs. one off purchase items.
-
quantity: Required to use the Cortex campaign stage of “Item Back In Stock”. (notify Users automatically when items are available).
-
image_list: This will be the picture of the items that will appear in your emails. The images should be high quality and consistent in sizing across items.
-
categories: The record_id of the category from the Categories file. (e.g. if multiple, example format would be “1,2,3,4,5”).
-
replenish_interval: Allows Cortex to automatically follow up with Users when item is about to expire. The days provided should be an average estimate of how long the product typically lasts.
-
Note on parent items - In emails, we may want to recommend parent items instead of their children. An example of this is a shirt that comes in different sizes. In many cases, the parent item is not actually for sale, only its children. However, the parent entry still must be in the items file, with record_id, name, price, item_url and image_list as required fields. The price for the parent item should be equal to the price of its lowest-priced child. The item_url is typically the landing page of the item from which you can select its children. The images in image_list represent the images that you want to be shown in email templates when recommending the parent.
Users
Fields | Status | Type | Description |
---|---|---|---|
record_id | Required | String | Primary key of user in your database / MD5 of email address |
Required | String | Email address of customer | |
account_created_on | Required | yyyy-mm-dd | Account creation date in UTC format |
full_name | Optional | String | Full name of customer |
address1 | Optional | String | Address 1 of customer |
address2 | Optional | String | Address 2 of customer |
city | Optional | String | City of customer |
state | Optional | String | State of customer |
zip | Optional | String | Zip code of customer |
country | Optional | String | Country of customer |
phone | Optional | String | Phone number of customer |
birthday | Optional | yyyy-mm-dd | Birthday in UTC format |
gender | Optional | String | Gender of customer* |
ip_address | Optional | String | IPv4 address of customer. Send only ONE IP ADDRESS |
number_logons | Optional | Integer | Number of times customer logged on |
last_logon_at | Optional | yyyy-mm-dd hh:mm:ss | Last date and time customer logged on in UTC format |
registration_source | Optional | String | Customer acquisition channel |
date_unsubscribed | Optional | yyyy-mm-dd hh:mm:ss | Date and time customer unsubscribed in UTC format |
unsubscribe_link | Optional | String | Internal link to unsubscribe customer |
utm_campaign | Optional | String | UTM Campaign |
utm_source | Optional | String | UTM Source |
utm_medium | Optional | String | UTM Medium |
utm_term | Optional | String | UTM Term |
utm_content | Optional | String | UTM Content |
last_accepts_marketing | Optional | String | Has the customer accepted marketing emails (1/0 and true/false accepted) |
Example:
Fields | Value |
---|---|
record_id | A1B2C3D4 |
johndoe@example.com | |
account_created_on | 2016-01-01 |
full_name | John Doe |
address1 | 123 Main St. |
address2 | Apt 209 |
city | Los Angeles |
state | CA |
zip | 91224 |
country | USA |
phone | 3339992222 |
birthday | 1970-01-01 |
gender | m |
ip_address | 127.0.0.1 |
number_logons | 2 |
last_logon_at | 2016-01-05 10:25:13 |
registration_source | Google Adwords |
date_unsubscribed | 2016-01-05 10:25:13 |
unsubscribe_link | http://www.unsubscribeaddress.com |
utm_campaign | campaign_launch |
utm_source | |
utm_medium | banner1 |
utm_term | SEO_service |
utm_content | content_a |
last_accepts_marketing | 1 |
Context/Considerations:
-
account_created_on: Used when determining sends of New to Your Brand (NTYB) emails in Cortex, the created on date must be within 2 days of current date for a user to be eligible
-
full_name: First and Last name will be available as merge tags in email
-
birthday: Allows your to setup Birthday Campaigns in Cortex
-
gender: If not provided, RS can predict gender with up to 95% accuracy.
-
registration_source: Useful for analytics inside of Cortex as well as segmenting campaigns
-
date_unsubscribed: This is only required in rare situations where multiple send systems are being used
-
unsubscribe_link: This is only required in rare situations where multiple send systems are being used
-
utm_campaign: Refers to the overall campaign you are running
-
utm_source: Used to describe where the traffic is coming from
-
utm_medium: Used to describe the specific element
-
utm_term: Used for paid search to determine the particular keyword you were bidding on for that specific ad
-
utm_content: Used for split testing
- last_accepts_marketing: Used to add customers that have not subscribed to marketing
* The gender field accepts the following inputs. String inputs will be validated and reduced to the first character, so "m" and "male" are both valid, but "woman" or "decline to answer" would not pass validation (the correct values for those are "f" and "x").
Input |
Gender |
---|---|
m |
male, man, masculine gender |
f |
female, woman, feminine gender |
n |
non-binary, genderqueer, agender |
i |
intersex |
o |
other |
x |
decline to answer |
u |
unknown |
Orders
Fields | Status | Type | Description |
---|---|---|---|
record_id | Required | String | Primary key of order in your database |
user_record_id | Required | String | Primary key of user in your database / MD5 of email address |
Required | String | Email address of customer | |
total_price | Required | Float | Total price of entire order |
ordered_at | Required | yyyy-mm-dd hh:mm:ss |
Order datetime in UTC format |
order_status | Required | String | Status of order |
discount_amount | Optional | Float | Discount of order (Positive Value) |
shipping_amount | Optional | Float | Shipping of order |
tax_amount | Optional | Float | Tax of order |
payment_method | Optional | String | Payment method used |
subscription | Optional | Integer | Subscription order: 1, Non-subscription order: 0 |
Example:
Fields | Value |
---|---|
record_id | 987654321 |
user_record_id | A1B2C3D4 |
johndoe@example.com | |
total_price | 99.95 |
ordered_at | 2016-01-05 10:25:13 |
discount_amount | 10.00 |
shipping_amount | 5.00 |
tax_amount | 9.95 |
payment_method | PayPal |
subscription | 0 |
order_status | Paid |
Context/Considerations:
- order_status: Helpful to make revenue/order stats as accurate as possible inside of Cortex (e.g. we can de-activate certain statuses such as “Refunded” that are not true orders)
Order items
Fields | Status | Type | Description |
---|---|---|---|
order_record_id | Required | String | Primary key of order in your database |
item_record_id | Required | String | Primary key of item in your database |
name | Required | String | Name of item |
quantity | Required | Integer | Quantity of item in order |
price | Required | Float | Price per item |
categories | Optional | String | Category Record IDs of item, separated by commas (no spaces) |
Example:
Fields | Value |
---|---|
order_record_id | 987654321 |
item_record_id | 2345L |
name | Large Fuji Apple |
quantity | 2 |
price | 1.99 |
categories | 123,123A |
User subscriptions
Used by AI models to track users who have recurring subscriptions to a product (Note: These are not newsletter only subscribers)
Fields | Status | Type | Description |
---|---|---|---|
record_id | Required | String | Primary key of subscription |
user_record_id | Required | String | Primary key of user in your database / MD5 of email address |
status | Required | String | Status of subscription |
item_record_id | Required | String | Primary key of subscribed item in your database. Subscribed item must have an item type of “subscription” |
started_at | Required | yyyy-mm-dd hh:mm:ss | Subscription start datetime in UTC format |
trial | Required | Integer | Indicating whether the user is on trial 1=true 0=false |
churned | Required | Integer | Indicating whether the user is on churned 1=true 0=false |
canceled_at | Required | yyyy-mm-dd hh:mm:ss | Subscription cancelation datetime in UTC format. If the subscription is active, leave this field blank. |
cancel_reason | Optional | String | Subscription cancelation reason |
attribute_1 | Optional | String | Any additional field (frequency, color, etc) |
Example:
Fields | Example |
---|---|
record_id | 345678 |
user_record_id | A1B2C3D4 |
status | active |
item_record_id | 2345L |
started_at | 2016-01-05 10:25:13 |
trial | 1 |
churned | 1 |
canceled_at | 2016-01-15 10:25:13 |
cancel_reason | Too expensive |
attribute_1 | Monthly |
Item reviews
Used by AI models to enhance recommendations and churn score of users
Fields | Status | Type | Description |
---|---|---|---|
record_id | Required | String | Unique Key |
feedback_at | Required |
yyyy-mm-dd |
Date of feedback in datetime in UTC format |
user_record_id | Required | String | Primary key of user in your database / MD5 of email address |
item_record_id | Required | String | Primary key of subscribed item in your database. |
rating | Optional | Float | Rating of the item (1-5, float) |
review | Optional | String | Review of the item |
num_approvals | Optional | Integer | Number of users that found this review useful (integer) |
Example:
Fields | Value |
---|---|
record_id | 42 |
feedback_at | 2016-01-01 11:31:45 |
user_record_id | A1B2C3D4 |
item_record_id | 2345L |
rating | 1,2.5,3.3,4,5 |
review | “This item was fantastic!” |
num_approvals | 3 |
Context/Considerations:
-
rating: At least one must be provided: rating or review
-
review: At least one must be provided: rating or review
User wish lists
Fields | Status | Description |
---|---|---|
item_record_id | Required | Primary key of item in your database. |
user_record_id | Required | Primary key of user in your database / MD5 of email address |
active | Required | Active: 1, Inactive: 0 |
Example:
Fields | Example |
---|---|
item_record_id | 2345L |
user_record_id | A1B2C3D4 |
active | 1 |
Context/Considerations:
- active: This defines if the item is active in a user’s wishlist, not to be confused with the items file active column
Comments
0 comments
Please sign in to leave a comment.