Affiliate Box for Amazon — Handbookv2.27.2

• Applies to version: 2.27.2
• Plugin settings live at: WordPress admin → Settings → Affiliate Box
• Text domain / slug: doozly-affiliate-box-for-amazon

How to read this handbook. Every section answers one question on its own, without depending on the section before it. That makes it longer than a tutorial and lets you jump straight to what you need — and it lets a support assistant quote a single section without losing the context.

Every label in bold is the exact wording used inside the plugin, so you can search for it on screen.

1. What this plugin does#

1.1 What is Affiliate Box for Amazon?#

Affiliate Box for Amazon puts Amazon affiliate content into WordPress posts and pages using shortcodes. It can show a single product box, a saved box shared by several posts, a four-column comparison table, a bestseller list, a search grid, or an editorial review box carrying your own photos and score.

It is built for the Amazon Associates programme. You store one Associates Tracking ID per Amazon store, and every outbound link is built with the right ID for the store it points at.

1.2 What do I get in the free version?#

Free, with no licence key of any kind:

• Buy on Amazon

  As an Amazon Associate we earn from qualifying purchases.

  — a single product box, written by hand or built in a visual builder with a live preview.
• — saved boxes, stored once and reused by ID across many posts.
• Amazon API — fill title, image, price, brand and savings from an ASIN or a keyword search, using Amazon Creators API credentials.
• Marketplaces — one Associates Tracking ID per Amazon store, with a warning when an ID does not match the store it is filed under.
• Health — a screen that checks your setup for the mistakes that stay invisible.
• All 22 Amazon Associates marketplaces, both layouts, three image sizes, colour pickers, custom button text, and the affiliate disclosure.

1.3 What does a Premium licence add?#

A Premium licence unlocks:

1.4 Which shortcode should I use?#

1.5 Does this plugin work with the block editor, Elementor or a page builder?#

Yes, and in the block editor there is a block of its own. Add Affiliate Box, pick from the list of everything you have saved, and the real box appears in the editor while you choose. No key to copy, nothing to type.

The list holds product boxes, comparison tables, bestseller lists, reviews and rotations together — one block for all of them, with the kind written beside each entry.

Everything is still a shortcode underneath, and shortcodes work in the classic editor, in a Shortcode block, and in the shortcode or text widget of every common page builder. Nothing that already sits in a post needs changing.

2. Installing and activating#

2.1 How do I install the free version?#

1. In WordPress admin, go to Plugins → Add New.
2. Search for Doozly Affiliate Box for Amazon, or upload the ZIP under Plugins → Add New → Upload Plugin.
3. Press Install Now, then Activate.
4. Open Settings → Affiliate Box.

The free version never asks for a licence key and is complete on its own.

2.2 How do I install the Premium version?#

The Premium version is a separate ZIP downloaded from your Freemius account, and it installs into its own folder (doozly-affiliate-box-for-amazon-premium).

1. Download the Premium ZIP from your account.
2. Go to Plugins → Add New → Upload Plugin and upload it.
3. Press Activate.
4. When prompted, enter the licence key from your account.

The separate folder is deliberate: it keeps your paid installation from being overwritten by an update from the WordPress.org directory.

2.3 Why do the Premium tabs still say “Premium plan required” after I paid?#

Because the email address on the licence has not been confirmed yet.

When the plugin connects to the licensing service it sends a confirmation email. Until you press the button in that email, the licence is not yet active and every paid tab shows Premium plan required — even though payment went through.

In almost every reported case the email was in the spam folder. It is sent to the address of the WordPress account you were logged in with when you activated.

The plugin detects this state and shows a notice above all tabs reading One click left: confirm your email address. If you see that notice, nothing is wrong with your purchase — find the email and click the button.

2.4 Can the free and Premium versions be active at the same time?#

They live in different folders, so WordPress sees them as two plugins. The licensing SDK deactivates one when you activate the other, so in normal use only one is ever running.

If you ever see both active, deactivate the free one. Two active copies can leave the site loading the free stylesheet, which makes Premium elements — review boxes in particular — render without their styling.

2.5 Where are the plugin settings?#

Settings → Affiliate Box in the WordPress admin sidebar. The page has a row of tabs across the top. Which tabs appear depends on your build and licence:

Left to right, they run in the order you work in them — what applies to everything, then what you build, then what came of it.

Marketplaces comes before Amazon API, because a Tracking ID is the more basic of the two: without one the plugin earns nothing at all, while the API is optional — product data can be typed in by hand. The other way round does not work: Amazon requires a Tracking ID on every API request, so credentials without one cannot even be tested.

A paid tab is marked either way, but the mark changes once your licence is active. Before it, the tab carries the word PREMIUM — there it explains why the tab is locked, so it has to be readable. After it, the word shrinks to a small blue dot in the tab’s top-right corner, which says what you have rather than what you need. Hover the tab and it spells the meaning out.

The dot exists so all eleven tabs fit on one line. Written out, the five marks take a fifth of the bar — exactly the width that was missing. The dot lies over the tab instead of beside it and therefore takes no width at all.

The General tab opens with a card for every other tab, saying in one line what each is for and linking straight to it. Only the tabs your build actually has appear there, so it never points at something you do not have. On those cards the word PREMIUM stays written out with or without a licence: each card has a row to itself, so a wider label moves nothing — and that is where the dot’s meaning is easiest to pick up.

Below the cards, General holds three numbered sections — Which Amazon store, How every box looks, Affiliate disclosure — one Save Changes button covering all three, and then the Shortcode reference, in grey because nothing in it is a setting. The reference has a Find an attribute box: type asin or price and only the matching rows stay, group headings included.

2.6 What is the “Start here” panel on the General tab?#

On a fresh installation the General tab opens with a short panel called Start here, listing the three steps that get you from installed to earning:

1. Enter your Associates Tracking ID — required. Every Amazon link needs one, and Amazon pays on the ID of the store the purchase happens in. Without it your commission is credited to nobody.
2. Connect the Amazon API — optional, and marked as such. With it a box fills itself from an ASIN; without it you type the title, price and picture in by hand and everything else works the same.
3. Build your first box — required.

A step you have finished turns green and loses its button. The next step still outstanding is outlined in blue; that is always a required step, never the optional one.

The panel removes itself. Once the two required steps are done it never appears again — there is nothing to dismiss and no setting to find. It counts a box as built if you have saved one anywhere, or if a shortcode of the plugin’s has been found in one of your posts, so writing shortcodes straight into articles counts too.

If you are set up in a way the plugin cannot see, I am set up already — hide this at the foot of the panel removes it for good.

2.7 What happens to my content if my licence expires?#

Your saved boxes, tables, lists and reviews stay in the database untouched. The Premium shortcodes stop rendering for visitors — nothing broken appears on the page — and administrators see a short note in place of the element saying a Premium licence is needed. Free features keep working exactly as before.

3. Your first product box#

This takes about five minutes and does not need Amazon API credentials.

3.1 Step 1 — Enter your Associates Tracking ID#

1. Go to Settings → Affiliate Box → Marketplaces.
2. Find the row for the Amazon store you are enrolled in — for example United States (.com).
3. Paste your Associates Tracking ID into that row (it looks like yourname-20).
4. Press Save Tracking IDs.

3.2 Step 2 — Choose your default marketplace#

1. Go to Settings → Affiliate Box → General.
2. Under Which Amazon store, set Default marketplace to the store most of your links point at.
3. Save.

3.3 Step 3 — Build the box#

1. Go to Settings → Affiliate Box → Product Boxes.
2. Fill in at least Title, ASIN and Image URL. If you have Amazon API credentials, use Search Amazon or Fetch by ASIN instead and the fields fill themselves.
3. Watch the preview underneath. It is rendered by the plugin itself, not an imitation, so what you see is what the page will show.
4. Press Copy shortcode.

3.4 Step 4 — Put it on a page#

In the block editor, add the Affiliate Box block — type /affiliate and it comes up. Choose your box from the list and it appears right there, drawn by the plugin itself rather than an imitation. Publish and view the page.

Two settings sit in the sidebar beside the block, Layout and Image size. They belong to the place, not to the box: the same box goes wide in an article and narrow in a sidebar, and the settings page cannot know which. Leave them on As the box is set up and the box keeps its own.

The shortcode remains the way in for the classic editor and page builders: copy from the Shortcode column and paste it wherever text goes. Both produce exactly the same box — the block runs the shortcode.

3.5 Step 5 — Or put it in a sidebar#

Under Appearance → Widgets, add the Affiliate Box widget, choose an entry, and give it a heading if you want one. It defaults to the narrow layout, because a box built for an article runs over the edge of a sidebar.

