Amazon Selling Partner

Overview

The Amazon Selling Partner integration connects returns.cloud with Amazon Seller Central accounts that use the Fulfilled by Merchant (FBM) program. It automatically retrieves return requests that were processed through Amazon's prepaid return label service and imports them into returns.cloud.

Each imported return is automatically created as a Return Order and linked to its corresponding Sales Order, ensuring a seamless data flow. If a Return Order for that return already exists, the system updates the existing record instead of creating a duplicate.

Returns imported through this integration are marked with the origin value "integration" in the ReturnOrderOriginEnum. This allows you to identify and filter Amazon-originated returns in queries and automations.

Prerequisites

Before the integration can process returns, the following conditions must be met.

The Sales Channels for each Amazon marketplace you want to import from must already exist in returns.cloud. During the integration setup, you will map each Amazon country marketplace to a Sales Channel. If the required Sales Channels have not been created yet, you need to set them up first. See the Sales Channel documentation for instructions.

The Sales Orders must already exist in returns.cloud and they must be located in the same Sales Channel that is mapped to the corresponding Amazon marketplace. For example, if a return comes from the German Amazon marketplace and that marketplace is mapped to the Sales Channel "MyBrand / Amazon DE", the original Sales Order must also exist in that same Sales Channel. If the Sales Order is missing or exists in a different Sales Channel, the matching will fail and the return cannot be linked. The integration does not create Sales Orders. They need to be imported beforehand, either through the GraphQL API, another integration, or manually.

Item matching is done by SKU. The SKU used in the Amazon return must match the SKU of an Item Variation in returns.cloud. If no match is found, the return item cannot be assigned correctly.

Setup and Configuration

To set up the Amazon Seller Portal integration, navigate to the integration settings in returns.cloud and add a new integration of the type "Amazon Selling Partner".

Step 1: General Settings

Name: Enter a descriptive name for this integration, for example "Amazon" or "Amazon DE". This name is only used internally to identify the integration in your settings.

Step 2: Connection Settings

Interval: Define how often the integration should synchronize with Amazon. The value is set in hours. The recommended interval is 2 hours. A shorter interval means returns appear faster in returns.cloud, but very short intervals are usually not necessary.

Initial report start time: Set the date and time from which the integration should start fetching return data. The format is YYYY-MM-DD HH:mm:ss, for example 2026-03-01 00:00:00. Only returns created on or after this date will be imported. This is useful when you activate the integration for the first time and want to avoid importing very old returns.

Main Marketplace: Select the Amazon marketplace that this integration should connect to, for example Germany, France, or United States. This determines which regional Amazon Selling Partner API endpoint is used.

Authorization remainder email: Enter an email address that will receive notifications when the authorization token expires or needs to be renewed. This ensures that someone on your team is alerted before the integration stops working due to an expired token.

Step 3: Authorization

After filling in all fields, click Submit to save the integration. Once saved, the configuration page will show an additional Authorization section with an Authorize button.

Click the Authorize button. You will be redirected to an Amazon-branded authorization page. On that page, log in with your Amazon Seller Central credentials and grant returns.cloud permission to access your seller account data.

After successful authorization, the system stores the authorization token. The integration is now active and will begin fetching returns at the configured interval, starting from the initial report start time.

If the authorization token expires, the contact specified in the authorization remainder email field will be notified. In that case, return to the integration settings and click Authorize again to renew the token.

Step 4: Test the Connection

After authorization, you can use the Test button to verify that the connection to Amazon is working correctly. A successful test confirms that the credentials are valid and the marketplace is reachable.

Step 5: Import Settings (Sales Channel Mapping)

After a successful connection test, navigate to the Import Settings tab in the integration configuration. This step is required before the integration can start fetching returns.

The Import Settings page shows a list of all Amazon country marketplaces that are available under your Seller Central account, for example DE (Germany), FR (France), GB (Great Britain), ES (Spain), NL (Netherlands), and others.

