ContextQMD
Back to Airbyte

Amazon Seller Partner

docs/integrations/sources/amazon-seller-partner.md

2.0.055.5 KB
Original Source

Amazon Seller Partner

<HideInUI>

This page contains the setup guide and reference information for the Amazon Seller Partner source connector.

</HideInUI>

Prerequisites

  • Amazon Seller Partner account
  • For Brand Analytics streams (Market Basket Analysis, Search Terms, Repeat Purchase, Alternate Purchase, Item Comparison reports): Registration in Amazon Brand Registry and the Brand Analytics role in your SP-API application
  • For PII access in Orders and OrderItems streams (BuyerInfo, ShippingAddress): An approved Restricted Role, either Direct-to-Consumer Shipping or Tax Invoicing, in your SP-API developer profile
<!-- env:cloud -->

For Airbyte Cloud:

  • AWS Environment
  • AWS Region
  • AWS Seller Partner Account Type
  • Granted OAuth access
<!-- /env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

  • AWS Environment
  • AWS Region
  • AWS Seller Partner Account Type
  • LWA Client Id
  • LWA Client Secret
  • Refresh Token
<!-- /env:oss -->

Supported regions

The connector supports the following Amazon marketplace regions: AE (United Arab Emirates), AU (Australia), BE (Belgium), BR (Brazil), CA (Canada), DE (Germany), EG (Egypt), ES (Spain), FR (France), GB (United Kingdom), IN (India), IT (Italy), JP (Japan), MX (Mexico), NL (Netherlands), PL (Poland), SA (Saudi Arabia), SE (Sweden), SG (Singapore), TR (Turkey), UK (United Kingdom), and US (United States).

Both GB and UK refer to the United Kingdom marketplace and can be used interchangeably. For the complete list of Amazon marketplace IDs, see the Amazon SP-API documentation.

Setup guide

Step 1: Set up Amazon Seller Partner

Register your Amazon Seller Partner account.

<!-- env:oss -->

Airbyte Open Source setup steps

  • Register Amazon Seller Partner application. The application must be published as Amazon does not allow external parties such as Airbyte to access draft applications.
<!-- /env:oss -->

Step 2: Set up the source connector in Airbyte

To pass the check for Seller and Vendor accounts, you must have access to the Orders endpoint and the Vendor Orders endpoint, respectively.

<!-- env:cloud -->

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. Click Sources and then click + New source.
  3. On the Set up the source page, select Amazon Seller Partner from the Source type dropdown.
  4. Enter a name for the Amazon Seller Partner connector.
  5. Click Authenticate your account.
  6. Log in and Authorize to your Amazon Seller Partner account.
  7. For Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. This field is optional - if not provided or older than 2 years ago from today, the date 2 years ago from today will be used.
  8. For End Date, enter the date in YYYY-MM-DD format. Any data after this date will not be replicated. This field is optional - if not provided, today's date will be used.
  9. Financial Events Step Size: Select the time window size for fetching financial events data for the ListFinancialEvents and ListFinancialEventGroups streams. Options include:
    • Hourly: 1H, 2H, 4H, 6H, 8H, 12H (recommended for high-volume sellers experiencing pagination token expiration)
    • Daily: 1D, 7D, 14D, 30D, 60D, 90D, 180D (default)
  10. Financial Events Max Results Per Page: Set the maximum number of results per page for the ListFinancialEvents stream (1-100, default: 100). Lower this value if you encounter InvalidInput errors during sync, which occur when the response exceeds 10 MB.
  11. You can specify report options for each stream using Report Options section. Available options can be found in corresponding category here.
  12. For Include PII (Personally Identifiable Information), enable this option to access PII fields such as BuyerInfo and ShippingAddress in the Orders and OrderItems streams. This requires an approved Restricted Role from Amazon. If your account lacks the required role, the connector falls back to standard access automatically and PII fields remain empty.
  13. For Wait between requests to avoid fatal statuses in reports, enable if you want to use waiting time between requests to avoid fatal statuses in report based streams.
  14. Click Set up source.
<!-- /env:cloud --> <!-- env:oss -->

