Amazon Integration Guide

Connect Amazon Shops to Dodgeprint — both the Seller (SP-API) and Advertising (Ads API) sides — and access orders, ledger transactions, product deployment, campaigns, and customer review solicitations through a single API surface.

Overview

Amazon integration on Dodgeprint has two independent OAuth tracks under the same platform_id=5, distinguished by whether a site_id is passed when requesting the authorization URL:

Track	Use case	Body to /authenticate-site
Seller (SP-API)	Orders, listings, financial transactions, solicitations	{ "platform_id": 5 }
Advertising (Ads API)	Sponsored Products / Brands / Display campaigns	{ "platform_id": 5, "site_id": <seller_site_id> }

Connect order matters

You must connect Seller first (which creates a Site record), then call /authenticate-site again with the returned site_id to attach Ads credentials to the same Site.

Unified redirect behaviour

Both tracks use redirect_url. After consent, Dodgeprint 302-redirects to your URL with a standard query contract — partners dispatch on segment:

Outcome	Callback URL
Seller success	<redirect_url>?platform=amazon&site_id=<new_site_id>
Seller failure	<redirect_url>?platform=amazon&code=<err>&message=<msg>
Ads success	<redirect_url>?platform=amazon&site_id=<site_id>&segment=advertising

---

Prerequisites

1. A Dodgeprint account with a Personal Access Token — see the Authentication Guide.
2. Your workspace_id (from your account settings).
3. Every request must include:
   • Authorization: Bearer <PAT>
   • X-Workspace-Id: <workspace_id>
   • Content-Type: application/json

For OAuth fundamentals and platform comparison, see the OAuth Platform Authentication guide.

---

End-to-end Flow

  Stage 1         Stage 2            Stage 3          Stage 4            Stage 5+
  ───────         ────────           ───────          ────────           ────────
  Partner         Connect            Connect          Select             Sync & read
  setup (PAT)     Seller OAuth       Ads OAuth        marketplace        data
                  (redirect)         (optional)       (REQUIRED)

All responses follow the standard envelope:

{ "success": true, "code": 200, "data": { ... } }

---

Stage 1 — Set up environment

export DODGEPRINT_TOKEN="eyJ0eXAi...YOUR_PAT"
export DODGEPRINT_WORKSPACE_ID="380"
export DODGEPRINT_API="https://api.dodgeprint.com/api/v1"

# Sanity check
curl -s "$DODGEPRINT_API/sites?limit=1" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

---

Stage 2 — Connect Amazon Seller (SP-API)

2a. Request Seller OAuth URL

Do not include site_id — absence tells Dodgeprint this is the Seller track.

curl -X POST "$DODGEPRINT_API/authenticate-site" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_id": 5,
    "redirect_url": "https://myapp.com/amazon/callback"
  }'

Response:

{
  "success": true,
  "code": 200,
  "data": {
    "url": "https://sellercentral.amazon.com/apps/authorize/consent?application_id=...&state=eyJ0eXAi..."
  }
}

The state is a JWT valid for 15 minutes.

2b. Handle the redirect callback

After the user authorizes on Amazon Seller Central, Dodgeprint completes the token exchange and 302-redirects the user's browser to your redirect_url with query parameters appended:

Outcome	Redirect URL
Success	https://myapp.com/amazon/callback?platform=amazon&site_id=<new_site_id>
Failure	https://myapp.com/amazon/callback?platform=amazon&code=<err_code>&message=<url_encoded_msg>

Example (Node/Express):

app.get('/amazon/callback', (req, res) => {
  const { site_id, code, message } = req.query;
  if (code) {
    return res.status(400).send(`Amazon OAuth failed: ${decodeURIComponent(message)}`);
  }
  // site_id is the newly connected Amazon Seller site
  return res.redirect(`/dashboard/sites/${site_id}`);
});

API reference: POST /authenticate-site, GET /sites

---

Stage 3 — Connect Amazon Ads (optional)

