Skip to main content

​
Amazon Affiliate Integration Setup

This guide covers setting up Amazon Product Advertising API (PA-API) integration for catalog items.

​
Overview

The catalog system supports Amazon affiliate products through two methods:
  1. Simple Affiliate Links — Direct affiliate URLs (e.g., amzn.to short links)
  2. Product Advertising API — Full product data enrichment via Amazon PA-API 5.0
For basic affiliate link integration (no API required): 
from syntropy_journals.app.models.syntropy.catalog import CatalogItemModel, IntegrationSource

item = CatalogItemModel(
    name="Product Name",
    description="Product description",
    category="wellness",
    source=IntegrationSource.AMAZON.value,
    affiliate_url="https://amzn.to/your-link",
    is_active=True,
)

​
Amazon Product Advertising API Setup

For full product data (prices, images, ratings, availability):

​
1. Prerequisites

  • Amazon Associates account (associates.amazon.com)
  • Product Advertising API access (apply via Associates dashboard)
  • Approved API credentials

​
2. Environment Variables

Add to your .env or environment configuration: 
AMAZON_ACCESS_KEY=your_access_key
AMAZON_SECRET_KEY=your_secret_key
AMAZON_PARTNER_TAG=syntropyhealth-20
AMAZON_REGION=us-east-1
AMAZON_MARKETPLACE=www.amazon.com

​
3. Install Dependencies

uv add paapi5-python-sdk

​
4. API Client

The client lives at syntropy_journals/app/integrations/amazon/client.py and provides:
  • AmazonProductAPI.get_item_by_asin(asin) — Fetch product details by ASIN
  • extract_asin_from_url(url) — Extract ASIN from Amazon URLs
  • resolve_short_link(short_url) — Resolve amzn.to short links

​
5. Enrichment Service

The enrichment service at syntropy_journals/app/integrations/amazon/enrichment.py provides:
  • enrich_amazon_item(session, item) — Enrich a single catalog item with PA-API data
  • enrich_all_pending_items(session) — Batch enrich all items flagged for enrichment
Enrichment updates: name, description, price, currency, image URL, rating, review count, stock status.

​
Rate Limits

Traffic LevelRequests/DayRequests/Second
New Associate8,6400.1
Growing86,4001
Established864,00010

​
Best Practices

  1. Cache responses — Store product data locally, refresh daily
  2. Batch requests — Use GetItems for multiple ASINs (max 10 per request)
  3. Handle errors gracefully — Fall back to cached/manual data
  4. Respect rate limits — Implement exponential backoff
  5. Keep affiliate tags consistent — Use environment variables

​
Troubleshooting

ErrorCauseFix
”Request is throttled”Rate limit exceededImplement caching and backoff
”InvalidParameterValue”Bad ASIN formatCheck ASIN is 10 alphanumeric chars starting with B0
”ItemsNotFound”Product unavailableCheck marketplace availability