On a modern theme the widget areas are block areas, so the Affiliate Box block works there too, and does the same thing. The widget is for sites running Classic Widgets, where blocks are not offered.

A widget with nothing chosen draws nothing at all — not even its heading.

4. Tracking IDs and Amazon stores#

4.1 Why does every Amazon store need its own Tracking ID?#

Amazon runs the Associates programme per country. A Tracking ID issued for amazon.com is not valid on amazon.de. If a link to amazon.de carries a US ID, the link still works and the reader can still buy — but Amazon credits the sale to nobody, and you earn nothing.

This is the single most expensive misconfiguration possible with this plugin, and it makes no noise at all. Nothing breaks; the money simply does not arrive.

4.2 How do I enter a Tracking ID for a store?#

1. Go to Settings → Affiliate Box → Marketplaces.
2. Find the row for the store. The 22 stores are grouped into Amazon’s three regions — North America, Europe, Middle East & India, and Asia-Pacific — the same grouping the Amazon API tab uses for credentials. India sits under Europe; that is Amazon’s own filing, not a mistake.
3. Paste the ID for that store.
4. Press Save Tracking IDs.

Fill in one row for every store you are actually enrolled in. Stores you leave blank borrow the ID of your fallback marketplace, which produces a working link that earns nothing.

Most people fill in one or two rows. Twenty blank fields are the normal state of this screen, not an unfinished job.

How to read the screen. The panel at the top says whether anything is missing, and each row carries its own state on its left edge:

A blue “3 items link here” badge counts the saved boxes, tables, bestseller lists and review boxes that point at that store. Saved content is what gets counted — a

Grey italic text in a field is the placeholder, not a value: it shows the suffix Amazon uses for that store (yourtag-21). A real value is bold monospace with a green edge, and switches to that look as soon as you type.

4.3 What is the fallback marketplace?#

The fallback marketplace is the store whose Tracking ID stands in whenever a store has none of its own. You choose it under Settings → Affiliate Box → General → Which Amazon store, in the field labelled Falls a store has no Tracking ID, use.

It exists so that a link is never tagless. It is not a substitute for enrolling: a link to amazon.de under a US ID earns nothing.

4.4 What is the difference between the default marketplace and the fallback marketplace?#

They answer two different questions.

• Default marketplace — which store does a box point at when the shortcode does not say?
• Fallback marketplace — whose Tracking ID is used when the store being linked to has none of its own?

They are often the same store, but they do not have to be.

Both sit in the same section — General → Which Amazon store — with the same two sentences printed between the heading and the fields, so the distinction is on the screen where you make the choice.

4.5 Why does the plugin warn that my Tracking ID does not match the store?#

Amazon Tracking IDs end in a country-specific suffix: -20 and -21 are the two most common, but each store has its own. The plugin checks the suffix of the ID you entered against the store it is filed under and warns when they disagree.

The warning does not block saving — the plugin cannot know your account for certain. It is a prompt to check in Associates Central, because a mismatched suffix almost always means the ID was pasted into the wrong row.

4.6 Which Amazon stores are supported?#

All 22 active Amazon Associates marketplaces:

The key is what you write in a shortcode: marketplace="de", asin_uk="...".

5. The Amazon API#

5.1 What does the Amazon API do for me?#

With credentials configured, the plugin can:

• Search Amazon by keyword and let you click a result to fill a box.
• Fetch a product by ASIN and fill title, image, price, former price, savings and brand.
• Build bestseller lists and search grids, which are fetched live.
• Refresh saved boxes and bestseller lists nightly (Premium).

5.2 Do I need Amazon API credentials?#

No. Product boxes, saved boxes and comparison tables all work without them — you type the title, image and price yourself.

You do need credentials for bestseller lists, search grids and any automatic filling or refreshing.

5.3 Which Amazon API does this plugin use?#

The Amazon Creators API. Amazon retired the older Product Advertising API (PA-API) on 15 May 2026; it now answers every request with HTTP 403.

AWS Access Keys and Secret Keys do not work. You need a Credential ID and a Credential Secret, created in Associates Central under Tools → Creators API.

If you previously stored PA-API keys, they are ignored and removed when you save Creators API credentials.

5.4 Why are credentials issued per region?#

Amazon issues one credential per region, and a credential only works for the marketplaces of that region. The plugin therefore stores three credential pairs:

Most sites only need one. Fill in the regions you actually link to. The version shown next to your Credential ID in Associates Central tells you which row it belongs in.

5.5 How do I enter Amazon API credentials?#

1. Go to Settings → Affiliate Box → Amazon API.
2. Under Amazon Creators API, find the row for your region.
3. Paste the Credential ID and the Credential Secret.
4. Press Save credentials.

The secret is stored separately and never displayed again. On later visits the field shows a masked placeholder; leave the secret blank to keep the one already stored.

5.6 How do I tell at a glance whether the API is working?#

The top of Settings → Affiliate Box → Amazon API carries one line that says so, in colour:

Underneath it counts the requests made today against the 8,640 a fresh Creators API account is allowed.

5.7 How do I test that my credentials work?#

On Settings → Affiliate Box → Amazon API, scroll to Test connection, pick a marketplace and press Test connection.

It sends one live search using that marketplace’s Associates Tracking ID and its region’s credential, bypassing the cache, so it always reflects the current state. A green Test request succeeded means everything is in place.

With no Tracking ID entered anywhere, nothing is sent. Amazon requires one on every request, so the test would fail before it reached them — and a failure there looks like a credential problem when it is not. Instead the tab says so and offers a button straight to the Marketplaces tab. Beside the test button, Tag to be used always names the Tracking ID the request would carry.

5.8 What does “A complete Creators API secret is 80 characters” mean?#

A valid Creators API secret is exactly 80 characters. If the plugin reports a different length, the value in the field was truncated when it was copied — usually a partial selection or a line break lost in transit.

Amazon will refuse a short secret with invalid_client. Paste the whole value again.

5.9 Why does Amazon return products without a price?#

Two causes, and the Recent API errors table on the Amazon API tab says which one applies:

1. Your Associates account is not cleared for offers data. This is typical when recent qualifying sales came from SiteStripe or manual links rather than API-rendered links.
2. The offers resources were rejected and the plugin retried without them, so titles and images would still load.

The Last raw API response (debug) panel below shows exactly what Amazon sent.

5.10 Why are star ratings and review counts always empty?#

Because Amazon does not send them. The API accepts a request for a star rating and a review count and then answers without them. This is a long-standing gap in Amazon’s API, not a fault of your credential, and it is the reason no Amazon affiliate plugin fills these reliably.

Type them in yourself and check them now and then — they are the one part of a box that does not keep itself current.

The review count matters: 4.6 from nine buyers and 4.6 from eleven thousand are not the same recommendation, and the count is what tells them apart. Leave it at 0 to show the stars without a count.

5.11 What are the request limits?#

A fresh Creators API account gets one request per second and 8,640 per day.

The plugin protects that budget in three ways:

• Responses are cached (see below), so a page view usually costs no request at all.
• A brake pauses requests after a throttled response, so one rejection does not cascade into a permanent block.
• The visual builder does not auto-fetch while you type; use the explicit Fetch by ASIN or Search Amazon buttons.

5.12 How long is Amazon data cached, and why is 24 hours the maximum?#

Set under Settings → Affiliate Box → Amazon API → Cache duration for Amazon API responses. Three choices: 6 hours, 12 hours, 24 hours (recommended).

The maximum is capped at 24 hours deliberately. Amazon’s Associates Program IP License allows Product Advertising Content to be cached for up to 24 hours; caching longer violates the agreement and can get your Associates account suspended.

That is the cache. A second rule governs what is on the page: a price must carry a date/time stamp unless it is refreshed hourly. The plugin does not print one — see 19.2.

Recommended: 24 hours, combined with the nightly refresh. That gives the fewest possible API requests — typically one per bestseller list per day.

5.13 What does the nightly refresh cover? (Premium)#

Set under Settings → Affiliate Box → Amazon API. It refreshes bestseller lists and saved boxes.

Comparison tables are not included. They store the product data you fetched in the admin and do not re-query Amazon on page load. Use the Fetch from Amazon button inside a table when you want those refreshed.

Preferred refresh time sets the hour, in site-local time. Off-peak hours like 02:00–04:00 are recommended so the refresh finishes before traffic picks up.

5.14 How do I clear the cache?#

Settings → Affiliate Box → Amazon API → Clear cache, tokens and log.

This removes cached Amazon responses, the stored access tokens and the error log. Your credentials, boxes, tables and lists are not touched.

6. Product Boxes —

Buy on Amazon

As an Amazon Associate we earn from qualifying purchases.

#

Free.

6.1 What is a product box?#