Only needed if your integration reads or manages Sponsored Products / Brands / Display campaigns. Pass the site_id from Stage 2 — its presence tells Dodgeprint this is the Ads track.

3a. Request Ads OAuth URL

curl -X POST "$DODGEPRINT_API/authenticate-site" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"platform_id\": 5,
    \"site_id\": $SITE_ID,
    \"redirect_url\": \"https://myapp.com/amazon/callback\"
  }"

Response shape is identical to Stage 2a (returns data.url for the Amazon Ads consent page).

3b. Handle the redirect callback

On success, Dodgeprint 302-redirects with segment=advertising appended so your handler can distinguish Ads from Seller:

https://myapp.com/amazon/callback?platform=amazon&site_id=<site_id>&segment=advertising

You can reuse the same callback route as Stage 2b — switch on segment:

app.get('/amazon/callback', (req, res) => {
  const { site_id, code, message, segment } = req.query;
  if (code) return res.status(400).send(`Amazon OAuth failed: ${decodeURIComponent(message)}`);
  if (segment === 'advertising') {
    // Ads credentials attached to site_id
    return res.redirect(`/dashboard/sites/${site_id}?view=ads`);
  }
  // Seller connected
  return res.redirect(`/dashboard/sites/${site_id}`);
});

No need to parse the state parameter

Both Seller and Ads tracks sign the OAuth state with JWT (a legacy pipe-delimited format is still accepted on inbound callbacks for backward compatibility). Trust the data.url returned — do not attempt to parse or regenerate the state client-side.

Detecting Ads connection without a callback

Partners that cannot host a redirect callback can poll GET /sites/:id — the returned data.is_authorized_ads flag flips to true once Ads credentials are attached.

API reference: POST /authenticate-site, GET /sites/:id

---

Stage 4 — Select Amazon marketplace (REQUIRED)

Amazon sellers often participate in multiple marketplaces (US, UK, DE, …). Dodgeprint requires one active marketplace per site before any sync runs.

4a. List available marketplaces

curl "$DODGEPRINT_API/sites/$SITE_ID/amazon/marketplace" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

Response:

{
  "success": true,
  "code": 200,
  "data": {
    "current": null,
    "options": [
      {
        "id": "ATVPDKIKX0DER",
        "name": "Amazon.com",
        "country_code": "US",
        "domain_name": "www.amazon.com",
        "is_participating": true,
        "has_suspended_listings": false,
        "is_current": false
      }
    ]
  }
}

Only marketplaces where is_participating=true and the domain matches www.amazon.* (real commerce) appear in options.

4b. Select one

curl -X PUT "$DODGEPRINT_API/sites/$SITE_ID/amazon/marketplace" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"marketplace_id": "ATVPDKIKX0DER"}'

Response: { "success": true, "code": 200, "data": { "current": "ATVPDKIKX0DER" } }

Skipping this stage breaks sync

If you don't select a marketplace, sync jobs fail with a marketplace_selection_required alert. Always run Stage 4 before Stage 5.

API reference: Amazon Marketplace — GET, PUT

---

Stage 5 — Trigger sync

Dodgeprint pulls Amazon data on a scheduled job. To trigger an on-demand sync:

curl -X POST "$DODGEPRINT_API/manual-sync" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"type\": \"sync_orders\", \"site_id\": $SITE_ID}"

Response:

{
  "success": true,
  "message": "Orders sync has started and is running in the background.",
  "data": {
    "sites_syncing": [{"site_id": 9185, "platform_id": 5}],
    "progress_tracking": true,
    "sync_started_at": "2026-04-21T04:55:22.168913Z"
  }
}

Supported type values: sync_orders, sync_products, sync_transactions.

Rate limit

5 syncs per hour per (site_id, type) pair. Exceeding returns HTTP 429.

API reference: POST /manual-sync

---

Stage 6 — Orders

Once sync_orders completes (typically 30–60s depending on order volume):

