Frequently Asked Questions
Common questions about using the plugin
What's the short version of the PaapiPlugin FAQ?
PaapiPlugin is a WordPress plugin that embeds live Amazon product search on your site. You need an Amazon Associates account. For product data, use our Managed API (Beta) with no credentials required, or bring your own Creators API or PA-API v5 credentials. Then drop one shortcode on a page. The free version on WordPress.org is fully functional, Premium is $39/year, and three optional addons (Product Boxes, Comparison Tables, Analytics) are $19/year each.
Do I need an Amazon Associates account?
You always need an Amazon Associates account. You do NOT need your own Amazon API credentials yet if you use our Managed API (Beta), which runs real-time Amazon search with no AWS keys. Bring your own Creators API or PA-API v5 credentials when you are ready. Either way, your Amazon Associate tag stays yours.
How do I get Amazon API credentials?
Sign up for Amazon Associates, then choose one of two authentication methods: OAuth 2.0 (Creators API) - apply at the Creators API page to get a Client ID and Client Secret (recommended for new users). AWS Signature V4 (PA-API) - apply for Product Advertising API access to get an Access Key and Secret Key. Both methods require your Associate Tag. Note: Amazon requires at least 10 qualifying referred sales in the last 30 days before approving Creators API access, and only the primary Associates account owner can register the application (delegated-access users will be blocked). See our documentation for detailed setup instructions. If you do not have credentials yet, you can start on the Managed API (Beta) with no Amazon API credentials needed yet, and bring your own when you are ready.
Do I need Amazon API credentials to use PaapiPlugin?
No. Our Managed API (Beta) runs real-time Amazon product search with no Amazon API credentials needed yet and no AWS keys. You still need a free Amazon Associates account so commissions are tagged to you, and your Amazon Associate tag is always yours. If you already hold Creators API or PA-API v5 credentials, you can bring your own instead with one toggle in the plugin admin.
PA-API v5 retired on May 15, 2026. What do I do now?
Amazon retired the Product Advertising API v5 SigV4 endpoint on May 15, 2026. If your site brought its own PA-API v5 (AWS Signature V4) keys, those calls now fail with auth errors and product widgets stop returning data. Here is what to do, in this order. First, switch to our Managed API (Beta), which needs no Amazon API credentials, so you are back online in about 30 seconds. Or, switch to the Creators API (OAuth 2.0), the recommended bring-your-own path now that PA-API is legacy. Either way your Amazon Associate tag stays yours. For the full symptom list and migration steps, see PA-API v5 retired: what changed.
How do I use Test Connection to diagnose a credential error?
If the Creators API returns a token error such as invalid_client or invalid_scope, open the plugin admin and click Test Connection. The diagnostic walks every step of the OAuth handshake and surfaces the resolved credential version, the resolved token endpoint URL, the HTTP status code Amazon returned, the literal error code, the error_description text, and the marketplace targeted. It also shows a human-readable hint and a hint link that point you straight at the fix. Read it top down and the mismatched field is usually obvious in under a minute. The most common cause of invalid_client is a credential version that does not match the prefix on your Client Secret, and invalid_scope or unauthorized_client usually means your credentials have not been granted that scope, so you need to re-issue or re-authorize the credentials. For a walkthrough of each OAuth error code and its fix, see our Creators API troubleshooting guide.
How do I add the search to my page?
Simply add the shortcode [psfa_search] to any page or post. You can also use the visual Shortcode Builder in the plugin settings to customize parameters.
Can I filter products by category?
Yes! Use [psfa_search category="Electronics"] to pre-set a category, or let users pick from the dropdown. Free users have 5 categories, Premium users get all 26.
Does the plugin support infinite scroll?
Yes! Products load automatically as users scroll. With your own Amazon credentials (Creators API or PA-API), results load up to Amazon's 10-page ceiling. On the Managed API (Beta), searches load up to 5 pages, or 3 pages when filters are applied.
Can I customize the appearance?
Yes! Free users get the Neutral base color with orange accent and can override CSS. Premium users get a 6-axis appearance system: 5 base colors, 17 accent colors, 5 card styles (Vega, Nova, Maia, Lyra, Mira), 5 border radius levels, dark mode, and 15 Google Fonts.
Does it work with caching plugins?
Yes, but you may need to exclude pages with the shortcode from full-page caching, as search requires dynamic content.
Does the plugin cache Amazon API responses?
Yes! Search results are cached for 30 minutes and individual product data for 1 hour. This significantly reduces API calls and speeds up repeat searches. You can manage and clear the cache from the dedicated Cache page, which shows all cached items in a sortable, filterable table.
What if my API credentials are invalid?
The plugin displays an error message asking you to check your credentials. Open Settings then Paapi Product Search and click Test Connection to see which step failed. For the Creators API, verify your Client ID, Client Secret, and that the credential version matches your secret. For bring-your-own PA-API v5, verify your Access Key, Secret Key, and Associate Tag. If you would rather skip credentials entirely, switch to our Managed API (Beta), which needs none.
Can I search without a query?
Yes. With no query and no category set, [psfa_search] shows the Top Products Grid: a rotating grid of popular Amazon products across categories instead of an empty search box, turning any page into an instant Amazon storefront. This is the Top Products on Empty State setting, which is on by default. If you specify a category instead, it shows popular products from that category. Either way visitors can search or filter to go deeper, and every product is tagged with your Associate ID.
What is the Top Products Grid?
The Top Products Grid is a free feature that shows a rotating grid of popular Amazon products across categories when [psfa_search] is placed with no query and no category, instead of an empty search box. It is on by default (the Top Products on Empty State setting) and gives any page an instant Amazon storefront. If you have turned that setting off, add [psfa_search mode="top"] to force the grid on. Every product link carries your Amazon Associate tag.
What are the requirements?
WordPress 5.8+, PHP 7.4+, cURL extension, and an Amazon Associates account. For product data you can use our Managed API (Beta, no credentials required) or bring your own PA-API v5 (Access Key, Secret Key, Associate Tag) or Creators API credentials.
Can I hide the search box or filters?
Yes! Use [psfa_search hide_search="true"] to hide the search box, or hide_filters="true" to hide filters. Great for category-specific pages.
Can I control how many products are displayed?
Yes! Use the count attribute with pagination="none" to display a specific number of products (2-20). For example: [psfa_search category="Electronics" pagination="none" count="6"] displays exactly 6 products. Perfect for curated product showcases.
Is the plugin mobile-friendly?
Absolutely! The plugin uses a responsive, mobile-first design that looks great on all devices and screen sizes.
Is the product data (prices, availability) always accurate?
It depends on the data path. With your own credentials (Creators API or PA-API v5), the plugin shows live price and availability from your own Amazon API connection; Amazon updates that data periodically, so it can occasionally differ slightly from Amazon's website, and we recommend visitors verify details on Amazon before purchasing. With the Managed API (Beta), product data comes through a third-party product-data provider, not Amazon's official Creators API or PA-API, and the plugin does not display scraped price or availability: visitors see a "Check price on Amazon" button that takes them to the live price on Amazon.
What does the Analytics add-on track?
The Analytics add-on tracks visitor interactions including search queries, product clicks, impressions, and filter usage. It provides an admin dashboard with charts and tables, a date range picker (7d/30d/90d/custom), and CSV/JSON export. It is privacy-first - no cookies, no PII, and no IP logging. Session IDs are random UUIDs stored only in the browser's sessionStorage. The add-on requires a Premium license and costs $19/yr.