For Airbyte Open Source:

  1. Navigate to the Airbyte Open Source dashboard.
  2. On the Set up the source page, select Amazon Seller Partner from the Source type dropdown.
  3. Enter a name for the Amazon Seller Partner connector.
  4. Using developer application from Step 1, generate refresh token.
  5. For Start Date, enter the date in YYYY-MM-DD format. The data added on and after this date will be replicated. This field is optional - if not provided, the date 2 years ago from today will be used.
  6. For End Date, enter the date in YYYY-MM-DD format. Any data after this date will not be replicated. This field is optional - if not provided, today's date will be used.
  7. Financial Events Step Size: Select the time window size for fetching financial events data for the ListFinancialEvents and ListFinancialEventGroups streams. Options include:
    • Hourly: 1H, 2H, 4H, 6H, 8H, 12H (recommended for high-volume sellers experiencing pagination token expiration)
    • Daily: 1D, 7D, 14D, 30D, 60D, 90D, 180D (default)
  8. Financial Events Max Results Per Page: Set the maximum number of results per page for the ListFinancialEvents stream (1-100, default: 100). Lower this value if you encounter InvalidInput errors during sync, which occur when the response exceeds 10 MB.
  9. You can specify report options for each stream using Report Options section. Available options can be found in corresponding category here.
  10. For Include PII (Personally Identifiable Information), enable this option to access PII fields such as BuyerInfo and ShippingAddress in the Orders and OrderItems streams. This requires an approved Restricted Role from Amazon. If your account lacks the required role, the connector falls back to standard access automatically and PII fields remain empty.
  11. For Wait between requests to avoid fatal statuses in reports, enable if you want to use waiting time between requests to avoid fatal statuses in report based streams.
  12. Click Set up source.
<!-- /env:oss -->

Supported sync modes

The Amazon Seller Partner source connector supports the following sync modes:

  • Full Refresh
  • Incremental

Supported Streams

<!-- env:oss --> <!-- /env:oss --> <HideInUI>

Entity-Relationship Diagram (ERD)

<EntityRelationshipDiagram></EntityRelationshipDiagram> </HideInUI>

Report options

Report options can be assigned on a per-stream basis that alter the behavior when generating a report. For the full list, refer to Amazon’s report type values documentation.

Certain report types have required parameters that must be defined. For the GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL, GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL, and GET_FLAT_FILE_RETURNS_DATA_BY_RETURN_DATE streams, the maximum allowable value for period_in_days is 30 days, 30 days, and 60 days, respectively. If the specified period_in_days exceeds these limits, it will be automatically adjusted to the maximum value for the respective stream, or set to 365 days if not provided.

For the Vendor Forecasting Report, we have two streams - GET_VENDOR_FORECASTING_FRESH_REPORT and GET_VENDOR_FORECASTING_RETAIL_REPORT which use the same GET_VENDOR_FORECASTING_REPORT Amazon's report, but with different options for the sellingProgram parameter - FRESH and RETAIL respectively.

Performance considerations

Information about rate limits you may find here.

  • Use the Financial Events Step Size configuration for the ListFinancialEvents and ListFinancialEventGroups streams:
    • Hourly step sizes (e.g., 1H, 6H) are recommended for high-volume sellers experiencing pagination token expiration (TTL errors). They fetch smaller chunks per request, reducing the risk of timeouts.
    • Daily step sizes (e.g., 1D, 7D) are better for moderate data volumes, balancing sync speed with API efficiency.
    • Larger step sizes (e.g., 30D, 180D) are more efficient for smaller data volumes, reducing the number of API calls.

Data type map

Integration TypeAirbyte Type
stringstring
int, float, numbernumber
datedate
datetimedatetime
arrayarray
objectobject

PII access for Orders and OrderItems

The Orders and OrderItems streams can return personally identifiable information (PII) such as buyer names, shipping addresses, and phone numbers. Amazon gates these fields behind Restricted Data Tokens (RDTs).

To access PII fields, enable Include PII in the connector configuration. The connector then requests an RDT scoped to the Orders and OrderItems endpoints. The following prerequisites apply:

  • Your Amazon SP-API developer profile must have an approved Restricted Role: Direct-to-Consumer Shipping or Tax Invoicing. To request access, update your developer profile and submit for Amazon's review.
  • The selling partner must have authorized your application.