For each country marketplace, you need to assign a Target sales channel. This tells the system into which returns.cloud Sales Channel the returns from that specific Amazon marketplace should be imported. The dropdown lists all Sales Channels that have been created in returns.cloud.

If you do not want to import returns from a specific marketplace, leave the selection on "Do not import". Only marketplaces with an assigned Sales Channel will be included in the synchronization.

Important: The Sales Channels must already exist in returns.cloud before you can assign them here. If the Sales Channel you need is not listed in the dropdown, create it first. See the Sales Channel documentation for details on how to set up Sales Channels.

Example: If you sell on Amazon Germany and Amazon France, and you have two Sales Channels named "MyBrand / Amazon DE" and "MyBrand / Amazon FR", you would assign DE to the first and FR to the second. All other marketplaces can remain on "Do not import".

This mapping also determines which Amazon return reports the system fetches. The integration only requests reports for marketplaces that have a Sales Channel assigned, which keeps the data import focused and efficient.

The Sales Channel mapping is also critical for matching returns to their original Sales Orders. When the integration imports a return from a specific Amazon marketplace, it searches for the corresponding Sales Order within the mapped Sales Channel. Make sure that your Sales Orders are imported into the same Sales Channel that you assign to the respective Amazon marketplace here. If the Sales Order exists in a different Sales Channel, the system will not find it and the return cannot be linked.

How It Works

The integration runs on a scheduled basis and performs the following steps:

1. It connects to the configured Amazon Seller Central account via the Selling Partner API.
2. It retrieves new and updated return requests from FBM orders that use Amazon's prepaid return labels.
3. For each return, it looks up the matching Sales Order in returns.cloud by the Amazon order reference.
4. It creates a new Return Order or updates an existing one, linking it to the Sales Order.
5. Each return item is matched to a Sales Order Item using the SKU.
6. If return reason mapping has been configured, the return reason provided by the customer on Amazon is translated to the corresponding returns.cloud Return Reason. If no mapping is configured, the return reason field remains empty.

Return Reason Mapping (Optional)

Amazon uses its own set of return reasons when a customer initiates a return. These reasons do not match the Return Reasons configured in returns.cloud. To have return reasons included in the imported Return Orders, you need to map them manually.

The mapping is configured in the Configuration tab of the integration settings. The page shows a list of all Amazon return reasons. For each Amazon reason, you can select the corresponding returns.cloud Return Reason from a dropdown.

This step is optional. If you do not configure the mapping, the integration will still import returns, but the Return Order Items will not have a return reason assigned. This means automations or reports that depend on return reasons will not have that data available for Amazon returns.

If you do configure the mapping, each imported return item will carry the mapped returns.cloud Return Reason. This keeps the data consistent across all channels and allows automations, reporting, and downstream systems to work with reliable reason data.

You can update the mapping at any time. Changes apply to newly imported returns. Already imported Return Orders are not retroactively updated when you change the mapping.

Forwarding Returns to Connected Systems

Once a Return Order has been created by the Amazon integration, it can be forwarded to other connected systems. This happens through the existing returns.cloud integration and automation capabilities.

Common target systems include shop systems like Shopify or ERP solutions like Microsoft Business Central. The forwarding can be configured to trigger automatically when a return reaches a certain status, or it can be handled manually.

This means Amazon returns are processed in the same workflow as returns from any other channel, all managed centrally in returns.cloud.

Key Data Points

The following data is imported or derived for each Amazon return:

Return Order level:

• Link to the original Sales Order
• Return status
• Origin set to "integration"
• Sales Channel assignment
• Shipping and consumer information from the original order

Return Order Item level:

• SKU (used for item matching)
• Quantity
• Mapped Return Reason
• Link to the original Sales Order Item

Return Order Parcel level:

• Tracking number from the Amazon prepaid return label
• Parcel status