Amazon Ads

For platform OAuth setup, use Authenticate. Daspire manages the application credentials and stores the authorization securely; the setup form retains the connector’s current business settings.

This page contains the setup guide and reference information for Amazon Ads.

Prerequisites

• Amazon Ads account login (username and password)
• Region

Setup guide

Step 1: Set up Amazon Ads

Create an Amazon user with access to Amazon Ads account.

Step 2: Set up the Amazon Ads data source in Daspire

1. Select Amazon Ads from the Source list.

2. Enter a Source Name.

3. Authenticate your Amazon Ads account. After the Amazon consent window completes, the form automatically loads available profiles using that authorization. Select the intended profiles, then Save changes to apply the configuration. Profile discovery does not save the source or start a sync.

4. Select Region to pull data from North America (NA), Europe (EU) or Far East (FE). See Amazon docs for more details.

5. Report Wait Timeout is the maximum number of minutes the connector waits for report generation. The default is 60 minutes.

6. Report Generation Maximum Retries is the maximum number of attempts the connector tries to generate a report. The default is 5.

7. Start Date (optional) is the requested report starting date, in YYYY-MM-DD format. Report planning uses each profile's timezone. Available history depends on the actual API version and report type; the legacy v2 limit must not be applied to every v3 report. Keep the configured date when reporting an unavailable historical interval. Without an explicit date, the connector uses the attribution window and applicable compatibility behavior; it does not universally subtract one day from an explicitly configured date.

8. Profile IDs (optional) you want to fetch data for. The list is discovered from the authorized Amazon Ads account and the selected Amazon Ads API endpoint region. Leave it empty only when you intentionally want to fetch all visible profiles in that endpoint region. See Amazon docs for more details.

9. Attribution Window (optional) is the number of days after the click date that the click is considered to be eligible for attribution. The default is 7 days. Attribution is the measurement of conversion events, or customer behaviors that occur following an ad interaction. These behaviors measure the success of an ad campaign based on advertiser goals. Learn more.

10. Click Save & Test.

Supported sync modes

The Amazon Ads data source supports the following sync modes:

• Full Refresh
• Incremental

Supported streams

This source is capable of syncing the following streams:

• Profiles
• Sponsored Brands Campaigns
• Sponsored Brands Ad groups
• Sponsored Brands Keywords
• Sponsored Brands Reports
• Sponsored Display Campaigns
• Sponsored Display Ad groups
• Sponsored Display Product Ads
• Sponsored Display Targetings
• Sponsored Display Reports
• Sponsored Products Campaigns
• Sponsored Products Ad groups
• Sponsored Products Keywords
• Sponsored Products Negative keywords
• Sponsored Products Ads
• Sponsored Products Targetings
• Sponsored Products Reports

Specific features and highlights

All the reports are generated for the day before relatively to the target profile' timezone.

Sponsored Brands campaign reports use Amazon reporting v3 as their authoritative source. Each record includes reportVariant so downstream data can retain API lineage. The legacy v2 campaign report is disabled by default; enable report_options.sponsored_brands_report_stream.include_legacy_v2_campaigns only for an account that has been reviewed and shown to require that fallback.

Long report reads emit bounded state checkpoints throughout the sync instead of retaining the full result in connector memory. The execution worker still decides whether a failed job's last checkpoint can be committed, so a failed sync should be retried through the normal Daspire workflow.

Legacy v2 reporting has a 60-day, profile-local availability window. The Native retention-handling update preserves the configured Start Date but avoids requesting older v2 dates that the provider cannot serve. It records the unavailable interval in the affected profile's connector state as unavailableLegacyV2History, with historicalCoverageAccepted: false. This is not a claim that the older history was restored. V3 variants within the same stream retain their own request dates; this change does not select or enable Unified Reporting. Operators must verify the deployed image supports this handling before relying on it.

If a requested period predates the provider's available history, acceptance must separately identify that missing interval. Amazon's v2 reporting FAQ describes the limit and possible console/v3 alternatives; do not switch reporting APIs or import replacement history without reviewing the affected data contract.

The v3 profile-day boundary correction prevents a Sponsored Products request from extending its final day into the profile's tomorrow. It retains the requested current day, historical start, attribution window and connector progress; it is not a historical-retention adjustment. Current-day metrics may still change on later reads. Verify the actual deployed image supports the correction before treating a date-related failure as resolved.

The separate Reporting v3 retention correction uses the specific reportTypeId, not a single limit for all v3 reports. For the report types implemented here, Brands campaigns retain 60 days; Display reports and Products search-term reports retain 65 days; Products campaign, targeting and advertised-product reports retain 95 days. These limits follow Amazon's campaign, targeting, advertised-product, purchased-product, and search-term documentation, verified September 11, 2026. Other report types can have different limits.

When this correction is deployed, the connector keeps the configured Start Date and records unavailable history per profile and report type in unavailableReportingV3History, with historicalCoverageAccepted: false. Display's additional request lookback is included in that evidence when it exceeds the provider's boundary. Only available requests are marked completed; missing history is not treated as restored. The correction does not enable or change Unified Reporting. Operators must verify the running digest, actual report reads and recorded gaps before accepting recovery.

For report-creation validation failures, a separately deployed diagnostic update distinguishes profile-local and UTC request ages. It can retain an explicitly recognized provider date constraint and its bound relative to the requested start, without exposing absolute dates or response text in execution logs. Unknown or ambiguous responses remain unclassified. These hints do not change request dates, retry behavior, progress, or available history; they are not proof of restored access or data coverage. The connector producer and execution diagnostic consumer must both support these fields before operators rely on them.

Performance considerations

Information about expected report generation waiting time you may find here.

Troubleshooting

Max number of tables that can be synced at a time is 6,000. We advise you to adjust your settings if it fails to fetch schema due to max number of tables reached.

If Save & Test fails, verify that the OAuth account can list profiles in the selected Amazon Ads API endpoint region. Token exchange happens before profile discovery. An HTTP 400 alone does not establish that the user's authorization expired.

Token exchange diagnostics retain the HTTP status and a recognized OAuth error code, without the provider response body or error_description:

OAuth error	What to investigate
invalid_client	The effective application client ID and client secret, including secret rotation.
invalid_grant	An invalid or revoked grant, or a refresh token issued to a different client. This code alone cannot distinguish those causes.
unauthorized_client	Whether the effective client is authorized to use the grant, including the client/refresh-token pairing.
invalid_request, unsupported_grant_type	Required parameters, form encoding, and grant_type=refresh_token.
invalid_scope, access_denied	Requested scope and authorization permissions.

Unknown or malformed provider errors retain only the HTTP status. Compare the client configuration actually injected at runtime with the configuration used when the refresh token was issued. A stored source client can differ from the runtime client. Amazon documents that refresh tokens are assigned to one client; do not treat them as interchangeable across applications.

When reauthorization is required, sign in to Daspire, select the correct workspace, then open Sources → the existing Amazon Ads source → Settings → Reauthenticate (or Authenticate). Complete the Amazon-hosted consent flow with an account that can access the intended advertiser, then use Save & Test. Keep the intended region and profile selection. Never send tokens, client secrets, or authorization responses through chat, email, or support logs. Check all connections referencing that source before saving.

A successful authorization check verifies access, but does not establish that a sync wrote the intended data. For a connection paused during recovery, leave its schedule paused until a newly authorized sync has passed the required source, destination, and data checks. Then restore its exact original schedule and read it back; setting the connection status to Active alone does not restore natural scheduling.

Data type mapping

Integration Type	Daspire Type
string	string
int, float, number	number
date	date
datetime	datetime
array	array
object	object