A single, self-contained box for one product: image, brand, title, star rating, price, a former price with a discount badge, a call-to-action button and the affiliate disclosure.

You build a box once under Settings → Affiliate Box → Product Boxes, and a post shows it with one short line:

The product lives in one place, not in the post text. That is what lets the same box appear in twenty posts and still be changed once — and it is what makes it possible to keep the price honest, because a price written into a post is a price nobody ever revisits.

6.2 How do I create a product box?#

1. Go to Settings → Affiliate Box → Product Boxes.
2. Press Add new product box.
3. Fill in the fields, or use Fill from Amazon if you have API credentials: type into Search keywords and press Search Amazon, then click a result — or type into Or enter ASIN and press Fetch by ASIN.
4. Press Save product box.
5. Back in the list, click the shortcode in the Shortcode column. It goes straight to your clipboard.

You do not need API credentials to create a box. Without them you type the title, image and price yourself, and nothing on this screen is locked.

Only ASIN carries a needed marker: it builds the affiliate link, and it is what a refresh looks the product up by.

Internal label is the name this box goes by in the list, and nothing a reader ever sees. Leave it empty and it is filled from the product title, shortened to its head — enough to tell one box from another once you have thirty of them.

6.3 Where do I see what a box will look like?#

Once a box has been saved, As it is saved now at the top of the editor shows the box itself, drawn by the same code a post uses — not an imitation that can drift.

It shows the saved state, so press Save product box to see a change there.

While you are choosing colours, How it will look further down shows a small model of the card — image, title, price and button — and it follows every change as you make it, without saving.

6.4 What is the key in box="a7f3k2c9", and can it change?#

It is the permanent name of that box. The plugin gives it out once, it is never shown as an editable field, and nothing can move it to another box.

It is deliberately not the row number. A number is handed out by this installation; move your content to another site and the numbers are handed out again in a different order. A post asking for box 3 would then show whichever box happened to become number 3 — a different product, under your affiliate link, with nothing on screen to say so. The key travels with the box and always means the same one.

6.5 What do the colours in a box do?#

A box carries three of its own: Button color, Background color and Text color. Each is an override — leave it blank and the box follows How every box looks on the General tab, which in turn falls back to the plugin’s own design.

Above them sit the seven ready-made schemes (see 15.1); one click sets all three.

Where a pair would be hard to read, the editor says so. Text at less than about 4.5:1 against the background is named with its measured ratio, and saved anyway — the plugin reports, it does not refuse.

6.6 What layouts are there?#

Five. Every list that offers them — the General tab, the box itself, the block and the widget — shows the same four names with their largest size in brackets, so you can pick by the space you have.

• In post (640 px) — image on the left, text on the right. The default, and the one for the middle of an article.
• Sidebar (400 px) — image on top, text underneath, centred. For a narrow column; it fills the column up to 400px.
• Compact (640 × 78 px) — one line: thumbnail, name, price, button. For naming a product without breaking the paragraph, and for a short list of recommendations in a sidebar. The name is cut with an ellipsis rather than wrapped, and the star rating and brand line are left out — one line has to stay one line. On a phone it folds into two.
• Hero (960 px) — wide, with a bigger picture, a bigger name and the line above it. For the pick at the top of a review. It wants a theme with a wide content column; in a narrow one it simply fills the column, and the effect is lost.
• Button only (auto × 38 px) — no card at all: just the call to action, for after a paragraph that has already named the product. No picture, no title, no price, because they are in the sentence above. Its width follows the button text and its height your theme’s. Set the disclosure to Once per page first, or every button carries its own — see §16.2.

The width is a cap: a box never grows past it, and in a narrower column it simply fits the column. Heights follow what the box shows — a title over two lines makes a taller box — which is why only Compact, whose whole point is a fixed line, carries a height in its name. Its height follows the image size: 74px small, 78px medium, 94px large.

Set the site-wide default under Settings → Affiliate Box → General → Default layout, or set Layout on the box itself. A block or a widget can override it for one placement, because the right layout depends on where the box stands, not on the box.

6.6.2 Picture on the right#

A tick box in the box editor, under Layout. It mirrors the box: picture on the right, text on the left.

It is meant for several boxes one after another. Three identical arrangements read as a catalogue; alternating sides read as an article somebody wrote. It is a property of the box rather than of the placement, so a box keeps its side wherever it appears — which is what makes the alternation work at all.

There is nothing to mirror in Sidebar (it stacks) or Button only (it has no picture), so it is ignored there, and a box that stacks on a phone always puts the picture on top. In a shortcode it is image_right="1".

6.6.1 What is “Line above the name”?#

A short line in small capitals above the product name — Our pick, Best value, Editor’s choice. Leave it empty and none appears.

It is what turns the Hero layout into a recommendation rather than just a wider box, which is why the field sits on the box and not on the layout: the same box keeps its line wherever it is shown. The Compact layout leaves it out, because one line has to stay one line.

If the box also carries a Brand, the two share one line — OUR PICK · AMAZON — rather than stacking. They are the same size and both in capitals, so one above the other read as clutter above the title rather than as two separate facts.

In a shortcode it is eyebrow="Our pick", and it travels with the self-contained version of a box.

6.7 How do I show a discount?#

Fill in both Former price (crossed out) and Discount. Either one alone shows nothing: a struck-through price without a percentage reads as a mistake, and a percentage without a price has nothing to be a percentage of.

Type the discount as a plain number — 22 becomes a −22% badge.

6.8 How do I refresh a box from Amazon?#

Each row in the list has a Refresh button that fetches that box from Amazon again.

The list says by itself which boxes need it. A panel above it counts how many have not been refreshed in over a week, and the Refreshed column shows an age rather than a date — 5 days ago, 2 weeks ago — with the exact timestamp in its tooltip. A row over a week old is marked amber and its Refresh button is highlighted; a row that says never was filled in by hand and has nothing to refresh from, which is not a fault.

With Premium, the nightly refresh does this for every box automatically.

6.9 How do I duplicate a box?#

Press Duplicate in the row. The copy opens for editing immediately, named <original> (copy), with its “last refreshed” timestamp cleared — a copy has never been fetched from Amazon, whatever the original said.

Duplicating keeps the label, button text, colours, layout, image size and the detail switches. That is what you duplicate a box for. The copy is given its own key, so the two can never be confused.

6.10 What does “Restore default appearance” do?#

It empties that box’s colour fields so the stylesheet decides again, and puts the details-to-show switches back to their shipped defaults.

Not touched: ASIN, title, image, price, marketplace and the store rows. It restores how a box looks, never what it says.

6.11 Why did my review count of “11,482” become 11?#

It does not any more. A review count copied from Amazon arrives as 11,482 or 11.482, and the separators are stripped before it is saved. A discount typed as 22% keeps only the number, so it can never render as -22%%.

If you write a shortcode by hand instead, use a plain number: rating_count="11482". The thousands separator is added for display automatically, in the reader’s locale.

6.12 Can a post carry the product data itself instead?#

Yes, and older posts that do keep working.

It is no longer offered as a way of working, for one reason: a product written into a post text is never refreshed. Nothing asks Amazon about it again, so it is the data that ages worst — which is why the plugin grew a scan that reads through your posts looking for exactly these.

With box set, the product details always come from the saved box. Only layout, image_size, bg_color and button_text are read from the shortcode as well — otherwise a price in a post would go stale again, which is the problem a saved box solves.

There is one case where the long form is the better answer: moving content. WordPress exports posts, not settings, so an article that travels to another site arrives without your boxes. For that, open Product Boxes, find the row, and click Self-contained version in the Shortcode column. You get the same box written out in full, ready to paste into an article that has to stand on its own.

Read what it says underneath before you use it. That copy stops being looked after — nothing refreshes a price living in post text — and it cannot carry the box’s own button colour, its text colour or the show/hide switches, because

6.13 What is the minimum shortcode that works?#

Everything else comes from the box. Writing the data out by hand instead, the minimum that produces something useful is an ASIN and a title:

		

			


				
				


					
					
											

							
								Echo Dot (4th Gen)							
						
					
					
					
					

						
							
							Buy on Amazon
						
					

											
As an Amazon Associate we earn from qualifying purchases.
					
				
			
		
		

6.14 Full attribute reference for

Buy on Amazon

As an Amazon Associate we earn from qualifying purchases.

#

6.15 Showing a different box each day — #

A box in a sidebar stays there for months. A regular reader sees it on every visit, and after the third time they stop seeing it at all. A rotation is a set of your saved product boxes and a rule for when to change: every day, every hour or every week.

Set one up under Settings → Affiliate Box → Rotation: give it a name for your own use, pick the boxes that should take turns, choose how often. Then put it on the page like anything else — the Affiliate Box block, the widget, or .