curl "$DODGEPRINT_API/orders?site_id=$SITE_ID&limit=20" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

API reference: GET /orders, GET /orders/:id

---

Stage 7 — Financial transactions (ledger)

The ledger endpoint is platform-aware: pass an Amazon site_id (platform_id=5) and you receive rows from Amazon's financial transactions; pass an Etsy or Shopify site and you receive that platform's ledger. The response shape is identical.

# List transactions — sort by posted date, newest first
curl "$DODGEPRINT_API/ledgers/$SITE_ID/transactions?limit=50&sort=posted_date&sort_type=desc" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

# Filter by date range + ledger type + free-text search
curl "$DODGEPRINT_API/ledgers/$SITE_ID/transactions?date=01/04/2026,30/04/2026&ledger_type=SHIPMENT&q=order" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

Supported query params (per API Reference): limit, page, q, ledger_type, date (comma-separated DD/MM/YYYY,DD/MM/YYYY), sort, sort_type.

Rows include amount, currency, posted_date, transaction_status, merchant_order_id, shipment_id, and (for Amazon sites) a nested amazon_transaction_type.

Data freshness

Amazon transactions populate from the amazon:get-transactions scheduled job — ensure it has run (or trigger sync_transactions via Stage 5).

---

Stage 8 — Deploy products to Amazon

Amazon has a dedicated deployment endpoint (POST /v2/amazon/deploy-products) separate from Etsy's (/v2/deploy-products). Deployment is an RFC 7231 Long-Running Operation (LRO): the endpoint returns 202 Accepted with a Location header pointing at the deploy report, and a Retry-After header hinting at the polling interval.

v2 vs v1 base path

$DODGEPRINT_API in this guide is https://api.dodgeprint.com/api/v1. The Amazon deploy endpoint lives under v2, so add a separate base for it:

export DODGEPRINT_API_V2="https://api.dodgeprint.com/api/v2"

8a. Discover valid product types and content

Amazon deployment requires a whitelisted product_type (DB-driven — currently SHIRT and COAT; other values like HOODIE / SHOES return 422 without further hint), plus a content_id pointing to a content record created via /v1/contents.

# List Amazon product types allowed for this workspace
curl "$DODGEPRINT_API/product-type?platform_id=5" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

# List content records you can attach
curl "$DODGEPRINT_API/contents?limit=20" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

API reference: GET /product-type, GET /contents

8b. Submit the deploy job

curl -i -X POST "$DODGEPRINT_API_V2/amazon/deploy-products" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"site_id\": $SITE_ID,
    \"product_id\": 12345,
    \"content_id\": 678,
    \"product_type\": \"SHIRT\",
    \"amazon_attributes\": {
      \"fulfillment_availability\": {
        \"lead_time_to_ship_max_days\": 5,
        \"fulfillment_channel_code\": \"DEFAULT\"
      }
    },
    \"bullet_points\": [
      \"100% combed cotton, pre-shrunk\",
      \"Double-stitched seams for durability\"
    ],
    \"variants\": [
      {
        \"price\": 24.99,
        \"quantity\": 50,
        \"options\": [
          { \"name\": \"Size\", \"value\": \"M\" },
          { \"name\": \"Color\", \"value\": \"Black\" }
        ]
      }
    ]
  }"

Response — 202 Accepted:

HTTP/1.1 202 Accepted
Location: /api/v1/report-product-deploy/789
Retry-After: 5
Content-Type: application/json

{
  "success": true,
  "code": 202,
  "message": "Deploy job queued",
  "data": { "report_id": 789 }
}

Common 422 causes

• Missing content_id, or ID doesn't belong to your workspace
• product_type not in the whitelist — call GET /product-type?platform_id=5 first
• Missing nested amazon_attributes.fulfillment_availability.{lead_time_to_ship_max_days, fulfillment_channel_code} (both enforced)
• Field name drift from V1: use amazon_attributes (not product_definitions), bullet_points (plural, not bullet_point)
• shipping_profile_id / return_policy_id are Etsy-only — Amazon rejects them

