Amazon Creators API - Elixir Client

An Elixir client library for the Amazon Creators API with automatic token caching and management.

Features

Installation

Add amazon_creators_api to your list of dependencies in mix.exs:

def deps do
  [
    {:amazon_creators_api, "~> 0.1.0"}
  ]
end

Configuration

Set up your Amazon Creators API credentials as environment variables:

export CREATORS_API_CLIENT_ID="your_client_id"
export CREATORS_API_CLIENT_SECRET="your_client_secret"
export CREATORS_API_PARTNER_TAG="yourpartner-20"

Usage

Simple Usage (Recommended)

The easiest way to use the API is with fetch_items/2, which handles token management automatically:

# Fetch a single item
opts = [
  region: :na,  # or :eu, :fe
  marketplace: "www.amazon.com",
  partner_tag: System.get_env("CREATORS_API_PARTNER_TAG"),
  client_id: System.get_env("CREATORS_API_CLIENT_ID"),
  client_secret: System.get_env("CREATORS_API_CLIENT_SECRET")
]

case AmazonCreatorsAPI.fetch_items("B09B2SBHQK", opts) do
  {:ok, %{"itemsResult" => %{"items" => items}}} ->
    Enum.each(items, fn item ->
      IO.puts(item["itemInfo"]["title"]["displayValue"])
      IO.puts(item["detailPageURL"])
    end)

  {:error, reason} ->
    IO.puts("Error: #{inspect(reason)}")
end

Fetch Multiple Items

asins = ["B09B2SBHQK", "B09B8V1LZ3", "B0BZTW3TCH"]

{:ok, %{"itemsResult" => %{"items" => items}}} =
  AmazonCreatorsAPI.fetch_items(asins, opts)

IO.puts("Fetched #{length(items)} items")

European Marketplaces

opts = [
  region: :eu,
  marketplace: "www.amazon.de",
  partner_tag: "yourpartner-21",
  client_id: System.get_env("CREATORS_API_CLIENT_ID"),
  client_secret: System.get_env("CREATORS_API_CLIENT_SECRET")
]

AmazonCreatorsAPI.fetch_items("B09B2SBHQK", opts)

Custom Resources

By default, the API fetches common product information. You can specify custom resources:

opts = [
  region: :na,
  marketplace: "www.amazon.com",
  partner_tag: "yourpartner-20",
  client_id: System.get_env("CREATORS_API_CLIENT_ID"),
  client_secret: System.get_env("CREATORS_API_CLIENT_SECRET"),
  resources: [
    "itemInfo.title",
    "itemInfo.features",
    "offersV2.listings.price",
    "images.primary.large"
  ]
]

AmazonCreatorsAPI.fetch_items("B09B2SBHQK", opts)

Available Resources

Item Information:

Images:

Offers (Version 2):

Browse Nodes:

Customer Reviews:

Other:

Manual Token Management

For advanced use cases where you want to manage tokens yourself:

# Get a token (cached automatically)
{:ok, token_data} = AmazonCreatorsAPI.get_token(:na, client_id, client_secret)

# Use the token for multiple requests
{:ok, items1} = AmazonCreatorsAPI.get_items(
  "B09B2SBHQK",
  "www.amazon.com",
  "yourpartner-20",
  token_data["access_token"],
  token_data["version"]
)

{:ok, items2} = AmazonCreatorsAPI.get_items(
  "B09B8V1LZ3",
  "www.amazon.com",
  "yourpartner-20",
  token_data["access_token"],
  token_data["version"]
)

Monitoring Token Cache

# Get cache statistics
stats = AmazonCreatorsAPI.token_stats()
# => %{"na:your_client_id" => %{ttl_seconds: 3540, expires_at: 1735123456}}

# Clear cache (useful for testing or forcing refresh)
AmazonCreatorsAPI.clear_token_cache()

Regions and Marketplaces

North America (NA) - Version 2.1

Europe (EU) - Version 2.2

Far East (FE) - Version 2.3

Error Handling

The API returns standard Elixir {:ok, result} or {:error, reason} tuples:

case AmazonCreatorsAPI.fetch_items("INVALID_ASIN", opts) do
  {:ok, items} ->
    IO.inspect(items)

  {:error, :not_found} ->
    IO.puts("Item not found")

  {:error, :unauthorized} ->
    IO.puts("Invalid credentials")

  {:error, {:auth_failed, status, body}} ->
    IO.puts("Authentication failed: #{status}")

  {:error, {:http_error, status, body}} ->
    IO.puts("HTTP error: #{status}")

  {:error, {:request_failed, reason}} ->
    IO.puts("Request failed: #{inspect(reason)}")
end

Token Caching

The library automatically caches authentication tokens using a GenServer. Tokens are:

Testing

Run the test suite:

mix test

Run tests with coverage:

mix coveralls

Run tests with detailed coverage:

mix coveralls.detail

Architecture

The library consists of two main modules:

  1. AmazonCreatorsAPI: Main API module with public functions
  2. AmazonCreatorsAPI.TokenManager: GenServer that manages token caching

The TokenManager is automatically started as part of your application's supervision tree.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues related to the Amazon Creators API itself, please refer to the official Amazon documentation.

For issues with this library, please open an issue on Codeberg.