Where it belongs. A sidebar, a footer, a “what we recommend” spot — places that do not belong to one article. Inside an article about one product a rotation is the wrong tool: the text talks about that product, and showing a different one tomorrow makes the page disagree with itself.

Everyone sees the same box on the same day. That is deliberate, and two things depend on it. Your pages are almost certainly cached — by a plugin, by your host, or by a CDN — and a choice made at random would freeze into that cache and never change again. And a report about a box only means something if the box was shown to everybody, not to a random half.

It is also an A/B test. Reports counts each box on its own, so two boxes for the same product — a different photo, a different button, a different layout — tell you which one earns its place. Give it enough days to be more than noise.

The small print. A rotation holds saved product boxes, not tables, lists or reviews: those differ so much in height that the page would jump on every change. At most ten, because every box in a rotation is written into the page — though only the one on show loads its picture, so the extra weight is markup and nothing else. Delete a box that is in a rotation and it simply drops out; the rest carry on. A rotation with one box left shows that box and stops rotating, and the Rotation tab says so.

7. One product, several stores#

The rows are free to fill in; acting on them needs Premium.

7.1 Why does the same product need more than one ASIN?#

An ASIN belongs to one Amazon store. The same ice maker is B08N5WRWNW on amazon.com and something else entirely on amazon.de. Point a German reader at the American product ID and they land on a page that does not exist.

So a box holds one ASIN for its own store, and a store map for the others: one row per store, each naming what that store should show and where its readers should go.

7.2 How do I add a store to a box?#

1. Open the box under Settings → Affiliate Box → Product Boxes and press Edit.
2. Scroll to One product, several stores.
3. Press Add a store.
4. Choose the store, then fill in what you know: ASIN, Search term, Title, Image URL, Price.
5. Press Save product box.

A store with no row of its own falls back to Search term for other countries higher up the same screen, and failing that to a search built from the title.

7.3 What does a store row need in order to count?#

A destination: an ASIN, or a search term, or a title short enough to become one. A row with none of those is dropped when you save.

That is deliberate. A row carrying only an image would swap the picture while the link stayed on the store it was already pointing at — the reader sees a French product photo over an American link. That is worse than no localisation at all.

The price is only kept next to an ASIN. Beside a search term it would be one figure above a result list of twenty other figures.

7.4 What happens in a store I have no row for?#

The reader is sent to a search for the product on their own Amazon, under the Tracking ID that earns there — not to a product ID that store may not have.

It is the second-best answer and never a wrong one. A search term you choose yourself beats one derived from the title: “Eismaschine” finds far more on amazon.de than “ice maker” does.

7.5 Which stores does the nightly refresh keep current?#

Only stores that have a Tracking ID of their own, entered under Marketplaces.

That is the same set geotargeting is allowed to send anyone to, and for the same reason: Amazon runs the Associates programme per country and credits a sale to the ID of the store it happens in. A store with no ID of its own earns nothing, so nobody is routed there — and a price nobody will ever see is not worth an Amazon request.

In the store dropdown such a store is marked — no Tracking ID. Add one under Marketplaces and that row starts refreshing by itself the following night; there is no second switch to find.

7.6 A row says Amazon no longer has this ASIN. What now?#

The nightly refresh asked Amazon about that ASIN in that store, and Amazon answered that it does not know it.

The row is stood down, not deleted: readers of that store get the search instead of a link into the void, while the ASIN, title and image you entered stay on screen so you can see what happened and decide. Enter a different ASIN and the row goes back into service on the next save.

7.7 When should I switch on “Same ASIN everywhere”?#

For books, and almost nothing else.

A book’s ASIN is its ISBN-10, and Amazon carries it under that number in every store — so the same ID works worldwide and beats any search. Every other kind of product has a different ID per store. Switch this on for one of those and every store outside the box’s own gets a link to a page that does not exist.

7.8 Can I switch geotargeting off for one box?#

Yes. Geotargeting for this box decides whether this one box follows the reader’s country. Left at (use the global setting) it does what the Geotargeting tab says; set it to On for this box or Off for this box and this box alone stops asking.

Useful for a product that is genuinely sold in one country only — sending a reader somewhere it does not exist earns nothing and wastes the click.

7.9 Can a box point somewhere other than its product page?#

Not a saved box, and that is deliberate. A box is built around its ASIN: the nightly refresh fetches the price through it, Health checks it, and the store rows hang off it. A link pointing elsewhere would let the price and the button disagree — the box would show the price of the product page and send the reader to a storefront where that figure means nothing.

For a link to a storefront, a filtered search or a campaign page, write

8. Comparison Tables — #

Premium.

8.1 What does a comparison table do?#

It puts up to four products side by side in columns, with a shared list of feature rows underneath so a reader can compare the same property across all of them. One column can be highlighted as your pick.

8.2 How do I build a comparison table?#

1. Go to Settings → Affiliate Box → Comparison Tables.
2. Press Add new table.
3. Give it a Title (internal) and optionally a Heading shown above the table.
4. Under Feature labels, the first of the two numbered steps, name the rows you want to compare: “Capacity”, “Noise”, “Warranty”. A box for each one appears in every column further down as you type, so the whole table can be filled in on one pass.
5. Under Products, fill each of the four columns — they are labelled Column 1 to Column 4. With API credentials you can search Amazon and drop a result straight into a column, or type four ASINs and press Fetch all 4 from Amazon.
6. Save, then insert into your post — click the shortcode in the list to copy it.

Once a table has been saved, As it is saved now at the top of the editor shows the table itself, drawn by the same code a post uses. Save to see a change reflected there.

Renaming a label keeps the values you have typed. The value boxes belong to the row, not to its wording, so changing “Weight” to “Weight (kg)” carries the values with it.

The same label twice is flagged and saved once. Two identical labels would otherwise become two identical rows, each showing the same value.

A feature row with no values anywhere renders as a row of dashes. The editor counts those and names them under the labels, because the labels sit at the top of the form and the values sit inside each column, far apart.

8.3 Which column becomes which in the finished table?#

A column with neither a title nor an ASIN is left out, and the ones after it move up. Leave Column 1 blank and fill Column 3, and Column 3 is what a reader sees first.

Each column card says which it will be — Shows as column 2 — or, when it is blank, Empty — left out of the table. The card marked ★ Top pick is the one drawn as your recommendation, and the builder colours it the same way throughout so you can see it while you work.

8.4 How do I colour a comparison table?#

Under How it looks — the third numbered step in the editor — a table has three colours, and they apply to the table as a whole:

Start from a ready-made scheme. Six of them sit above the fields; one click sets all three. Each has been checked for readable text, and beside the fields a small model shows how the three sit together, updating as you change them.

The ribbon’s text colour is not yours to choose — it is calculated. Dark text on Amazon orange reaches 7.9:1; the same dark text on teal manages only 3.1:1, so no fixed colour can serve every accent. The plugin measures each one and takes whichever of black or white reads better.

Leave a colour blank and the plugin’s own is used. Nothing is written into the page unless you chose it, so clearing a field really does restore the default.

The buy button keeps its own colour. It is deliberately not part of a scheme: orange is what readers expect a buy button on an Amazon box to look like, and it is set once for the whole site under General → How every box looks.

The per-column Column background and Product title colour further down are still there for the rare case where one column must differ. Setting a background on the recommended column replaces the marking the scheme gives it, so leave it blank unless you mean exactly that.

8.5 What can each column carry?#

ASIN, search term, title, image, price, former price, savings percentage, star rating, button text, marketplace, a badge (such as “Best value”), a Column background, a Product title colour, and one value per feature row.

Where you set both colours on a column, the editor measures them against each other and says so when the pair falls below 4.5:1 — a white title on a white column is saved, but not silently.

For the table as a whole, see 8.4 — that is where a scheme is chosen, and it is the easier way in.

8.6 Can I build a table without saving it?#

Yes, if you have Amazon API credentials. Pass ASINs directly:

The products are fetched from Amazon at render time. Feature values cannot be supplied this way — only the row labels — so an ad-hoc table is best for a quick side-by-side, and a saved table for anything you will keep.

8.7 Attribute reference for #

8.8 Are comparison tables refreshed nightly?#

No. A comparison table stores the product data you fetched in the admin and does not re-query Amazon when a page loads. Use the Fetch from Amazon button inside the table when you want it refreshed.

9. Bestseller Lists — #

Premium. Requires Amazon API credentials.

9.1 What does a bestseller list do?#

It fetches products live from Amazon for a keyword or an Amazon category and shows them as a grid or a list. Because it is fetched live, it keeps its products, prices and pictures current without you touching it.