When Include PII is enabled:

  • The ShippingAddress object in Orders includes Name, AddressLine1, AddressLine2, AddressLine3, and Phone in addition to the standard address fields.
  • The BuyerInfo object includes buyer email and name information.

If your application lacks the required Restricted Role, the connector logs a warning and falls back to standard authentication. PII fields remain empty, and non-PII data syncs normally. No manual intervention is required.

Limitations & Troubleshooting

Failed to retrieve the report

Failed to retrieve the report 'YOUR_REPORT_NAME' for period 2024-01-01T12:01:15Z-2024-01-15T12:01:14Z.
This will be read during the next sync. Report ID: YOUR_REPORT_ID. Error: Failed to retrieve the report result document.

Requesting reports via Amazon Seller Partner API can lead to failed syncs with error above "Failed to retrieve the report...".

One of the reasons why users face this issue is that report requests were made too often.

Solution 1:

To overcome it you can force use sleeping between requests to avoid fatal statuses while requesting reports.

Steps:

  1. Go to the Set Up page of the connector.
  2. Open optional section.
  3. Enable Wait between requests to avoid fatal statuses in reports toggle.

Disadvantages of this approach is that syncs with waiting between requests are much slower than without it. So it is better to create a separate connection only for stream that usually fails with "Failed to retrieve the report..." error. This will help you to avoid affecting streams that worked as expected.

:::note

For now the waiting logic only work for the following streams:

  • GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL
  • GET_AFN_INVENTORY_DATA
  • GET_FBA_ESTIMATED_FBA_FEES_TXT_DATA

:::

Solution 2:

Create a separate connection for streams which usually fail with error above "Failed to retrieve the report..." and disable sync of these streams in the first connection with streams which don't fail because of the error. Adjust the sync time of these two connection to do not overlap. It's recommended to have a time break between syncs in the connections.

Rate Limit issue for Report Streams

Syncing Report Streams sometimes may fail due to rate limits.

The Amazon Seller Partner source connector makes requests according to the limits mentioned in the SP API docs. But actual Rate Limits could be differ from ones mentioned in the docs. See Usage Plans and Rate Limits for more information. Depending on actual rate limits the Amazon Seller Partner source connector can receive "rate limited" responses, unfortunately there is no way to find actual rate limits values for account.

We recommend next steps to overcome the rate limits issue:

  1. Depending on your amount of data per Period In Days adjust this value to reduce time of processing the report on API Side. If creation of the report takes more than 1 hour it's recommended to set lower value for Period In Days setting.
  2. Configure affected Report Stream to read data incrementally, use Incremental Sync mode (Append). This will prevent the source of rereading already fetched data and make the source to read new data starting from state cursor value. See Incremental Sync Mode - Append for more information.
  3. Set syncs to run every 24 hours.

This configuration will sync partial data, until the source gets rate limited. Once state value reaches date that equal the date of sync, next sync will have only one partition(date period for report). The source will make only one request for affected report which should be enough to avoid rate limits issue.

ListFinancialEvents stream incompatible with deduplication on BigQuery

The ListFinancialEvents stream does not define a primary key because the Amazon SP-API returns aggregated event lists per time range rather than individual events with unique identifiers. All top-level fields in this stream are arrays, such as ShipmentEventList and RefundEventList.

BigQuery requires non-JSON, non-array types for its CLUSTER BY clause, which Airbyte uses during deduplication. Syncing ListFinancialEvents to BigQuery in deduplication mode fails with:

text
CLUSTER BY expression must be groupable, but type is JSON.

Solution:

Use Append sync mode instead of Dedup for the ListFinancialEvents stream when syncing to BigQuery. If you need deduplicated data, perform deduplication in BigQuery using SQL after the data lands in append mode.

InvalidInput error for ListFinancialEvents stream

text
The API returned an InvalidInput error. This typically occurs when the response exceeds the maximum number of transactions or 10 MB per page.

