> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rakuten

> Send Ad Conversion Transactions to the Rakuten Transactions API

## Overview

Rakuten Advertising is a global affiliate marketing platform that connects advertisers with publishers to drive conversions and track affiliate performance. With the Rakuten destination, you can sync transaction and conversion event data from your data warehouse to Rakuten's Advertiser Transaction API, enabling accurate affiliate attribution and commission tracking.

This destination supports comprehensive transaction tracking for multiple verticals including Retail, Travel, and Financial services, with both affiliate-attributed (click-based) and Linkless transaction types.

## Supported syncing

| Sync Type | Description | Supported Sync Modes | API Reference |
| - | - | - | - |
| **Events** | Sync transaction/conversion events from any source to Rakuten | Insert | [Rakuten API docs](https://api.linksynergy.com/docs) |

For more information about sync modes, refer to the [sync modes](https://docs.hightouch.com/syncs/types-and-modes.md#sync-modes) docs.

## Connect to Rakuten

Go to the [**Destinations** overview page](https://app.hightouch.com/destinations?from=docs) and click the **Add destination** button. Select **Rakuten** and click **Continue**.

You need to provide the following credentials:

* **Client ID**: Your Rakuten API client ID
* **Client Secret**: Your Rakuten API client secret
* **Advertiser ID (MID)**: Your Rakuten Merchant ID (numeric, up to 5 digits)

### Obtain API credentials

Contact your Rakuten Advertising account representative to obtain API credentials. You'll need credentials with access to the Advertiser Transaction API endpoint.

> [!WARNING]
>
> The Advertiser ID must be numeric and no more than 5 characters. Verify your credentials by testing the connection before creating syncs.

## Sync configuration

Once you've set up your Rakuten destination and have a [model](https://docs.hightouch.com/getting-started/concepts.md#models) to pull data from, you can set up your sync configuration to begin syncing data. Go to the [**Syncs** overview page](https://app.hightouch.com/syncs?from=docs) and click the **Add sync** button to begin. Then, select the relevant model and the Rakuten destination you want to sync to.

### Event timestamp

Select the column from your model that contains the transaction timestamp. This becomes the `transaction_datetime` in Rakuten and must be in a valid datetime format. The timestamp is automatically converted to ISO 8601 UTC format.

> [!WARNING]
>
> Transaction timestamps cannot be in the future. Ensure your transaction datetime values represent when the transaction occurred.

### Field mapping

Hightouch lets you sync transaction fields via [field mapping](https://docs.hightouch.com/syncs/mapping-data.md). You can map data from any of your model columns to Rakuten's transaction fields.

#### Required fields

You must map the following fields to complete your configuration:

* **Order ID**: A unique identifier for the transaction (max 40 characters)
* **Currency**: ISO 3-character currency code (e.g., `USD`, `EUR`, `GBP`)
* **Items**: An array of line item objects (see Items array section below)

#### Tracking fields

These optional fields enable affiliate attribution:

* **Click ID (ranSiteID)**: The Rakuten tracking parameter captured from affiliate redirects. This is a 34-character identifier. For Linkless transactions, this field can be omitted.
* **Landing datetime**: The UTC timestamp when the user landed on your site from the affiliate link. If not provided, this automatically defaults to 5 minutes before the transaction timestamp to ensure API compliance.

> [!NOTE]
>
> For affiliate-attributed transactions, capture the `ranSiteID` parameter from the referring URL when users arrive from Rakuten affiliate links. This enables proper commission attribution.

#### Items array

Each transaction requires at least one item. Use the [inline mapper](https://docs.hightouch.com/syncs/mapping-data.md#inline-mapping) to structure the items array. Each item in the array must include:

**Required item fields:**

* `sku`: Product identifier (max 40 characters)
* `product_name`: Product name (max 512 characters)
* `amount`: Item subtotal (post-discount, excluding tax)
* `quantity`: Number of units

**Optional item fields:**

* `order_item_id`: Unique identifier for the line item
* `brand`: Product brand name
* `category`: Product category path (e.g., `Electronics>Widgets`)
* `category_id`: Category identifier
* `coupon`: Item-level coupon code applied
* `discount_amount`: Item-level discount amount
* `discount_type`: Type of discount applied
* `is_clearance`: Whether the item is on clearance
* `is_sale`: Whether the item is on sale
* `marketplace_store`: Marketplace store name
* `product_id`: Additional product identifier

> [!TIP]
>
> Use the inline mapper to transform your source data into the required array format. If your data has one row per order, you'll need to structure the items as a JSON array.

#### Optional transaction fields

Rakuten supports extensive optional fields organized by vertical:

**General/Retail fields:**

* `alternative_order_id`, `customer_id`, `customer_status`, `customer_rank`, `customer_segment`
* `coupon`, `credit_card_type`, `commission_reason`
* `discount_amount`, `discount_type`, `order_status`
* `purchase_site`, `ship_country`, `shipped_datetime`
* `store_id`, `store_category`

**Travel fields:**

* `check_in_datetime`, `check_out_datetime`
* `reservation_start_datetime`, `reservation_end_datetime`, `reservation_length_in_days`
* `cancel_deadline_datetime`, `consumed_datetime`

**Financial fields:**

* `autopay`, `home_ownership`
* `loan_amount_requested`, `loan_apr`, `loan_approval_datetime`
* `loan_offer_apr`, `loan_offer_badge`, `loan_offer_term`
* `loan_origination_fee`, `loan_model_number`, `loan_purpose_applicant`
* `loan_term_in_months`, `monthly_housing_payment`, `publisher_lead_id`

**Offline tracking (O2O) fields:**

* `o2o_bank_partner`, `o2o_store_id`, `o2o_store_zip`

### Sync behavior

Rakuten processes transactions individually via POST requests. The destination automatically:

* Formats datetime values to Rakuten's required ISO 8601 format (without milliseconds)
* Validates the items array contains at least one item
* Handles authentication token management and refresh
* Provides detailed error messages from Rakuten's validation

## Tips and troubleshooting

To see the exact API requests and responses from each sync run, use the [live debugger](https://docs.hightouch.com/syncs/debugger.md). To get notified by Slack, PagerDuty, SMS, or email when a sync fails, set up [sync alerts](https://docs.hightouch.com/syncs/alerting.md). If you run into an issue this page doesn't cover, [contact support](#pylon-chat).

### Linkless transactions

For Linkless transactions (conversions without an affiliate click), you can omit the `click_id` field. The destination automatically sets a default `landing_datetime` value (5 minutes before the transaction) to ensure API compliance.

### Date format requirements

All datetime fields must be convertible to ISO 8601 UTC format. The destination handles the conversion automatically, but ensure your source data contains valid datetime values.

> [!NOTE]
>
> The `landing_datetime` must be before the `transaction_datetime`. If you provide a landing datetime that occurs after the transaction, the Rakuten API will reject the request.

### Field length limits

Rakuten enforces strict field length limits:

* `order_id`: Maximum 40 characters
* `sku`: Maximum 40 characters
* `product_name`: Maximum 512 characters

Ensure your source data respects these limits to avoid validation errors.

## Common errors

### Authentication errors

If you receive 401 or 403 authentication errors:

* Verify your Client ID and Client secret are correct
* Confirm the credentials have access to the Advertiser Transaction API
* Check that your Advertiser ID (MID) matches your account

### Validation errors

If you receive 400 validation errors, check the error details for:

* Missing required fields (order\_id, currency, items)
* Empty items array (at least one item is required)
* Invalid field formats (especially datetime fields)
* Field values exceeding length limits

### Items array errors

If you receive errors about the items array:

* Ensure the items field is a valid array with at least one item
* Verify each item has all required fields: `sku`, `product_name`, `amount`, `quantity`
* Check that numeric fields (`amount`, `quantity`) contain valid numbers