It is not Amazon’s sales ranking. The Creators API does not expose the bestseller rank at all. What the list shows is what Amazon puts first for your search term — its own relevance order (SortBy=Featured) inside the keywords or category you choose. In practice that is close to a bestseller list; it is not the same list you see on Amazon’s own bestseller pages, and comparing the two will show differences. The tab says the same thing above the list.

9.2 What do the five colours in a bestseller list do?#

A list carries more colour than anything else in the plugin: Product title color, Detail text color, Price color, and a background for odd and even rows. Leave one blank and the plugin’s own is used.

The seven ready-made schemes above the fields fill all five at once (see 15.1).

Three text colours on two backgrounds are six combinations, and each can go wrong on its own — give the even rows a dark blue and the default detail text becomes unreadable on every second card. The editor measures all six and says which fall below about 4.5:1, naming the pair and the ratio. It never refuses; a deliberately quiet colour is your decision.

The report keeps up as you choose. It used to be built from the saved state and sat still, so it could claim “readable” for colours you had just changed.

Beside it, a two-row model shows the odd and even rows with all three text colours on them, and follows every change.

9.3 How do I create a bestseller list?#

1. Go to Settings → Affiliate Box → Bestsellers.
2. Press Add new bestseller list.
3. Enter keywords, and optionally a browse node to narrow them to one Amazon category.
4. Choose the number of products, the layout and the columns.
5. Save, then insert — click the shortcode in the list to copy it.

Bestseller lists need Amazon API credentials: the products come from Amazon on every render. Without them the tab says so and the create button stays inactive.

The editor groups its fields under What the list shows, Layout and Colours.

9.4 What is a browse node?#

A browse node is Amazon’s numeric ID for a category. Using one instead of keywords gives you the products of that category rather than the results of a search — usually a cleaner, more stable list.

You can find browse node IDs in the URL of an Amazon category page: open the category on Amazon and copy the number after node=. The editor keeps the full instructions behind How to find a browse node.

Browse node IDs differ per Amazon store. A node from amazon.com does not work on amazon.de or amazon.co.uk — take it from the marketplace you set on the list.

9.5 What can I configure on a bestseller list?#

Heading and whether to show it, keywords, browse node, number of products, marketplace, layout (grid or list), number of columns, and switches for brand, feature bullets, price, savings and star rating. Plus colours for row backgrounds (odd and even), title, details and price.

The colours are checked for readability. Three text colours over two row backgrounds is six combinations, and a panel under the colour pickers measures all six. It names any that fall below 4.5:1, with the ratio and both hex values. A colour left blank is measured against the built-in one it falls back to — so giving the even rows a dark background is caught even though you never touched a text colour. Nothing is refused; the list saves either way.

Feature bullets are off by default. Amazon’s feature bullets run to several lines each, and three of them under every card bury the price and push the button out of sight. Switch them on for a single-column list, where there is room to read them.

9.6 Attribute reference for #

9.7 Why are bestseller lists not geotargeted?#

Because there is nothing to rewrite. A bestseller list’s products are fetched live from Amazon for one store, and the bestsellers of amazon.de are different products from those of amazon.com — different ASINs, in a different order.

Geotargeting a bestseller list would mean fetching it again for every reader’s country. Amazon issues API credentials per region, so that would only work for sellers holding a credential for every region.

A bestseller list therefore shows the store it was built for, to everybody. This is a deliberate limitation, not a bug.

10. Search Grids — #

Premium. Requires Amazon API credentials.

10.1 What does a search grid do?#

It shows live Amazon search results for a keyword as a grid. Unlike a bestseller list it is not saved anywhere — everything is in the shortcode.

10.2 Attribute reference for #

Example:

Leaving out keywords shows an administrator note asking for it and nothing to visitors.

10.3 Are search grids geotargeted?#

No, for the same reason as bestseller lists: the results are fetched live for one store, and the results for another store are different products.

11. Review Boxes — #

Premium.

11.1 What is a review box for?#

Everything else in this plugin describes what Amazon sells. A review box describes what you found out.

It carries your own photograph of the product, your own score, what was good and what was not, a verdict, and the individual criteria as labelled bars. It is built for people writing genuine, first-hand product reviews.

11.2 How do I create a review box?#

1. Go to Settings → Affiliate Box → Reviews.
2. Press Add new review.
3. Fill in at least Product — the box does not render without it.
4. Add your photos, your score, pros and cons, and a verdict.
5. Watch the live preview beside the form.
6. Press Save review, then insert .

takes a single attribute, id.

11.3 How do I add my own photos?#

Press Add a photo. This opens the WordPress media library, where you can upload a new picture or pick one you already have. Up to 8 photos.

The first photo is the lead photo — the large one. Use the arrow buttons on each tile to reorder; the tile marked Lead photo is the one that will be shown large.

Photos are stored as media library attachments rather than as web addresses. That matters for two reasons: WordPress can then serve the right size for each screen instead of sending a phone the 3000-pixel original of a phone photo, and the pictures survive a move to another domain.

11.4 Is my own photo safer than an Amazon product image?#

Yes, and this is worth knowing. The Associates Operating Agreement limits which of Amazon’s product images you may display. A photograph you took yourself is not one of theirs and falls outside that restriction entirely.

The warning that appears on every other image field in this plugin does not apply here.

11.5 Should I type the score or let it be calculated?#

Both work, and the box handles them differently:

• No criteria filled in → simply type a number into Overall score. Somebody writing a quick review should not have to fill in a table first.
• Criteria filled in → leave Overall score empty and the criteria are averaged into it. The editor shows the running average as you type.
• Both → your typed number wins. Useful when the average does not match what you would actually tell a friend.

All criteria count the same. There are no weights, deliberately: a weighted average the reader cannot see is not more honest than a plain one, only harder to check.

11.6 What scale can I use?#

Out of 10 (the default) or out of 5, set with the Scale field. If the box shows stars, they are drawn from the same score, rescaled to five.

Changing the scale converts your scores rather than discarding them. 9 out of 10 becomes 4.5 out of 5 — the same judgement in another unit — and the preview shows the converted numbers before you save.

11.7 Why does my criterion not appear in the box?#

A criterion needs a number to appear. A name on its own is the question without the answer, and on the page it would be a bare word under your verdict.

The row stays saved in the editor either way — nothing is lost — but it is not drawn. The preview beside the form always shows what the reader will get.

11.8 Why is there a label above the score?#

Because a large number sitting beside an Amazon price and an Amazon button reads as Amazon’s rating unless something says whose it is.

The label — Our score by default, and freely editable — is what makes the score unmistakably yours. For the same reason, Amazon’s own star rating never appears in a review box at all. One box, one verdict, one voice.

11.9 What can I change about how a review box looks?#

New boxes start with Photo beside the text and Lead photo with a gallery, because both read better in a normal article column. A box with a single photo shows no thumbnails, and a narrow column stacks the photo above the text by itself — so neither default gets in the way. Boxes you saved earlier keep whatever they were saved with.

The photo frame takes the shape of your lead photo, so nothing is letterboxed or cropped. In a gallery the frame then stays that shape, which is what keeps the page from jumping when a reader clicks a differently-shaped thumbnail.

Five settings, chosen so that no combination can look wrong:

11.10 Why is my review box stacked when I chose “Photo beside the text”?#

Two conditions must both be met, and the box falls back to the stacked layout until they are:

1. The review has at least one photo. A two-column layout with an empty picture column is a void, not a narrower layout.
2. The column is wide enough — roughly 560px. In a narrow column two columns stop being an arrangement and become two strips.

In the side layout the product name, the byline, the score and the verdict all sit beside the photo. The criteria bars, pros and cons and the button return to full width underneath, because they read badly squeezed into 60% of the column.

11.11 Can I change the colour of a review box?#

Two colours, and everything else is worked out from them.

• Accent colour — the score block, the criteria bars, the line above the product name and the rule beside the verdict.
• Background colour — the card itself.

The seven ready-made schemes sit above the two colour pickers. One click sets both, and each has been checked for readable text — the quickest route if you would rather not choose colours at all. They are the same schemes, under the same names, that the other tabs offer; see 15.1.

There is deliberately no separate text colour. Pick a dark background and the box switches to light text, lifts the green and red of the pros and cons, and brightens the price, all on its own. A strip under the picker shows every colour the box will actually use, and it updates as you choose. A colour picker for the text would let somebody put black on dark green, and that is not an error message — it is a review nobody can read.

The editor shows the measured contrast under the background field, so you can see before saving whether the text will be comfortable. A mid grey cannot carry body text in any colour, and the editor says so rather than pretending otherwise.

11.12 Is the button optional?#

Yes. Leave ASIN empty and the box shows no button, no price and no disclosure. That is a perfectly good review.