This error occurs when the ListFinancialEvents stream returns more data than the API can handle in a single page response. According to the Amazon SP-API documentation, if the response exceeds the maximum number of transactions or 10 MB, the API returns an InvalidInput error.

Solution:

Lower the Financial Events Max Results Per Page setting in your connector configuration:

  1. Go to the connector settings page.
  2. Find the Financial Events Max Results Per Page option.
  3. Reduce the value from the default of 100 to a smaller number (e.g., 50, 25, 10, or even 1 for very high-volume accounts).
  4. Save and retry the sync.

You may also combine this with a smaller Financial Events Step Size (e.g., 1H or 6H) to further reduce the amount of data fetched per request.

Changelog

<details> <summary>Expand to review</summary>
VersionDatePull RequestSubject
5.6.12026-03-1774538Update dependencies
5.6.02026-03-1074296Add Restricted Data Token (RDT) support for Orders and OrderItems streams to access PII fields (BuyerInfo, ShippingAddress) via opt-in include_pii config option
5.5.12026-03-0372961Add time-windowed partitioning to Orders stream for proper state checkpointing of OrderItems substream
5.5.02026-02-2672258Add GET_SALES_AND_TRAFFIC_REPORT_BY_DATE stream
5.4.12026-02-2473757Update dependencies
5.4.02026-02-2072837Add marketplaceId to GET_SALES_AND_TRAFFIC_REPORT stream and add new GET_SALES_AND_TRAFFIC_REPORT_BY_MONTH stream for monthly granularity
5.3.12026-02-1073006Update dependencies
5.3.02026-02-0272259Add configurable MaxResultsPerPage for ListFinancialEvents stream with InvalidInput error handling
5.2.02026-01-2171055Re-add 8 brand analytics and vendor analytics streams to Cloud. Fix token expiration handling for long-running syncs.
5.1.22026-01-2071037Fix GB marketplace_id config transformation
5.1.12026-01-2071991Update dependencies
5.1.02026-01-1571327Add rate limiting and hourly granularity options for ListFinancialEvents and ListFinancialEventGroups streams
5.0.22026-01-1471526Update dependencies
5.0.12025-12-1170200Fix financial events pagination causing 400 InvalidInput errors under rate limiting when syncing ListFinancialEvents, and align ListFinancialEventGroups pagination behavior
5.0.02025-12-0869805Remove deprecated FBA Subscribe and Save report types (GET_FBA_SNS_FORECAST_DATA and GET_FBA_SNS_PERFORMANCE_DATA)
4.9.12025-11-2569935Update dependencies
4.9.02025-11-1066995Add APIBudget for reports streams
4.8.42025-10-2968678Increase maxSecondsBetweenMessages to 14400
4.8.32025-10-2966030Update dependencies
4.8.22025-09-2466485Upgrade to CDK v7
4.8.12025-08-1665047Update dependencies
4.8.02025-07-2955195Add VendorOrdersStatus stream
4.7.22025-08-0263032Update dependencies
4.7.12025-07-1563309Adds type property to config_normalization_rules in manifest
4.7.02025-07-0862850Promoting release candidate 4.7.0-rc.1 to a main version.
4.7.0-rc.12025-06-3062119Migrate to manifest-only
4.6.42025-06-1554870Update dependencies
4.6.32025-06-0361351Update dependencies
4.6.22025-04-0957537Fix Extend Minimum Date Range
4.6.12025-04-0855238Fix daterange in DatetimeBasedCursor and Added configurable step size for financial events streams (list_financial_event_groups, list_financial_events)
4.6.02025-02-2453225Add API Budget
4.5.32025-02-2253928Update dependencies
4.5.22025-02-1753693Add app_id to server configuration (OAuth)
4.5.12025-02-0849297Update dependencies
4.5.02025-02-0453155Promoting release candidate 4.5.0-rc.5 to a main version.
4.5.0-rc.52025-01-3152700Use incremental_dependency for the OrderItems substream
4.5.0-rc.42025-01-3152683Fix Rate Limiting issue; disable concurrency
4.5.0-rc.32025-01-2852619Fix Orders pagination
4.5.0-rc.22025-01-2852592Only request data for the Orders stream for up to 2 minutes before present if replication_start_date is not specified
4.5.0-rc.12025-01-2749293Convert to REST and reports streams to concurrent low-code CDK in v6. Remove buggy analytics streams
4.4.72024-11-1447691Fix period_in_days definition
4.4.62024-11-2548644Starting with this version, the Docker image is now rootless. Please note that this and future versions will not be compatible with Airbyte versions earlier than 0.64
4.4.52024-11-0447049Update dependencies
4.4.42024-10-1246817Update dependencies
4.4.32024-10-0546473Update dependencies
4.4.22024-09-2844748Update dependencies
4.4.12024-08-1743739Update dependencies
4.4.02024-07-1742052Add waiting between requests logic to avoid failed report requests
4.3.112024-07-1341873Update dependencies
4.3.102024-07-1041345Update dependencies
4.3.92024-07-0941158Update dependencies
4.3.82024-07-0840751Improve error messaging and turning on alerting
4.3.72024-07-0640990Update dependencies
4.3.62024-07-0140590Add log message when data only accessible to seller accounts, add report id in log message for fatal report status, add check for start date.
4.3.52024-06-2740215Replaced deprecated AirbyteLogger with logging.Logger
4.3.42024-06-2540384Update dependencies
4.3.32024-06-2240008Update dependencies
4.3.22024-06-1339441Update state handling for incremental streams
4.3.12024-06-0438969[autopull] Upgrade base image to v1.2.1
4.3.02024-05-24#38657Extend the report_options spec config with a stream_name attribute
4.2.42024-05-15#38210Fix GET_VENDOR_TRAFFIC_REPORT stream with report option reportPeriod=DAY
4.2.32024-05-09#38078Hide OSS-only streams in report options config for cloud users
4.2.22024-04-24#36630Schema descriptions and CDK 0.80.0
4.2.12024-04-08#36895Fix reportPeriod day query params
4.2.02024-03-19#36267Pin airbyte-cdk version to ^0
4.1.02024-03-12#35954Add GET_VENDOR_FORECASTING_FRESH_REPORT and GET_VENDOR_FORECASTING_RETAIL_REPORT streams
4.0.02024-02-23#35439Update schema for the GET_FBA_STORAGE_FEE_CHARGES_DATA stream
3.5.02024-02-09#35331Fix check for Vendor accounts. Add failed report result message
3.4.02024-02-15#35273Add VendorOrders stream
3.3.22024-02-13#33996Add integration tests
3.3.12024-02-09#35106Add logs for the failed check command
3.3.02024-02-09#35062Fix the check command for the Vendor account type
3.2.22024-02-07#34914Fix date formatting for ledger reports with aggregation by month
3.2.12024-01-30#34654Fix date format in state message for streams with custom dates formatting
3.2.02024-01-26#34549Update schemas for vendor analytics streams
3.1.02024-01-17#34283Delete deprecated streams
3.0.12023-12-22#33741Improve report streams performance
3.0.02023-12-12#32977Make all streams incremental
2.5.02023-11-27#32505Make report options configurable via UI
2.4.02023-11-23#32738Add GET_VENDOR_NET_PURE_PRODUCT_MARGIN_REPORT, GET_VENDOR_REAL_TIME_INVENTORY_REPORT, and GET_VENDOR_TRAFFIC_REPORT streams
2.3.02023-11-22#32541Make GET_AFN_INVENTORY_DATA, GET_AFN_INVENTORY_DATA_BY_COUNTRY, and GET_V2_SETTLEMENT_REPORT_DATA_FLAT_FILE streams incremental
2.2.02023-11-21#32639Make start date optional, if start date is not provided, date 2 years ago from today will be used
2.1.12023-11-21#32560Silently exit sync if the retry attempts were unsuccessful
2.1.02023-11-21#32591Add new fields to GET_LEDGER_DETAIL_VIEW_DATA, GET_FBA_INVENTORY_PLANNING_DATA and Orders schemas
2.0.22023-11-17#32462Remove Max time option from specification; set default waiting time for reports to 1 hour
2.0.12023-11-16#32550Fix the OAuth flow
2.0.02023-11-23#32355Remove Brand Analytics from Airbyte Cloud, permanently remove deprecated FBA reports
1.6.22023-11-14#32508Do not use AWS signature as it is no longer required by the Amazon API
1.6.12023-11-13#32457Fix report decompression
1.6.02023-11-09#32259Mark "aws_secret_key" and "aws_access_key" as required in specification; update schema for stream Orders
1.5.12023-08-18#29255Field role_arn is optional on UI but not really on the backend blocking connector set up using oauth
1.5.02023-08-08#29054Add new stream OrderItems
1.4.12023-07-25#27050Fix - non vendor accounts connector create/check issue
1.4.02023-07-21#27110Add GET_FLAT_FILE_ACTIONABLE_ORDER_DATA_SHIPPING and GET_ORDER_REPORT_DATA_SHIPPING streams
1.3.02023-06-09#27110Removed app_id from InputConfiguration, refactored spec
1.2.02023-05-23#22503Enabled stream attribute customization from Source configuration
1.1.02023-04-21#23605Add FBA Reimbursement Report stream
1.0.12023-03-15#24098Add Belgium Marketplace
1.0.02023-03-13#23980Make app_id required. Increase end_date gap up to 5 minutes from now for Finance streams. Fix connection check failure when trying to connect to Amazon Vendor Central accounts
0.2.332023-03-01#23606Implement reportOptions for all missing reports and refactor
0.2.322022-02-21#23300Make AWS Access Key, AWS Secret Access and Role ARN optional
0.2.312022-01-10#16430Implement slicing for report streams
0.2.302022-12-28#20896Validate connections without orders data
0.2.292022-11-18#19581Use user provided end date for GET_SALES_AND_TRAFFIC_REPORT
0.2.282022-10-20#18283Added multiple (22) report types
0.2.262022-09-24#16629Report API version to 2021-06-30, added multiple (5) report types
0.2.252022-07-27#15063Add Restock Inventory Report
0.2.242022-07-12#14625Add FBA Storage Fees Report
0.2.232022-06-08#13604Add new streams: Fullfiments returns and Settlement reports
0.2.222022-06-15#13633Fix - handle start date for financial stream
0.2.212022-06-01#13364Add financial streams
0.2.202022-05-30#13059Add replication end date to config
0.2.192022-05-24#13119Add OAuth2.0 support
0.2.182022-05-06#12663Add GET_XML_BROWSE_TREE_DATA report
0.2.172022-05-19#12946Add throttling exception managing in Orders streams
0.2.162022-05-04#12523Allow to use IAM user arn or IAM role
0.2.152022-01-25#9789Add stream FbaReplacementsReports
0.2.142022-01-19#9621Add GET_FLAT_FILE_ALL_ORDERS_DATA_BY_LAST_UPDATE_GENERAL report
0.2.132022-01-18#9581Change createdSince parameter to dataStartTime
0.2.122022-01-05#9312Add all remaining brand analytics report streams
0.2.112022-01-05#9115Fix reading only 100 orders
0.2.102021-12-31#9236Fix NoAuth deprecation warning
0.2.92021-12-30#9212Normalize GET_SELLER_FEEDBACK_DATA header field names
0.2.82021-12-22#8810Fix GET_SELLER_FEEDBACK_DATA Date cursor field format
0.2.72021-12-21#9002Extract REPORTS_MAX_WAIT_SECONDS to configurable parameter
0.2.62021-12-10#8179Add GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT report
0.2.52021-12-06#8425Update title, description fields in spec
0.2.42021-11-08#8021Added GET_SELLER_FEEDBACK_DATA report with incremental sync capability
0.2.32021-11-08#7828Remove datetime format from all streams
0.2.22021-11-08#7752Change check_connection function to use stream Orders
0.2.12021-09-17#5248Added extra stream support. Updated reports streams logics
0.2.02021-08-06#4863Rebuild source with airbyte-cdk
0.1.32021-06-23#4288Bugfix failing connection check
0.1.22021-06-15#4108Fixed: Sync fails with timeout when create report is CANCELLED`
</details>