8c. Poll the deploy report

Honour Retry-After from the initial 202 response:

# Follow the Location header
curl "$DODGEPRINT_API/report-product-deploy/789" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

# Or list recent reports for this site
curl "$DODGEPRINT_API/report-product-deploy?site_id=$SITE_ID&limit=10" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

For the full payload schema, field-by-field breakdown, and error catalog, see the Product Deployment Guide and the API reference below.

API reference: POST /v2/amazon/deploy-products, GET deploy reports, GET deploy report detail

---

Stage 9 — Amazon Ads campaigns

Prerequisite: Stage 3 (Amazon Ads OAuth) must be completed for the site.

9a. List profiles (one per marketplace/country)

curl "$DODGEPRINT_API/ads/profiles" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

9b. List portfolios with aggregated performance

curl "$DODGEPRINT_API/ads/portfolios?report_date_start=2026-04-14&report_date_end=2026-04-21&limit=20" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

9c. List campaigns

curl "$DODGEPRINT_API/ads/campaigns?limit=20&report_date_start=2026-04-14&report_date_end=2026-04-21" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

Each campaign includes aggregated metrics (ctr, cpc, acos, roas, clicks, impressions, cost, purchases, sales, unit_sold), a type (SP / SB / SD), and nested profile and portfolio objects.

9d. Update a single campaign

curl -X PUT "$DODGEPRINT_API/ads/campaigns/50123" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"state": "PAUSED", "budget": 75.00}'

9e. Bulk update (up to 100 campaigns)

curl -X PUT "$DODGEPRINT_API/ads/campaigns" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": 40,
    "campaigns": [
      {"id": 50123, "state": "PAUSED"},
      {"id": 50124, "budget": 100.00}
    ]
  }'

Field	Constraint
state	ENABLED or PAUSED
budget (bulk)	Min $1.00
budget (single)	Min $0.01

API reference: Amazon Ads Campaigns, Account & Portfolios

---

Stage 10 — Ad groups, product ads, keywords, targeting

10a. Ad groups

# List
curl "$DODGEPRINT_API/ads/ad-groups?campaign_id=50123" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

# Create
curl -X POST "$DODGEPRINT_API/ads/ad-groups" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "Manual - BestSellers", "campaign_id": 50123, "default_bid": 0.85}'

# Bulk update
curl -X PUT "$DODGEPRINT_API/ads/ad-groups" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"ad_groups": [{"id": 6001, "state": "ENABLED", "default_bid": 0.95}]}'

10b. Search terms (for negative-keyword mining)

curl "$DODGEPRINT_API/ads/search-terms?ad_group_id=6001" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

10c. Product ads

curl "$DODGEPRINT_API/ads/product-ads?ad_group_id=6001&limit=20" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

10d. Keywords (manual targeting)

# List
curl "$DODGEPRINT_API/ads/keywords?site_id=$SITE_ID&ad_group_id=6001&type=KEYWORD" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

# Bulk update bid/state (min bid $0.02)
curl -X PUT "$DODGEPRINT_API/ads/keywords" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"keywords": [{"id": 12345, "state": "ENABLED", "bid": 0.95}]}'

10e. Auto-targeting

# List
curl "$DODGEPRINT_API/ads/targeting?site_id=$SITE_ID" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID"

# Bulk update — target IDs are prefixed (e.g. "target_77001", "keyword_12345")
curl -X PUT "$DODGEPRINT_API/ads/targeting" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "profile_id": 40,
    "targets": [{"id": "target_77001", "state": "PAUSED", "bid": 0.55}]
  }'

API reference: Ad Groups & Product Ads, Keywords, Targeting & Search Terms

---

Stage 11 — Request customer reviews (Solicitations)

11a. Check eligibility

Synchronous check — roughly 1 second per order due to Amazon rate limits.