11.13 Should I put a price on a review box?#

Only if you mean to keep it current. A review is not refreshed nightly — the price is typed by hand and stays as typed. A price that has gone stale is worse than none.

11.14 Does a review box work with geotargeting?#

Yes, and it moves only what belongs to a store:

11.15 What is the schema.org markup on a review box?#

A small block of JSON-LD that travels with the box and describes the review in a form a search engine can read: what was reviewed, who reviewed it, the score, and the pros and cons. It changes nothing a reader sees.

Switch it on or off under Settings → Affiliate Box → Reviews → Structured data for search engines. It is on by default.

What is in it

It is a Product carrying a review, which is Google’s own shape for the review of a product:

A review box with no score produces no markup. A rating is what makes a review snippet, and a review without one would make the product invalid — so the box is drawn as always and simply says nothing about itself.

What is deliberately left out

• No offers and no price. You are not the seller — Amazon is. A price copied into markup goes stale between refreshes while a search engine reads it as a promise.
• No aggregateRating. That claims an average of many ratings. A review box holds exactly one: yours.

Google accepts a product that carries either offers, review or aggregateRating. Ours carries the review — which is why both omissions can stand and the markup still validates.

It promises no stars in Google. The markup makes the review machine-readable. Whether a search engine shows anything for it is the search engine’s decision, and for a reviewer’s own verdict on a product it often shows nothing. Any plugin that promises otherwise is guessing.

Switch it off if another plugin already marks up your reviews. Some SEO plugins add review markup of their own. Two descriptions of the same review on one page are worse than one, and only you can see which plugins you run.

Two review boxes in one post produce two blocks, which is correct: they are two reviews. Remove the shortcode and the markup goes with it — there is nothing left behind to clean up.

Your photographs show the unit you tested and your score is your judgement — both are true in every country, so neither is touched.

12. Geotargeting#

Premium.

12.1 What does geotargeting do?#

It sends each reader to the Amazon store of their own country, under the Tracking ID that earns there. A German reader clicking a box you built on amazon.com lands on amazon.de with your German tag.

12.2 How does the plugin know the visitor’s country?#

In this order:

1. The reader’s browser cache. A country found earlier is kept for 24 hours, so most page views make no network call at all.
2. Your own site, at /wp-json/abfa/v1/country. Many hosts and CDNs state the country of every request they pass on — Cloudflare does it on every plan, including the free one. Your server reads a value that arrived with the request rather than looking anything up. Nothing leaves your site.
3. A free external service, but only if your server cannot say, and only if you leave that switch on.

The plugin first renders the box for your default marketplace, so crawlers and readers with JavaScript disabled still get a working affiliate link, and the page itself stays fully cacheable.

12.3 How do I tell whether geotargeting is actually doing anything?#

The top of Settings → Affiliate Box → Geotargeting lists the three conditions it depends on, each with a tick or a cross:

1. The switch is on.
2. At least two stores can receive readers — that is, have a Tracking ID of their own.
3. A country can be determined, either from your own server or from the external lookup.

If any one of them is missing, geotargeting does nothing at all — and it does nothing silently, because a box with an unchanged link looks exactly like one that has just decided correctly. That is why the three are collected in one place instead of being spread over the page.

12.4 How do I turn geotargeting on?#

1. Go to Settings → Affiliate Box → Geotargeting.
2. Under Enable geotargeting, tick Detect visitor country.
3. Press Save Geotargeting Settings.

You also need a Tracking ID for at least two stores. With only one, there is nothing to route between and geotargeting does nothing at all — the Health tab says so explicitly.

12.5 What is geotargeted and what is not?#

Geotargeted: product boxes, saved boxes, comparison tables and review boxes. Each link, and — where you have filled them in — the store’s own ASIN, image, title and price.

Not geotargeted, and cannot be: bestseller lists and search grids. Their products are fetched live from Amazon for one store, and another store’s bestsellers are different products entirely. See section 9.7.

12.6 Where can geotargeting send a reader?#

Only to stores you have entered a Tracking ID for. A reader whose country maps to a store with no ID of your own keeps the link exactly as rendered.

This is deliberate and it is about money: Amazon pays on the ID of the store the purchase happens in, so a United States ID on amazon.de is not a wrong ID but no ID. Sending somebody to a store you earn nothing in costs you the commission rather than moving it.

12.7 What happens when the reader’s store has no ASIN?#

An ASIN belongs to one Amazon store. Where you filled in a per-store ASIN (asin_de and friends), that one is used. Everywhere else, this setting decides — Settings → Affiliate Box → Geotargeting → When the visitor’s store has no ASIN → Send them to:

A box with no search term falls back to “Leave the link” whatever you choose — a search for nothing is an empty page.

12.8 Why do the price and the star rating disappear when a box moves store?#

Because both belong to the store they were taken from.

A price is in one currency on one store; over a link to a different one it is wrong twice over, and over a search page it describes something that has no single price at all. Amazon’s Operating Agreement asks that a displayed price be the one the linked store currently charges, which settles it.

To keep a price, fill in the per-store price (price_de and friends). A price only survives where the box carries one for the store it is moving to.

12.9 Why does the price disappear from a whole comparison table when only one column moves?#

Because a price row is only meaningful as a whole. 179 € next to a gap next to $149.99 reads as an answer and is not one.

When any column in a table changes store, the price row falls for the entire table. The same applies to the star rating row.

12.10 How do I set a different ASIN, image, title or price per store?#

Two ways.

In the box editor: on the Product Boxes tab, under One product, several stores, press + Add a store and fill in a row.

In the shortcode: append the marketplace key — asin_de="...", image_de="...", title_de="...", price_de="...", search_de="...".

A row earns its place by naming a destination: an ASIN, or a search term, or a title short enough to become one. A row with nothing but an image is ignored — swapping the picture over a link that did not move is worse than not localising at all.

12.11 What about books, where the ASIN is the same everywhere?#

Use asin_global="1".

A book’s ASIN is its ISBN-10, and Amazon carries it under that number in every store. With asin_global="1", the plugin uses the same ASIN everywhere instead of falling back to a search.

For anything else this is almost always wrong, which is why it is never inferred: the same product has a different ID in each store.

12.12 How do I test geotargeting without a VPN?#

Two ways.

The built-in test. On Settings → Affiliate Box → Geotargeting there are two tests. One asks the same sources your readers’ browsers ask and tells you which one answered — the part you cannot otherwise see. The other lets you pick a country and shows which store that reader would reach, and under which Tracking ID, or that they would stay put.

By hand, in the browser console:

localStorage.setItem('abfa_geo_v1', JSON.stringify({country:'DE', ts:Date.now()}))

Reload the page. To go back:

localStorage.removeItem('abfa_geo_v1')

Chrome asks you to type allow pasting the first time you paste into the console.

12.13 Why does geotargeting still show the old country after I changed location?#

Because the country is cached in the reader’s browser for 24 hours. That is deliberate — it means most page views cost no network call — but it is also the reason most geotargeting tests appear to fail.

Clear it with localStorage.removeItem('abfa_geo_v1') in the console, or use the clear button on the Geotargeting tab’s own test.

12.14 Does geotargeting work with page caching?#

Yes. This is why geotargeting runs in the reader’s browser rather than on the server: the HTML is identical for everybody and can be cached whole. The rewriting happens after the page has loaded.

12.15 Is geotargeting a privacy problem? What about GDPR?#

The default path involves no third party at all. Your server already received the reader’s request; answering a question about it tells nobody anything new. There is nothing to consent to and no data leaves your site.

The one thing to decide is the external lookup — Settings → Affiliate Box → Geotargeting → Where the country comes from → If the server cannot say → Ask a free external service instead. This sends the reader’s IP address to a service outside your site, and it is the switch a European site will usually want off.

If the Geotargeting tab tells you your server already states the country, switching the external lookup off costs you nothing today and takes the data transfer out of your privacy policy.

12.16 The Geotargeting tab says “This request carried no country” — what now?#

Either your host does not state one, or you reached that admin screen past your CDN. Check a page on the public site before concluding — many CDNs add the header only on public traffic.

If your server genuinely cannot say, geotargeting depends on the external lookup. Turning that off would leave geotargeting with no country and nothing to do.

13. Reports#

Premium. Off until you switch it on.

13.1 What does Reports tell me that Amazon does not?#

Amazon counts clicks per Tracking ID, never per box — it sees the tag, not the placement. It therefore cannot tell you which box in which post produced a click.

Reports can. It shows which box was seen, which was clicked, and the click rate beside it. The rate is the more interesting column: a box seen five thousand times and clicked twelve times is a different problem from one seen fifty times and clicked twelve times.

