Introduction

The Postback API is provided by the Rakuten Advertising API Developer Portal. Visit the portal for a complete list of the APIs we offer.

Application

The Postback API allows you to receive transaction events as they are processed into our system. It is designed to provide data similar to the Events API, except we push this data to you so that you do not need to fetch it via the Events API.

You can use the API to:

• Set up a postback for a specific publisher ID.
• Update the postback URL.
• Delete the postback URL.
• Disable or enable a postback.

Beta Functionality

The Postback API is currently in beta as we are seeking user feedback for enhancements. The functionality of the postback will not be affected with any future enhancements. The enhancements will only affect user interaction with the API.

Access

You can view detailed instructions on using the Postback API in the portal. Use your Publisher Dashboard login credentials to log in.

Before getting started, you need the following:

• A URL for the postback. This URL is customizable, as detailed below.
• The API access token. View instructions for retrieving an API access token.

Additionally, your user account must be associated with the publisher ID that implements the postback.

Setting Up a Postback URL

The Postback API can support dynamic URLs, allowing you to customize the output. Your postback URL should include:

1. Your site URL.
2. The is_event=<is_event> field.
3. Parameters for any other fields you want to include. These are customizable; see the Customizable Fields section below for more details. If you include several parameters, these should be separated by an ampersand (&).

For example, if your website is https://www.my-pretty-postback-URL.com and you want to include the transaction_date and sku_number fields, your postback URL will be:

https://www.my-pretty-postback-URL.com?is_event=<is_event>& transaction_date=<transaction_date>&sku_number=<sku_number>

For more information on the purpose of the is_event=<is_event> field and how to interpret your data, view the Events API Transactions guide in the Developer Portal.

Customizable Fields

The following customizations are allowed:

• Renaming field names.
• Receiving only certain fields.
• Reordering the fields.
• Using static values.

We recommend you review the Events API Common Questions and the Events API Push/Postback Guide in the Developer Portal for a list of available fields and postback customization examples.

Examples of Customization Requests

• Example 1: Rename u1 to unique_id
• Example 2: Only include the following fields:
  • transaction_date
  • sku_number
  • quantity
  • commissions
• Example 3: Only include the following fields and rename the following:
  • transaction_date
  • sku_number
  • quantity
  • commissions
  • Rename u1 to unique_id

Troubleshooting

If your postback endpoint is receiving incorrect data or no data at all, please:

• Confirm that your endpoint meets our timeout limit of 400ms. Our server will not send data if your endpoint URL takes longer than 400ms to respond to the request. Only one connection attempt is made. Data is not re-sent if a connection attempt is rescinded or fails.
• Check that data exists by running an Individual Item Report with the Member ID (u1) field. Note that it can take up to four hours for data to show up in a report.
• You will not be notified if your postback is disabled automatically. We recommend you use the endpoint status API call to check if a postback is disabled or active.

We also provide a list of specific error messages and their meaning in the Developer Portal Guides. If you are still experiencing issues, reach out to Customer Support with specific order IDs or dates when data was not received.