Version 2.3. Updated June 2024.
Introduction
This document details the process to integrate tracking with your online-to-offline (O2O) system and the advertisers you are partnered with on the Rakuten Affiliate Network. The process outlined in this guide assumes you have worked with the advertisers to complete any integration necessary to enable the O2O functionality with their system.
Online Tracking
Traffic referred by the O2O campaign is sent directly to a customized landing or through a tracking redirect before delivering the user to the landing page. Our system exposes a tracking ID to this process. The tracking ID is passed under the query parameter siteID and holds a 34-character alphanumeric value:
http://www.o2o-advertiser.com/landing/somepage?siteID=xxxxxxxxxxx-yyyyyyyyyyyyyyyyyyyy
http://www.o2o-provider.com/redirect?a=b&siteID=yyyyyyyyyy-xxxxxxxxxxxxxxxxxxxxxxYour process must capture the siteID value, associate it with the user, and later with the online redemption action. For example, the online redemption action can be linking a credit card number or printing an in-store coupon.
Offline Tracking: Transaction Reporting
Report any applicable O2O sales that occur directly to our system. Sales must be structured as individual flat files per advertiser partner using a JSON data structure.
JSON Transaction Example
Note
Some of the examples in this document are formatted using pretty print for visual purposes. Actual JSON content must be formatted as outlined in the JSON File Structure section below.
{
"sku_order": {
"orderid": "TEST1234",
"siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q",
"time_entered": "2018-04-03T10:22:01Z",
"currency": "USD",
"trans_date": "2018-04-07T17:58:58Z",
"items": [
{
"sku": "O2O_SKUA",
"quantity": "1",
"amount": "4999",
"product_name": "O2O: Product A"
},
{
"sku": "O2O_SKUB",
"quantity": "3",
"amount": "1998",
"product_name": "O2O: Product B"
}
],
"optional_data": {
"o2o_store_id": "123456",
"o2o_store_name": "Store Name 1",
"o2o_store_address": "123 Some St",
"o2o_store_city": "Some City",
"o2o_store_state": "Some State",
"o2o_store_zip": "11111",
"o2o_store_country": "USA",
"o2o_bank_partner": "American Express"
}
}
} JSON Fields
Use the following fields when creating your file. Fields marked with an asterisk character (*) are required; click the + for more information:
This object contains information for the entire order and must include these elements: orderid, siteid, time_entered, currency, trans_date, and the items array.
This is a unique transaction OrderID composed of 1 to 40 non-blank characters.
This is the siteID value that was attributed to the online redemption event. If tracking is not implemented for the online redemption event, specify your encrypted Publisher ID. Note that siteID is used for u1 reporting purposes. By using the encrypted Publisher ID, you will not have access to the same level of data in reporting.
This field represents the date the user initiated the online redemption event. If tracking is not implemented for the online redemption event, specify the offline transaction date and time stamp.
Should be formatted yyyy-mm-ddThh:mm:ssZ in GMT 24-hour. The T delimiter between date and time and the Z at the end of the value are required.
The ISO4217 currency code reference. Use USD, CAD, GBP, JPY, BRL, or AUD for US dollar, Canadian dollar, British pound, Japanese yen, Brazilian real, or Australian dollar, respectively.
This field represents the date the offline transaction was completed.
Should be formatted yyyy-mm-ddThh:mm:ssZ in GMT 24-hour. The T delimiter between date and time and the Z at the end of the value are required.
This array should contain an object representing each product or service purchased. The item object should contain the elements sku, quantity, amount, and product_name.
This is a unique identifier for each product and service. It can be up to 40 case-sensitive alphanumeric characters. Append the prefix O2O_ to every SKU value; for example, report O2O_123abc for the SKU 123abc.
If you do not have access to product-level purchase details, use O2O_order as the SKU value.
The number of units of this product the customer has purchased.
If you do not have access to product-level purchase details, use 1 (one) as the Quantity value.
This is unit price * units sold * 100; for example, five units sold at $1.00 are entered at 500. This excludes shipping and tax. For example, using GBP as the currency: 3 units sold at £1.25 is output as 375.
If you do not have access to product-level purchase details, report the order sub-total or total as the amount value. The same data format rule applies: the order amount should be calculated as order sub-total * 100.
This field can be up to 512 alphanumeric characters. It provides a brief description or name for a product or service. Append the prefix O2O: to every product name value; for example, report O2O: Boots for the product name Boots.
If you do not have access to product-level purchase details, use O2O Order as the product name value.
If you do not know the product name, include the field but leave the value blank.
Special characters should be omitted or converted into HTML entity codes.
The object should be nested within the sku_order object and should include the following store elements: o2o_store_id, o2o_store_name, o2o_store_address, o2o_store_city, o2o_store_state, o2o_store_zip, o2o_store_country, o2o_bank_partner.
The ID assigned to the store where the purchase occurred.
The name of the store where the purchase occurred.
The address of the store where the purchase occurred.
The city of the store where the purchase occurred.
The state of the store where the purchase occurred.
The ZIP code of the store where the purchase occurred.
The country of the store where the purchase occurred.
The bank partner associated with the store where the purchase occurred.
JSON File Structure
The file’s content must be structured as a single JSON object per line, with the line being terminated by a newline character. Below are file examples depending on the level of data you have access to. Click the + to view item-level and order-level examples:
Follow this example if you have access to product-level purchase details:
{"sku_order": {"orderid": "TEST1234","siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q","time_entered": "2018-04-03T10:22:01Z","currency": "USD","trans_date": "2018-04-07T17:58:58Z","items": [{"sku": "O2O_SKUA","quantity": "1","amount": "4999","product_name": "O2O: Product A"},{"sku": "O2O_SKUB","quantity": "3","amount": "1998","product_name": "O2O: Product B"}],"optional_data" : {"o2o_store_id": "123456","o2o_store_name": "Store Name 1","o2o_store_address": "123 Some St","o2o_store_city": "Some City","o2o_store_state": "Some State","o2o_store_zip": "11111","o2o_store_country": "USA","o2o_bank_partner": "American Express"}}}
{"sku_order": {"orderid": "TEST345","siteid": "lMh2Xiq9xN0-dc5SYTV2VtSx1aH6tvQl8Q","time_entered": "2018-04-06T21:00:32Z","currency": "USD","trans_date": "2018-04-07T21:32:55Z","items": [{"sku": "O2O_SKUA","quantity": "1","amount": "4999","product_name": "O2O: Product A"},{"sku": "O2O_SKUB","quantity": "3","amount": "1998","product_name": "O2O: Product B"}],"optional_data" : {"o2o_store_id": "123456","o2o_store_name": "Store Name 2","o2o_store_address": "345 Another St","o2o_store_city": "Another City","o2o_store_state": "Another State","o2o_store_zip": "22222","o2o_store_country": "USA","o2o_bank_partner": "American Express"}}} Follow this example if you do not have access to product-level purchase details:
{"sku_order": {"orderid": "TEST1234","siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q","time_entered": "2018-04-03T10:22:01Z","currency": "USD","trans_date": "2018-04-07T17:58:58Z","items": [{"sku": "O2O_order","quantity": "1","amount": "9999","product_name": "O2O Order"}],"optional_data": {"o2o_store_id": "123456","o2o_store_name": "Store Name 1","o2o_store_address": "123 Some St","o2o_store_city": "Some City","o2o_store_state": "Some State","o2o_store_zip": "11111","o2o_store_country": "USA","o2o_bank_partner": "American Express"}}}
{"sku_order": {"orderid": "TEST345","siteid": "lMh2Xiq9xN0-dc5SYTV2VtSx1aH6tvQl8Q","time_entered": "2018-04-06T21:00:32Z","currency": "USD","trans_date": "2018-04-07T21:32:55Z","items": [{"sku": "O2O_order","quantity": "1","amount": "35999","product_name": "O2O Order"}],"optional_data": {"o2o_store_id": "123456","o2o_store_name": "Store Name 2","o2o_store_address": "345 Another St","o2o_store_city": "Another City","o2o_store_state": "Another State","o2o_store_zip": "22222","o2o_store_country": "USA","o2o_bank_partner": "American Express"}}} Special Considerations
Each element in the items array reflects a unique product (SKU). If a customer places an order with three quantities of product A costing $100 each and one quantity of product B costing $10 each, the items array should contain two distinct elements: one for each product item.
Purchases of the same SKU must be represented as an aggregated element in the array. This is more applicable to product variants depending on the SKU value you report. For example, a customer places one order with two quantities of T-shirt costing $10 each, one blue and one white. If the SKU value only identifies the product, you must report this as a single element in the items array with a combined quantity and amount. If the SKU value identifies the product and variant detail, you can report this as separate elements in the items array.
File Delivery
Files should be delivered via SFTP to mftp.linksynergy.com. Your Rakuten Affiliate Network contact will provide you with credentials to your SFTP account. You must provide us with the static IP address of the machine that will transmit the files.
File Naming Convention
The transaction files must follow this name convention:
[MID]_o2o-trans_[YYYYMMDD]*.json
Where:
- [MID] is the advertiser’s unique identifier in the Rakuten Affiliate Network. You can find an advertiser’s MID in the Publisher Dashboard by going to Advertisers in the navigation header and clicking My Advertisers. From there, click the advertiser’s name to view their profile page, where their MID is displayed.
- [YYYYMMDD] is the date of transmission.
- The asterisk character (*) is an optional wildcard you can use to distinguish each file further if you send more than one file per advertiser in a given day.
Accounting for Discounts
Order discounts can be reported as part of your order submission to the Rakuten Affiliate Network. To report a discount, use one of these two options; click the + for more information:
If a customer purchases one SKU A for $10.00 and two SKU B for $45.00 each and redeems a 10% order-level discount, adjust the reported amount value to reflect the applied discounts using the following logic:
- First, determine each item's percent of the order subtotal with this calculation: (product price * quantity) / order subtotal = item percent
- Next, determine the amount of the discount to apply to each item with this calculation: discount amount * item percent = item applicable discount
- Finally, subtract the item applicable discount value from the item subtotal. This is the amount you should report.
In the example provided above, the amounts sent would be $9.00 and $81.00, as shown here:
{ "sku_order": {
"orderid": "TEST1234",
"siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q",
"time_entered": "2018-04-03T10:22:01Z",
"currency": "USD",
"trans_date": "2018-04-07T17:58:58Z",
"items": [
{ "sku": "O2O_SKUA",
"quantity": "1",
"amount": "900",
"product_name": "O2O: Product A"
},{
"sku": "O2O_SKUB",
"quantity": "3",
"amount": "8100",
"product_name": "O2O: Product B"
}],
"optional_data": {
"o2o_store_id": "123456",
"o2o_store_name": "Store Name 1",
"o2o_store_address": "123 Some St",
"o2o_store_city": "Some City",
"o2o_store_state": "Some State",
"o2o_store_zip": "11111",
"o2o_store_country": "USA",
"o2o_bank_partner": "American Express"
}}} Include an extra record within the data submission depicting the discount:
- For SKU, enter the string O2O_Discount.
- For quantity, enter a 0.
- For amount, enter a negative dollar value of the discount (in cents).
- For product name, enter O2O: Discount.
This is an example of option 2 with a $5 Discount SKU:
{
"sku_order": {
"ordered": "TEST1234",
"siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q",
"time_entered": "2018-04-03T10:22:01Z",
"currency": "USD",
"trans_date": "2018-04-07T17:58:58Z",
"items": [
{
"sku": "O2O_SKUA",
"quantity": "1",
"amount": "2000",
"product_name": "O2O: Product A"
},{
"sku": "O2O_Discount",
"quantity": "3",
"amount": "-500",
"product_name": "O2O: Product B"
}
],
"optional_data": {
"o2o_store_id": "123456",
"o2o_store_name": "Store Name 1",
"o2o_store_address": "123 Some St",
"o2o_store_city": "Some City",
"o2o_store_state": "Some State",
"o2o_store_zip": "11111",
"o2o_store_country": "USA",
"o2o_bank_partner": "American Express"
}
}
} Cancellations and Returns
To report order cancellations, resend the original record lines with a negative amount (or positive in the case of discounts). To report returns, similarly resend the originally reported record and adjust the quantity and amount to reflect the return.
Using our original example in the Special Considerations section, if a customer purchases three quantities of product A at $100 apiece and one quantity of product B at $10, this should be reported as follows:
{"sku_order": {"orderid": "TEST1234","siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q","time_entered": "2018-04-03T10:22:01Z","currency": "USD","trans_date": "2018-04-07T17:58:58Z","items": [{"sku": "O2O_SKUA","quantity": "3","amount": "30000","product_name": "O2O: Product A"},{"sku": "O2O_SKUB","quantity": "1","amount": "1000","product_name": "O2O: Product B"}],"optional_data": {"o2o_store_id": "123456","o2o_store_name": "Store Name 1","o2o_store_address": "123 Some St","o2o_store_city": "Some City","o2o_store_state": "Some State","o2o_store_zip": "11111","o2o_store_country": "USA","o2o_bank_partner": "American Express"}}} If the customer cancels the full order, resend the records with a negative amount value:
{"sku_order": {"orderid": "TEST1234","siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q","time_entered": "2018-04-03T10:22:01Z","currency": "USD","trans_date": "2018-04-07T17:58:58Z","items": [{"sku": "O2O_SKUA","quantity": "3","amount": "-30000","product_name": "O2O: Product A"},{"sku": "O2O_SKUB","quantity": "1","amount": "-1000","product_name": "O2O: Product B"}],"optional_data": {"o2o_store_id": "123456","o2o_store_name": "Store Name 1","o2o_store_address": "123 Some St","o2o_store_city": "Some City","o2o_store_state": "Some State","o2o_store_zip": "11111","o2o_store_country": "USA","o2o_bank_partner": "American Express"}}} Alternatively, if the customer returns two quantities of product A and one quantity of product B, this should be reported as follows:
{"sku_order": {"orderid": "TEST1234","siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q","time_entered": "2018-04-03T10:22:01Z","currency": "USD","trans_date": "2018-04-07T17:58:58Z","items": [{"sku": "O2O_SKUA","quantity": "3","amount": "-2000","product_name": "O2O: Product A"},{"sku": "O2O_SKUB","quantity": "1","amount": "-1000","product_name": "O2O: Product B"}],"optional_data": {"o2o_store_id": "123456","o2o_store_name": "Store Name 1","o2o_store_address": "123 Some St","o2o_store_city": "Some City","o2o_store_state": "Some State","o2o_store_zip": "11111","o2o_store_country": "USA","o2o_bank_partner": "American Express"}}} When cancelling an order, you must account for any applied discounts. If you use option 1 from the Accounting for Discounts section to report the discount, the cancellation data you report must reflect the discounted item price.
If you use option 2 from the Accounting for Discounts section to report a discount, you must send a cancel record for the discounted item. To do this, report the discount record with a positive amount. This is an example of option two that cancels the order record used in the Example $5.00 Discount SKU:
{"sku_order": {"orderid": "TEST1234","siteid": "lMh2Xiq9xN0-73ivYTV2VtSbVaH6tvQl8Q","time_entered": "2018-04-03T10:22:01Z","currency": "USD","trans_date": "2018-04-07T17:58:58Z","items": [{"sku": "O2O_SKUA","quantity": "1","amount": "-2000","product_name": "O2O: Product A"},{"sku": "O2O_Discount","quantity": "3","amount": "500","product_name": "O2O: Product B"}],"optional_data": {"o2o_store_id": "123456","o2o_store_name": "Store Name 1","o2o_store_address": "123 Some St","o2o_store_city": "Some City","o2o_store_state": "Some State","o2o_store_zip": "11111","o2o_store_country": "USA","o2o_bank_partner": "American Express"}}} Attention
Any cancellation or return must be reported within 90 days of the original record being reported. Cancellations and returns reported after 90 days will not be accepted.
Comments
Please sign in to leave a comment.