Pick the period at the top: 7, 30, 90 or 365 days. Seven days answers “what did yesterday’s post do”; a year answers “which box carries its own weight”. Box views and clicks for the chosen period are shown beside the buttons, so an empty period reads as empty rather than broken.

Under it, Day by day draws one bar per day: box views in light blue, the clicks among them in green, on the same scale. Clicks are usually a thin strip — that is the honest picture, and a second axis would have made them look equal. Hovering a bar gives the exact figures, including for a day with nothing.

Posts with a box in them lists the posts a hand-written

Download CSV hands you the raw rows of the period — day, unit, country, mode, views, clicks — for anything the screen does not answer.

A rate in grey rests on fewer than a hundred views. 0.0 % out of 28 means “too little data”; 0.0 % out of 5,000 means “this box does not work”, and the two should not look alike.

Not counted: readers without JavaScript, and requests that look like a crawler. And these are box views, not visits — a page carrying three boxes counts three. Your analytics tool will therefore show different numbers, and neither is wrong.

13.2 What is the “readers you cannot reach” figure?#

The number at the top of the tab: how often a box was shown to somebody whose Amazon store you have no Tracking ID for, together with the countries they came from — and as a share of all box views in the period, because 1,030 views means something different at 2 % than at 18 %.

A purchase from those readers is credited to nobody. That is not a statistic, it is an invoice: enrol in that store, and the number turns into revenue.

The country table marks those rows, and carries a Clicked column beside Box views: a view is an opportunity, a click is one somebody took.

(Before 2.9.0 that column always read 0 — the click was recorded without the routing mode it belonged to, so it never reached the country row. Numbers from before the update stay as they were recorded; the column fills from then on.)

13.3 How do I switch Reports on?#

Settings → Affiliate Box → Reports → Count views and clicks. It is off until you tick it. While it is off, the tab lists the three questions switching it on answers, so the decision does not need this handbook.

The database table is created the first time an admin page is loaded after the update.

13.4 What exactly is stored?#

Only sums. Specifically not stored: no IP address, no identifier, no session, and no timestamp finer than the day.

Each row holds a day, a unit (which box), a country, a routing mode, a view count and a click count. That makes it statistics with no personal data attached.

13.5 How long are the numbers kept?#

About 400 days, then older rows are removed automatically. The whole table is dropped when you uninstall the plugin.

13.6 Does Reports slow my site down?#

One report per page view, not one per box. On a page with three boxes that is one write instead of three. Clicks are sent in a way that does not hold the reader up and still arrives when they are already leaving the page.

A page with more than 40 counted elements reports the first 40 and drops the rest, so a single page view can never turn into an unbounded number of writes.

13.7 Do clicks on a photo gallery count as affiliate clicks?#

No. Controls inside a box — the thumbnails of a review box gallery, for instance — are excluded. Only clicks that lead out are counted.

14. Health#

Free.

14.1 What is the Health tab for?#

The mistakes that cost money make no noise. A missing Tracking ID does not break a page; it just means Amazon credits the purchase to nobody. Health looks for exactly that class of problem.

It changes nothing and records nothing — it only reads what is already stored. No counters, no visitor data, no new tables.

14.2 How do I know Health has found something?#

A red number appears beside Health in the tab bar, on every tab of the plugin’s settings. It counts only the findings marked Needs attention — notes and passed checks are not counted, because a number that is never zero is a number nobody reads.

At the top of the tab those findings are listed by name, each one a link straight to its place on the page.

14.3 What does Health check?#

Five sections:

Geotargeting — whether it is on, how many stores can actually receive readers (with one, geotargeting does nothing), whether the country comes from your own server or an external service, and whether a country can be determined at all.

Boxes, tables and lists — which boxes and table columns have no search term, which point at a store with no Tracking ID, which prices are more than a week old, and which saved boxes Amazon no longer returns.

That last one costs nothing extra: the nightly refresh fetches every saved box from Amazon anyway, and since 2.10.0 the outcome is written down instead of discarded. Three things can come of it:

Which post uses which box#

Once a day, the plugin reads through your published posts and notes which shortcodes they carry. Two things come of it:

• The Product Boxes list says where each box is used, with links. Nothing else knows this: Reports counts a saved box as itself, because the same box lives in many posts at once.
• Health names saved boxes that appear in no post. They cost nothing, but they are carried along in every list and every count.

It reads all three ways a box reaches a page: a shortcode in the text, the Affiliate Box block — including one sitting inside a Columns block — and a rotation. A box that only appears inside a rotation counts as used in every post that shows the rotation, because that is what it is: shown there, just not every day.

Drafts are not searched. A broken box in an unpublished post costs nothing — but it does mean a box waiting for a draft shows up as unused.

The search takes about a millisecond and a half per post that carries a shortcode, which is why it runs once a day rather than on every page load. Search my posts at the top of Health starts it immediately, and the line beside it says when it last ran.

One failure is never enough to call a product dead. It takes a second failure on a different day — a false red would send you through thirty posts looking for nothing, and after that nobody believes the report again. Pressing Refresh twice in a row therefore changes nothing either.

Amazon API — whether credentials exist, whether every store you earn in is covered by a credential for its region, and whether your Credential Secret has its full 80 characters.

Review boxes — which reviews have no photo of your own, which have a background colour that cannot carry readable text, which are set to “photo beside the text” without a photo (where the setting does nothing), and which show no score at all.

Background jobs — whether the nightly refresh is scheduled at all (WP-Cron is not a clock: it runs when somebody visits, and many hosts switch it off), what the last run did, and whether /wp-json answers — security plugins often block that route, and then every country lookup falls back to the external service without anything saying so.

It also reports Tracking IDs whose country suffix does not match the store they are filed under, and tells you when the affiliate disclosure is switched off.

14.4 What does a finding cost me?#

Where the numbers exist, the finding says so:

Only one store has a Tracking ID There is nothing to route between, so geotargeting does nothing at all. In the last 30 days this cost you 1,030 of 5,860 box views — 17.6 %.

That line comes from Reports and appears only when Reports is on and has counted something. A finding without it is still a finding — an invented number would be worse than none.

Findings that carry a cost are sorted above ones that do not, because a figure is evidence and a rule is only true.

14.5 Is it getting better?#

Beside the count there is a small curve and a sentence: 10 fewer than 2 weeks ago. It draws the number of findings over the days.

A point is recorded each time you open this tab, not every night — the code that runs the checks is only loaded in the admin, and loading it on every page would be weight for a number nobody is looking at. So the curve has a point for every day you looked, and says nothing about the days you did not.

14.6 Can I fix something without leaving the page?#

Where a single click does it, the button is on the finding itself:

Everything else still ends in Go there →, because it needs a decision rather than a click.

14.7 Can I check every product at once?#

Check all products at the top of Health goes through everything that is used on a published page and asks Amazon whether it still exists.

It says beforehand what it will cost: „7 products are used on published pages. Asks Amazon 3 times.” The count is per store, not per ten products — one request asks one Amazon store, so products spread over three stores take three requests however few they are.

What it checks that nothing else does: a

It runs in batches with a visible progress bar, one request at a time, about a second apart. That is not caution: a new Associates account is allowed one request per second, and thirty requests in a row would also run past the time limit PHP is given on many hosts.

Drafts are left out. A product in an unpublished post costs nothing, and it should not cost Amazon requests either.

14.8 Something is gone — what now?#

Where one product is affected, Find a replacement sits on the finding. It opens that saved box with the old product title already in the search field — which is almost always the right search term, because it describes the thing you are replacing.

Where several are affected, the finding leads to Product Boxes instead. Each row there carries its own state — Not on Amazon any more, ASIN is unusable, Last refresh failed once — and its own Find a replacement link. One button can carry one address, not three.

14.9 Why does the first visit take a moment?#

Health asks your own site whether /wp-json/abfa/v1/country answers, and that request has to time out before it can report a failure. The answer is then kept for ten minutes, so opening the tab again is immediate.

Press Check again at the top to discard that answer and test the route straight away — after unblocking the REST API, for example.

14.10 What does “N checks passed” mean?#

Findings that found nothing wrong are collapsed under that line, one group per section. They are still there — a screen that shows only problems leaves you wondering whether anything was checked — but they do not take the same room as a problem. Click the line to see them.

14.11 Is Health available in the free version?#

Yes. Findings that concern Premium features explain what a licence would add, rather than pretending the feature is broken.

15. Appearance and theme integration#

15.1 The colour schemes#

Every screen with colour pickers offers the same seven named schemes above the fields — Amazon orange, Teal on white, Ink on warm paper, Berry on white, Green on off-white, Slate on cool grey and Sky on midnight. One click fills in whatever colours that screen has.