curl -X POST "$DODGEPRINT_API/amazon/solicitations/check-eligibility" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"site_id\": $SITE_ID, \"orders\": [{\"amazon_order_id\": \"123-4567890-1234567\"}]}"

Response:

{
  "success": true,
  "message": "1 out of 1 orders are eligible for review solicitation",
  "data": {
    "summary": {"total": 1, "eligible": 1, "not_eligible": 0},
    "results": [
      {
        "amazon_order_id": "123-4567890-1234567",
        "marketplace_id": "ATVPDKIKX0DER",
        "can_send": true,
        "reason": null,
        "available_actions": ["productReviewAndSellerFeedback"]
      }
    ]
  }
}

11b. Queue requests for eligible orders

curl -X POST "$DODGEPRINT_API/amazon/solicitations/bulk-request-review" \
  -H "Authorization: Bearer $DODGEPRINT_TOKEN" \
  -H "X-Workspace-Id: $DODGEPRINT_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"site_id\": $SITE_ID, \"orders\": [{\"amazon_order_id\": \"123-4567890-1234567\"}]}"

Limit	Value
Max orders per call	100
Amazon rate limit (internal)	1 request / second

Orders must be synced first

Solicitations return status: skipped, reason: "Order not found in system" for orders that haven't been synced via sync_orders yet.

API reference: Amazon Solicitations — Check eligibility, Bulk request review

---

Token refresh

Dodgeprint stores refresh tokens and automatically renews access tokens before expiry. You do not call any endpoint for this. If a refresh fails, sync jobs surface a token_refresh_failed alert — reconnect by repeating Stages 2–4.

---

Stage 12 — Disconnect a site

There is no public API to disconnect an Amazon site. Users who want to revoke the integration must do so from the Dodgeprint dashboard:

1. Go to https://app.dodgeprint.com/site/{site_id}/settings
2. Click Disconnect

Token revocation is not automatic

Dodgeprint stops using the Amazon credentials on disconnect, but does not revoke the token at Amazon. Users who want a full revoke should also remove the app from:

• Amazon Seller Central → Apps & Services → Manage Your Apps (Seller track)
• Amazon Ads Console → Settings → Authorized Applications (Ads track)

---

Rate limits

Scope	Limit
Default (per PAT)	60 req / minute
POST /manual-sync	5 / hour per (site_id, type)
POST /amazon/solicitations/check-eligibility	1 order / second (internal)
POST /amazon/solicitations/bulk-request-review	1 Amazon call / second (queued)

On 429, read the Retry-After header and back off.

---

Error handling

All error responses follow:

{ "success": false, "code": 4xx, "message": "Human-readable reason" }

HTTP	Meaning	Action
401	Missing or invalid Bearer	Refresh or re-issue PAT
403	Wrong X-Workspace-Id	Check header matches the account
404	Site or resource not found	Verify ownership of the ID
409	Sync already running	Wait for completion
422	Validation error	Check body against the API Reference schema
429	Rate limit	Back off per Retry-After
5xx	Dodgeprint error	Exponential backoff; escalate after 3 retries

---

Troubleshooting

Symptom	Likely cause	Fix
Callback never fires (Stage 2b)	User closed Amazon tab or denied consent	Restart Stage 2a
Sync fails with marketplace_selection_required	Stage 4 was skipped	Run PUT /sites/{id}/amazon/marketplace
Ads endpoints return empty	Only Seller OAuth done	Run Stage 3
401 despite valid token	Token has line breaks or trailing whitespace	Re-copy the PAT cleanly
Solicitation check is very slow	1-sec-per-order Amazon pacing	Batch into smaller groups (10–20 orders)

---

Related resources

• Authentication Guide — create and use a Personal Access Token
• OAuth Platform Authentication — general OAuth flow across platforms
• Product Deployment Guide — full deploy payload and error codes
• API Reference: Amazon Listings, Amazon Marketplace, Amazon Solicitations, Amazon Ads Campaigns, Ledger Transactions