# Rakuten

[Rakuten](https://rakutenadvertising.com/affiliate/) provides a robust affiliate marketing ecosystem to expand your reach by connecting with a vast and engaged audience across multiple channels.

Find the open source code for this destination in the [GitHub repository](https://github.com/rudderlabs/rudder-transformer/tree/main/src/cdk/v2/destinations/rakuten).

## Setup

1. In your [RudderStack dashboard](https://app.rudderstack.com/), go to **Directory** > **Destinations** > **Cloud Destinations**  and search for **Rakuten**.
2. Connect your source and click **Continue**.

### Connection settings

Configure the following settings to set up Rakuten as a destination in RudderStack:

- **Name**: Assign a name to uniquely identify the destination.
- **Merchant ID**: Enter the numeric merchant ID that uniquely identifies you in the Rakuten marketing system.

### Connection mode

{{< destination-config >}}

## Track

You can use the RudderStack [`track`]({{< ref "event-spec/standard-events/track.md" >}}) event to track events along with any associated properties and send this information to Rakuten.

A sample `track` event is shown below:

```javascript
rudderananlytics.track('event', {
  orderId: "OR122441",
  land: 1234,
  ranSiteId: "823421983a3-231824ft12-e12-gh1208b12-14"
  products: [{
      sku: 'sku1',
      amount: '8' // instead of 10 for 20% discount
      quantity: 1,
      name: 'Product1'
    },
    {
      sku: 'sku2',
      amount: 81 // instead of 90 for 10% discount
      quantity: 2,
      name: 'Product2'
    }
  ]
})
```

### Property mappings

RudderStack maps the following properties to the Rakuten fields:

| RudderStack property | Rakuten property | Limitations |  
| :-----| :----| :-----| 
| `properties.order_id` <br />`properties.orderId` <br/><br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `ord` | <40 non-blank characters | 
| `properties.land` <br />`properties.land_time`<br /> `properties.landTime` <br/><br/> <span style="color: #4D4DFF;font-size:12px;">Required</span> | `land` | Should be present as `YYYYMMDD_HHMM` in the GMT 24-hour format. <br /><br />**Note**: This is the datetime value set in the cookie of your Rakuten Marketing-specific gateway page when a customer arrives at your website. |
| `properties.date` <br />`properties.order_completed_time`<br /> `properties.orderCompletedTime` | date | Should be present as `YYYYMMDD_HHMM` in the GMT 24-hour format. <br /><br />**Note**: Represents the date and time of the online completion (Thank You) page. |
| `properties.altord` <br />`properties.alt_ord`<br />`properties.alter_order_id`<br /> `properties.alterOrderId` |  `altord` | <40 characters <br /><br />**Note**: Alternative version of the reported order ID like a backend version, customer-facing version, etc. |
| `properties.currency` | `cur` | 3 alphanumeric characters matching the currency used by the customer in the transaction. For example, `USD`, `CAD`, `GBP`, `JPY`, `BRL`, `EUR`, `AUD`.  |
| `properties.creditCardType`<br />`properties.credit_card_type` | `cc` | <16 characters |  
| `properties.commreason`<br />`properties.comm_reason` | `commreason` | <255 characters <br /><br />**Note**: Used for reporting only and should be used to show the reason for the commission (`iscomm`) flag. |
| `properties.iscomm`<br /> `properties.is_comm` | `iscomm` | - <br /><br />**Note**: Specifies if a commission is applicable for an order. |
| `properties.consumed` | `consumed` | <13 characters <br /> Should be formatted as  `YYYYMMDD_HHMM` in the GMT 24-hour format.<br />**Note**: Expected date when a travel event is consumed.  |
| `properties.coupon` | `coupon` |  <128 characters | 
| `properties.customerId` <br /> `properties.customer_id` <br /> `properties.cust_id`<br />`properties.custId`<br />`properties.userId` | `custid` | <128 characters <br /><br />**Note**: Identifier representing the customer like ID, hashed email, etc. Make sure to not pass any PII. Any special characters should be URL-encoded into the hex format. |
| `properties.cust_score`<br />`properties.customer_score`<br />`properties.customerScore` <br /> `properties.custScore` |  `custscore` | <16 characters <br /><br />**Note**:  Represents a score assigned to the customer by the system. It can alphabetical, numeric, or alphanumeric. |
| `properties.customerStatus` <br /> `properties.custStatus`<br />`properties.customer_status`<br />`properties.cust_status` | `custstatus` | <32 characters <br /><br />**Note**:  Represents the status of the customer like new, existing, guest, etc. |
| `properties.dId` <br /> `properties.advertisingId`<br />`properties.advertising_id` |  `did` | <42 characters <br /><br />**Note**:  Used for the advertising ID of the mobile device. |
| `properties.discountAmount` <br /> `properties.disAmt`<br />`properties.discount_amount` | `disamt` | <9 characters |
| `properties.orderStatus` <br /> `properties.ordStatus`<br />`properties.order_status` <br /> `properties.ord_status` |  `ordstatus` | <32 characters <br /><br />**Note**: Represents the order status assigned by the system. |
| `properties.tr` <br />`properties.ran_site_id`<br /> `properties.ranSiteID` | `tr` | <34 characters <br /><br />**Note**: Set in a cookie of your Rakuten Marketing-specific gateway page. Can include mixed-case letters, numbers, and special characters like `-`, `.`, `_`, `/`, and `*`. |
| `properties.segment` | `segment` | <32 characters <br /><br />**Note**:  Represents the customer segment. |
| `properties.shipcountry`<br /> `properties.ship_country` | `shipcountry` | <3 characters <br /><br />**Note**:  The country where the order is to be shipped. Must follow the ISO 3-character country code. |
| `properties.shipped` |  `shipped` | Should be present as `YYYYMMDD_HHMM` in the GMT 24-hour format. <br /><br />**Note**: Expected date when the order will be shipped. |
| `properties.sitename` <br /> `properties.site_name`<br /> `properties.url`<br />`context.page.url` | `sitename` | <128 characters <br /><br />**Note**: Identifier representing where the conversion took place like domain name of the site. Any special characters should be URL-encoded in the hex format. |
| `properties.storeId`<br /> `properties.store_id` | `storeid` | <255 characters <br /><br />**Note**: Represents the category of the store where the conversion occurred. |
| `properties.storecat` <br />`properties.store_cat`<br /> `properties.storeCategory `<br /> `properties.store_category` | `storecat` | - <br /><br />**Note**: Represents the category name for the store where the conversion occurred. |

### Item-level mappings

RudderStack maps the following item-level properties to the Rakuten properties:

| RudderStack property | Rakuten property | Limitations |  
| :-----| :----| :-----| 
| `product.$.sku` <br/><br/> <span style="color: #4D4DFF;font-size:12px;">Required</span>| `skulist.$` | - |
| `product.$.amount` <br /> `product.$.(price*quantity)` <br/><br/> <span style="color: #4D4DFF;font-size:12px;">Required</span>| `amtlist.$` |- |
| `product.$.quantity` <br/><br/> <span style="color: #4D4DFF;font-size:12px;">Required</span>| `qlist.$` |- |
| `product.$.name` <br/><br/> <span style="color: #4D4DFF;font-size:12px;">Required</span>| `namelist.$` | - |
| `product.$.brand` | `brandlist.$` | <255 characters. |
| `product.$.coupon` |  `couponlist.$` | - <br /><br />**Note**: Holds a pipe-delimited list of item-level coupons applied to the order. Order of values in this list must match the order of values in `skulist`. Multiple item-level coupon codes are not allowed. | 
| `product.$.categoryId` | `catidlist.$` | <128 characters <br /><br />**Note**: You can specify up to 5 category IDs per item separated by `>`. For example, `(1001>2001>3001)` |
| `product.$.category` | `catlist.$` | <255 characters <br /><br />**Note**: You can specify up to 5 category IDs per item separated by `>`. For example, `(ParentCat>ChildCat1>ChildCat2)` |
| `product.$.discountAmount` | `disamtlist.$` | <9 characters <br /><br />**Note**: Pipe delimited list of item-specific discount amounts formatted as a number. Values must match the order of values in `skulist`. |
| `product.$.discountType` | `distypelist.$` | <256 characters <br /><br />**Note**: Pipe delimited list of item-level discount types. Order of values must match of values in `skulist`. Special characters should be URL-encoded in hex format. |
| `product.$.isClearance` | `isclearancelist.$` | Acceptable values are `Y` or `N` <br /><br />**Note**: Pipe delimited list of flags indicating if the item is on clearance. Values must match the order of values in `skulist`. | 
| `product.$.isMarketPlace` | `ismarketplacelist.$` | Acceptable values are `Y` or `N` <br /><br />**Note**: Pipe delimited list of flags indicating if the item is from a marketplace. Values must match the order of values in `skulist`. | 
| `product.$.isSale` | `issalelist.$` | Acceptable values are `Y` or `N` <br /><br />**Note**: Pipe delimited list of flags indicating if the item is on sale. Values must match the order of values in `skulist`. | 
| `product.$.itmStatus` | `itmstatuslist.$` | <32 characters <br /><br />**Note**: Pipe delimited list of item-level statuses. Order of values in this list must match the order of values in `skulist`.  Possible values are `In-Stock`, `Back-Ordered`, etc. Special characters must be URL-encoded in hex format. | 
| `product.$.margin` | `marginlist.$` | <3 characters <br /><br />**Note**: Pipe delimited list representing profit margin of the products. Order of values in this list must match the order of values in `skulist`. |
| `product.$.markdown` | `markdownlist.$` |<6 characters <br /><br />**Note**: Pipe delimited list representing markdown rate of an item. Order of values in this list must match the order of values in `skulist`. |
| `product.$.sequence` | `sequencelist.$` | <4 characters. <br /><br />**Note**: Identifies the sequence of items included in a shipment or return. |
| `product.$.shipby` | `shipbylist.$` | <32 characters <br /><br />**Note**: Pipe delimited list of strings identifying who shipped the item. Possible values are `Store` if the item is shipped from a physical store, `Fulfullment Vendor X` if shipped by a fulfillment partner, etc. Special characters must be URL-encoded in hex format. |
| `product.$.shipID` | `shipidlist.$` | <32 characters <br /><br />**Note**:  Identifies a collection of items that are shipped or returned together. |
| `product.$.taxexempt` |  `taxexemptlist.$` | Acceptable values are `Y` or `N` <br /><br />**Note**:  Pipe delimited list of flags indicating if the item is tax-exempt. Rakuten then reduces the transaction amount by a defined tax rate. |

## Discount reporting 

For accurate discount reporting, make sure to report only product discounts or discounts that reduce a product subtotal. Do not include free shipping in the discount amount. 

Suppose a customer purchases 1 item of SKU A for $10.00 and 2 items of SKU B for $45.00 each and then redeems a 10% order-level discount. In that case, Rakuten provides two options for reporting discounts:
 
- Reduced item reporting (preferred)
- Discounts as SKU

### Reduced item reporting

{{< info >}}
Rakuten prescribes this reporting method for selected goods commissioning, that is, if you want to commission by product type.
{{< /info >}}

In this case, you can adjust the reported amount value to reflect the applied discounts. In the above example, you can send the amounts in a `product` array as $9.00 and $81.00 respectively for the two SKUs. 

For multiple item purchases, disperse the discounts accordingly among each value in the total amount value.

### Discounts as SKU

{{< info >}}
Rakuten prescribes this method if you intend to set the same commission on all goods.
{{< /info >}}

For this reporting model, add an extra value to the `sku`, `quantity`, `amount`, and the product `name` fields that depict the discount.

- For `sku`, and `name`, use the string `Discount`.
- For `quantity`, use `0`.
- For `amount`, use the negative dollar value of the discount.

A sample `track` event highlighting this method is shown:

```javascript
rudderananlytics.track('event', {
  products: [{
      sku: 'sku1',
      amount: '100'
      quantity: 1
    },
    {
      sku: 'Discount',
      name: 'Discount',
      amount: -10 // Total discount of 10
      quantity: 0
    }
  ]
})
```

## FAQ

#### Why are products commissionable even if `iscomm` is set to `N` (no)?

Note that `iscomm` is applicable for the entire order.

Even if you have `iscomm=N` in the postback, the transaction is still commissionable in Rakuten. You need to explicitly set the dynamic commissioning rules (for example, if `iscomm` equals `N`, pay $0 commission) in the Rakuten dashboard to avoid paying commission for a particular order.

#### How can I report a returned item in `Order Cancelled` or `Partially Cancelled` events?

Suppose a customer returns two items of SKU A and one item of SKU B, the cancellation records would look like below:

```javascript
rudderananlytics.track('event', {
  orderId: "ord123",
  land: 1133,
  ranSiteId: "846t21983y3-231824et12-e12-ey1208e12-14",
  cur: 'USD',
  products: [{
      sku: 'A',
      amount: '-200'
      quantity: 2,
      name: 'name_1'
    },
    {
      sku: 'B',
      amount: -10
      quantity: 1,
      name: 'name_2'
    }
  ]
})
```

Note that the quantity shows the number of returned items and price is negative, reflecting the return. Quantity is not a negative number for returns unless the price in the original order was zero.

You must also account for any discounts applied during the order cancellation. For reduced item discount reporting, note that:

- If you are using discount as a SKU option, send a cancellation record for the discount SKU item **in addition** to the regular SKUs of the order for cancellation.

<br />