They are one list, used by General, Product Boxes, Bestsellers, Reviews and Comparison Tables alike, so a name means the same thing wherever you meet it. A screen takes the parts it has and leaves the rest: a bestseller list fills five fields from a scheme, a comparison table three, the General tab one.

Every scheme has been checked for readable text in every role it is used — the body text against both backgrounds, the secondary text against the background, the button label against the accent, and the accent used as text against both backgrounds. The worst of those forty-two measurements is 4.7:1, against a threshold of 4.5:1.

A scheme’s accent comes in two shades, and they are not interchangeable. The loud one is meant to be a surface — a button, a ribbon — where the text on it is calculated and always readable. The other is the same hue darkened until it works as text, which is what a bestseller list’s price needs. Amazon orange as a surface is fine; the same orange as text on white is 2.1:1.

Text on a coloured background is calculated, not chosen. Dark text reaches 7.9:1 on Amazon orange but only 3.1:1 on teal, so no fixed colour can serve every accent. The plugin measures each one and takes whichever of black or white reads better. That applies everywhere a button is drawn — in a product box, a saved box, a search grid, a review box and a comparison table — as well as to the ribbon over a top pick and the body text of a comparison table with a dark column background.

The button colour set on the General tab reaches every one of those outputs, including comparison tables.

Nothing is written into the page unless you chose it, so clearing a colour really does restore the plugin’s own.

15.2 Which settings apply to everything?#

Settings → Affiliate Box → General, under How every box looks:

• Button text — the call to action, default Buy on Amazon
• Button color — default #FF9900. The label’s colour follows it: the plugin measures and takes black or white, whichever reads. A dark brand colour used to leave a button whose text was invisible.
• The affiliate disclosure (see section 16)

15.3 Which settings apply only to product boxes?#

Settings → Affiliate Box → General, under How every box looks:

• Default layout — In post (horizontal) or Sidebar (vertical)
• Image size — Small, Medium, Large
• Colour scheme — the seven named schemes, filling the two colours below
• Box background color
• Text color — applies to the product title

These reach

15.4 How do I restyle the boxes from my theme?#

The stylesheet is built around CSS custom properties, so you can restyle without fighting specificity. Set them on :root or on any container:

:root {
  --abfa-ink: #1a1d21;      /* main text */
  --abfa-muted: #6b7280;    /* secondary text */
  --abfa-line: #e3e6ea;     /* borders */
  --abfa-price: #b12704;    /* price colour */
  --abfa-radius: 12px;      /* corner radius */
}

A review box adds its own, so a theme can restyle it with a single value:

.abfa-review {
  --abfa-review-accent: #0f766e;
  --abfa-review-radius: 16px;
  --abfa-review-bg: #fff;
  --abfa-review-good: #15803d;
  --abfa-review-bad: #b91c1c;
}

The plugin deliberately does not set a font family — boxes inherit your theme’s typeface so they read as part of the article rather than as a widget pasted into it.

15.5 Does the plugin load CSS on every page?#

No. The stylesheet — and the geotargeting script, and the counting script — load only on pages where a shortcode is actually used.

15.6 How do I undo all my appearance changes?#

Settings → Affiliate Box → General → Restore default appearance.

This clears layout, image size, button text, all three colours and the disclosure, so every box goes back to the shipped design. Your Tracking IDs, API credentials, saved boxes, comparison tables and bestseller lists stay exactly as they are.

Individual saved entries have their own Restore default appearance button at the bottom of their edit screen.

15.7 Is the output accessible?#

Star ratings carry a spoken label, decorative bars are hidden from screen readers, keyboard focus is visible throughout, and animations respect prefers-reduced-motion. Pros and cons are marked with a tick and a cross as well as colour, so the meaning never rests on colour alone.

16. The affiliate disclosure#

16.1 What is the disclosure and why is it on by default?#

A short line under each box reading, by default:

As an Amazon Associate we earn from qualifying purchases.

Amazon’s Operating Agreement requires a statement of this kind, and advertising regulators in most countries require affiliate links to be identified. It is on by default for that reason.

16.2 Where should the disclosure appear?#

Settings → Affiliate Box → General → Affiliate disclosure, and there are three answers:

• In every box — the default, and the safest. The line travels with the link instead of depending on something further down the page.
• Once per page — drawn with the first box on the page and left off the rest. For articles that name a product every few paragraphs, where the same grey sentence five times reads as noise rather than as a notice. It still sits above every link it covers, which is the part that matters.
• Nowhere — I place it myself — only if your theme or another plugin already states it near your affiliate links.

Once per page is what makes the Button only layout usable: a bare call to action with a grey sentence under it is no longer a bare call to action, and five of them in one article is five copies of the same line.

Switching it off entirely is your decision and your responsibility. Amazon requires the disclosure; turning it off here does not remove that requirement, it moves the job to you.

Disclosure text words it yourself. Left empty, the default sentence comes back rather than nothing — a disclosure that is switched on but blank would be the worst of the three states.

A rotation is one output, not several: whichever of its boxes is on show carries the disclosure, so a page cannot lose it when the box changes.

16.3 Are outbound links marked correctly?#

Yes. Every affiliate link carries rel="nofollow noopener sponsored" and opens in a new tab.

17. Troubleshooting#

17.1 Where do I look when something does not work?#

Every problem, its cause and its fix are collected in the separate Troubleshooting Guide. It is organised by what you see on screen rather than by feature, because when something is wrong you usually do not yet know which part of the plugin is involved.

Three checks solve most reports before you need any of it:

1. Open Settings → Affiliate Box → Health. It names most misconfigurations outright, changes nothing and records nothing.
2. Look at the page while logged out, in a private window. Administrators see diagnostic notes that visitors never see.
3. Clear every cache — caching plugin, CDN, and the browser with a hard reload. After a plugin update this alone fixes most “it looks broken” reports.

17.2 Which problem is described where?#

17.3 I have an error message and want to know what it means#

The Troubleshooting Guide carries an index of every message the plugin can produce, including Amazon’s own reason codes such as invalid_client and InvalidAssociate, with what each one means and what to do about it.

17.4 What should I send when I contact support?#

The Troubleshooting Guide lists it in section 16. In short: the plugin version, whether the licence is active, the exact error text including anything in square brackets, a screenshot of the Health tab, and the shortcode you used.

Never send your Credential Secret. The length reported on the Amazon API tab is enough to diagnose a truncated one.

18. Reference tables#

18.1 All shortcodes#

18.2 Per-store shortcode attributes#

For every marketplace key in section 4.6,

asin_<key> · image_<key> · title_<key> · price_<key> · search_<key>

Example for Germany: asin_de, image_de, title_de, price_de, search_de.

18.3 Options stored in the database#

18.4 REST routes the plugin adds#

19. Legal notes#

19.1 Which Amazon images may I display?#

The Associates Operating Agreement limits which Amazon product images you may show. In general, images obtained through the Amazon API for products you are linking to are permitted; images copied from Amazon pages by other means often are not.

Fetch from Amazon fills the image field from Amazon’s API. If you paste an address yourself, do so only if you are entitled to use that image.

Your own photographs are not covered by that restriction at all — see section 11.4.

19.2 Why can I not cache prices for longer than 24 hours?#

Amazon’s Associates Program IP License allows Product Advertising Content to be stored for caching purposes for up to 24 hours. The plugin caps the cache setting at 24 hours for that reason. Caching longer violates the agreement and can get your Associates account suspended.

Do not confuse this with the rule about the price on the page: that one asks for an hourly refresh or a date/time stamp beside the price.

The plugin does not print that stamp. Version 2.22.0 did, and it was taken out again in 2.22.2. Two reasons. The rule belongs to the Product Advertising API licence you accepted, not to the plugin — and the way large publishers satisfy it is the other branch of the “or”: they refresh prices constantly and earn the exemption. Open any well-known review site and you will not find a date beside the price.

If you want to meet the rule to the letter, the honest route is the one those sites take: refresh often. Set the cache to 6 hours and let the nightly refresh run, and keep an eye on how old your prices actually are — the Refreshed column in the box list gives each one’s age at a glance, and marks anything over a week old.

19.3 Must I show the affiliate disclosure?#

Amazon’s Operating Agreement requires a statement identifying you as an Associate, and advertising regulators in most countries require affiliate links to be identified. The plugin ships with the disclosure on. See section 16.

19.4 Is this plugin affiliated with Amazon?#

No. Amazon is a trademark of Amazon.com, Inc. This plugin is not affiliated with, endorsed by, or sponsored by Amazon.

Handbook for Doozly Affiliate Box for Amazon 2.20.1. Every setting name, field label and shortcode attribute in this document is taken from the plugin source.