Integration: Transaction Data Validation
During the onboarding process and beyond, we need to validate the transaction data received by the Relevance Cloud integration against your company’s internal fulfillment systems. These specifications provide simple guidelines to follow when generating a sample feed of transaction data. Follow this document to ensure accurate validations by the Algonomy analytics group.
This guide assumes that its readers:
- Are experienced web or application developers
- Have a background in the ecommerce/retail industry
- Understand how to populate functions with dynamic page-specific values
What are the benefits of this feature?
By ensuring that your feed of transaction data is valid and usable by Algonomy, retailers can avoid problems down the line.
What are the drawbacks of this feature?
Setting up your first feeds is very important, and may require some adjustments to reach optimal feed integrity.
How It Works
Feeds are sent by retailers and ingested by Algonomy, processed and used to drive recommendations across the retailer's site.
The feed should be formatted as a flat text file with a single line item entry per row, delimited by commas.
Headers should only be included if you use the names identified in the Fields section below. Whether you use headers or not, the fields in the data feed should be in the exact order defined below.
Depending on the size of the file, you can deliver the data by either FTP or by email. For FTP information, contact your Algonomy team.
The filename must follow the convention SiteName_StartDate_EndDate_Timezone.csv. For example, BassPro_2011-08-24_2011-08-26_GMT.csv. Timezones are based on the following conventions:
- PST – Pacific Standard Time (GMT – 8)
- MST – Mountain Standard Time (GMT – 7)
- CST – Central Standard Time (GMT – 6)
- EST – Eastern Standard Time (GMT – 5)
- GMT – Greenwich Mean Time
- CET – Central European Time (GMT + 1)
- EET – Eastern European Time (GMT + 2)
- JST – Japan Standard Time (GMT + 9)
Duration and Coverage
The duration of time that the file should cover varies by merchant. As a rule of thumb, we request as a minimum of either 1 complete day OR 10,000 transaction lines. The file should contain
- All orders that pass through the fulfillment systems that contain Recommend tagging, including orders that are canceled, fraudulent or may eventually result in returns
- All internal testing orders that render the purchase complete page instrumented with Recommend tagging
All orders that pass through a fulfillment channel that does not contain Recommend tagging (e.g., call centers, Google Checkout, etc.) should be filtered out of the file.
To accurately and comprehensively validate your transaction data by Algonomy, you must supply line item level details for a specific period of time, which varies by merchant depending on the volume of transactions per day (i.e., the higher the order volume, the lesser the duration of time for which we need transactional data). Please do not include any personally identifiable information, such as email address or customer first/last name.
- datetime – a timestamp of the purchase, including both of the date as well as hour, minute and second of the day. This is most frequently formatted as ‘YYYY-MM-DD hh:mm:ss’. ‘YYYY-MM-DD’ is also an acceptable format.
- order – a character string that represents the same value passed through instrumentation and uniquely identifies the invoice number of the customer’s transaction. If this value is natively numeric, it can alternatively be passed as a numeric.
- product - a character string or integer that identifies the product purchased. Frequently merchants will have multiple identifiers for the same item or multiple item options; this value must congruently identify the product as it would be passed through instrumentation. For example, if a purchased item has a catalog SKU of 123456 and a UPC of 12374893872612 and a sub-SKU option of 123456-0004 and the instrumentation passes ‘123456’ to Recommend, the data validation file must contain ‘123456’.
- price – a numeric for the selling price paid by the customer at fulfillment. This should include any discounts applied at the point of sale. This should not include sales tax, shipping fees.
- units – an integer quantifying the number of units sold for that particular product and price. This should be an aggregation of all products sharing the same product and price. Continuing the above example, if the customer purchases 2 units of 123456-0004 and 3 units of 123456-0001, this field should be populated with 5. However, if option 0004 were priced at $5.99 and option 0001 at $6.99, there would be two separate entries for the same product id reflecting the appropriate price for each option.