Amazon Product Advertising API 5.0 TypeScript SDK

Common errors

• SignatureDoesNotMatch

  cause Invalid AWS Access Key, Secret Key, Partner Tag, or mismatch between the specified Host/Region and your credentials. The custom signing process requires exact matches.
  fix Double-check your `accessKey`, `secretKey`, `partnerTag`, `Host`, and `Region` values. Ensure they are correct for the Amazon marketplace you are targeting and that your keys are active and valid for PAAPI 5.0. Use the official PAAPI 5.0 Scratchpad to validate your credentials and parameters outside of the SDK.

• MissingAuthenticationToken

  cause The authentication headers required for AWS V4 signing were not correctly generated or included in the HTTP request. This often indicates an issue with `SignHelper` initialization or its integration.
  fix Verify that `SignHelper` is instantiated with the correct credentials and that its output, specifically the `Authorization` header, is properly incorporated into the outgoing request. Ensure all required headers like `x-amz-date`, `host`, `x-amz-target`, and `content-type` are present and correctly formatted.

• Bad Request (or similar with specific 'InvalidParameterValue' details in response payload)

  cause One or more request parameters (e.g., ItemIds, Resources, keywords for SearchItems) do not conform to the Amazon Product Advertising API 5.0 specification for the specific operation.
  fix Consult the official Amazon Product Advertising API 5.0 documentation for the exact request type (e.g., `GetItems`, `SearchItems`) and its required parameters. Ensure all fields are correctly named, have valid values, and that required fields are not missing. Pay attention to case sensitivity and expected data types.

Warnings

• gotcha This is an *unofficial* SDK. It is not directly maintained or supported by Amazon. While functional, it may not receive updates synchronously with Amazon's official API changes or provide the same level of support as official SDKs.
  Fix: Be prepared to manually update the SDK or fork it if Amazon introduces breaking changes to PAAPI 5.0 that are not promptly addressed by this library's maintainer.
• breaking The SDK is in early development (v0.2.0). Breaking changes to its API surface, class structures, or method signatures are possible even between minor or patch versions, without adhering to strict semver for stability.
  Fix: Always review the release notes or GitHub commit history when upgrading to new versions, even minor ones. Thorough testing after upgrades is recommended.
• gotcha The library implements the AWS V4 signing process from scratch using the `SignHelper` class. While this offers self-containment, it might subtly differ from official AWS SDK implementations or become outdated if AWS updates its signing algorithm, potentially leading to authentication failures.
  Fix: If authentication errors persist, verify the custom `SignHelper` implementation against the official AWS V4 signing documentation. Consider using AWS's own signing libraries if you encounter persistent issues.
• gotcha Incorrect configuration of `Host` and `Region` parameters can lead to 'SignatureDoesNotMatch' or 'InvalidParameterValue' errors. These must precisely match the Amazon marketplace you are targeting and the region associated with your AWS credentials.
  Fix: Always ensure the `Host` and `Region` enums passed to request constructors (or `CommonRequest`) accurately reflect the Amazon locale (e.g., `Host.UnitedStates` for `amazon.com`) and your AWS credentials' region.
• gotcha The Amazon Product Advertising API 5.0 has strict request throttling and resource limits. Exceeding these limits will result in API errors (e.g., HTTP 503 Service Unavailable or specific error codes from PAAPI 5.0).
  Fix: Implement proper error handling with exponential backoff and retry mechanisms for API requests. Review Amazon's PAAPI 5.0 documentation on request limits and best practices for making API calls.

Install

• npm install paapi5-typescript-sdk npm
• yarn add paapi5-typescript-sdk yarn
• pnpm add paapi5-typescript-sdk pnpm

Imports

• SDK
  wrong:

  const SDK = require('paapi5-typescript-sdk');

  correct:

  import * as SDK from 'paapi5-typescript-sdk';

  The library is TypeScript-first and designed for ESM. While CommonJS might technically work with transpilation, direct `import` is the idiomatic and intended usage.
• SignHelper, Region, HttpMethod
  wrong:

  import SignHelper from 'paapi5-typescript-sdk/auth/signHelper';

  correct:

  import { SignHelper, Region, HttpMethod } from 'paapi5-typescript-sdk';

  All major components, including utility classes and enums, are exported directly from the root package. Avoid deep imports as internal paths are not guaranteed stable.
• GetItemsRequest, PartnerType, Host
  wrong:

  import { GetItemsRequest } from 'paapi5-typescript-sdk/requests';

  correct:

  import { GetItemsRequest, PartnerType, Host } from 'paapi5-typescript-sdk';

  Request classes and related enums (PartnerType, Host) are top-level exports, simplifying access without needing to navigate internal directory structures.

Quickstart

This quickstart demonstrates how to instantiate and send a `GetItemsRequest` to Amazon's Product Advertising API 5.0, fetching product details by ASIN.

import { GetItemsRequest, PartnerType, Host, Region } from 'paapi5-typescript-sdk';

async function fetchAmazonProductDetails(asin: string) {
  const partnerTag = process.env.PA_API_PARTNER_TAG ?? 'YOUR_PARTNER_TAG';
  const accessKey = process.env.PA_API_ACCESS_KEY ?? 'YOUR_ACCESS_KEY';
  const secretKey = process.env.PA_API_SECRET_KEY ?? 'YOUR_SECRET_KEY';

  // Ensure you use the correct Host and Region for your desired marketplace
  // e.g., Host.UnitedStates and Region.UNITED_STATES for amazon.com
  const request = new GetItemsRequest(
    {
      ItemIds: [asin],
      Resources: [
        'Images.Primary.Large',
        'ItemInfo.Title',
        'Offers.Listings.Price'
      ],
    },
    partnerTag,
    PartnerType.ASSOCIATES,
    accessKey,
    secretKey,
    Host.Italy, // Example: Using Italy. Change as needed.
    Region.ITALY  // Example: Using Italy. Change as needed.
  );

  try {
    const data = await request.send();
    console.log(`Successfully fetched details for ASIN ${asin}:`);
    console.log(JSON.stringify(data, null, 2));
    return data;
  } catch (error) {
    console.error(`Error fetching details for ASIN ${asin}:`, error);
    throw error;
  }
}

// Example usage (replace with a real ASIN from amazon.it if using Italy locale)
// Make sure to set PA_API_PARTNER_TAG, PA_API_ACCESS_KEY, PA_API_SECRET_KEY
// in your environment variables or replace the placeholders.
fetchAmazonProductDetails('B07WGNF455')
  .then(() => console.log('Product fetch complete.'))
  .catch(() => console.error('Failed to fetch product.'));