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

For more information about sync modes, refer to the sync modes docs.

Connect to Rakuten

Go to the Destinations overview page 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.

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 to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page 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.

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. 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.

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 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

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

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.

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

If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.

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

Live debugger

Hightouch provides complete visibility into the API calls made during each of your sync runs. We recommend reading our article on debugging tips and tricks to learn more.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.