Affiliate Box for Amazon — Troubleshooting Guidev2.27.2

• Applies to version: 2.27.2
• Plugin settings live at: WordPress admin → Settings → Affiliate Box
• The full manual is separate: see the Handbook for how each feature works.

How to use this guide. It is organised by what you see, not by which part of the plugin is involved — when something is wrong you usually do not know which part that is. Start with the symptom index, or search this page for the exact error message you were shown; every message the plugin can produce is listed in section 15.

Every section answers one question completely on its own, so you never have to read the section before it.

1. Find your problem#

Match what you see on screen.

1.1 Symptom index#

1.2 The three checks that solve most problems#

Before working through a section, these three take a minute and resolve a large share of all reports:

1. Open Settings → Affiliate Box → Health. It names most misconfigurations directly. See section 2.
2. Look at the page while logged out, in a private window. Administrators see diagnostic notes that visitors never see, and some problems are only visible one way round.
3. Clear every cache — your caching plugin, your CDN, and the browser with a hard reload. After a plugin update this alone fixes most “it looks broken” reports.

2. Before anything else: the Health tab#

2.1 What is the Health tab and where is it?#

Settings → Affiliate Box → Health. It is the first tab, it is free, and it exists for exactly this situation.

It checks your setup for the mistakes that make no noise — a missing Tracking ID does not break a page, it only means Amazon credits purchases to nobody. Every finding says what is wrong, what it costs and where to fix it.

Health changes nothing and records nothing. It only reads what is already stored, so it is always safe to open.

2.2 What does Health check?#

Four groups:

• Geotargeting — whether it is on, how many stores can actually receive readers, where the visitor’s country comes from, and whether one can be determined at all.
• Boxes, tables and lists — which have no search term, which point at a store with no Tracking ID, and which prices are more than a week old.
• 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.
• Background jobs — whether the nightly refresh is scheduled, what the last run did, and whether /wp-json answers at all.

2.3 The Health tab takes several seconds to open#

Health asks your own site whether /wp-json/abfa/v1/country answers. Where a security plugin blocks the REST API, that request has to run into its five-second timeout before Health can report the failure — so the very screen that finds the problem is slowed down by it.

The answer is kept for ten minutes, so the next visit is immediate. Check again at the top discards it when you want to retest straight away.

If every visit is slow, the ten-minute cache is not being stored. That points at a broken object cache or a persistent cache plugin dropping transients.

2.4 Health says everything is fine but something is still wrong#

Health checks configuration, not rendering. It cannot see that your caching plugin is serving an old stylesheet, that your theme overrides a colour, or that a shortcode has a typo in it.

If Health is clean, the problem is most likely in section 5 or section 12.

3. Licence and activation#

3.1 The tabs say “Premium plan required” but I have paid#

The email address on the licence has not been confirmed yet. This is by far the most common report after a purchase.

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 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.

The plugin recognises this state. If you see a notice above the tabs reading One click left: confirm your email address, nothing is wrong with your purchase: find the email and click the button. It was sent to the address of the WordPress account you were logged in with when you activated.

If you cannot find it at all, reconnect the plugin from the plugin’s account screen to have it sent again.

3.2 The Premium features disappeared after my licence expired#

That is intended, and nothing was deleted.

Your saved boxes, tables, lists and reviews stay in the database untouched. The Premium shortcodes stop rendering for visitors — nothing broken appears in your articles — and administrators see a short note in place of the element. Everything returns exactly as it was when the licence is renewed.

3.3 I see the plugin twice in my plugin list#

The free and the Premium versions install into different folders (doozly-affiliate-box-for-amazon and doozly-affiliate-box-for-amazon-premium), so WordPress lists them as two plugins. That is deliberate: it keeps a paid installation from being overwritten by an update from the WordPress.org directory.

Normally the licensing SDK deactivates one when you activate the other, and the Premium one carries Premium after its name.

If both are active, deactivate the free one. Two active copies can leave the site loading the free stylesheet, and Premium elements then render unstyled — see 5.1.

3.4 Does the free version ever ask for a licence key?#

No. The free version is complete on its own and never asks for a key. If something is asking you for one, you are looking at the Premium version.

4. Nothing appears on the page#

4.1 The shortcode is printed as plain text in the article#

The shortcode is not registered on this site, which means the feature is not in the version you have installed.

, , and need the Premium version.

Two other causes worth ruling out:

• A typo in the shortcode name. WordPress leaves an unknown shortcode in the page as plain text.
• The editor escaped it. Pasting a shortcode into a paragraph in the block editor usually works; if it does not, use a Shortcode block.

4.2 Nothing appears where the box should be#

Check these four in order.

1. Are you logged out? Administrators see diagnostic notes that visitors do not. Check the page in a private window — if a red dashed note appears for you and nothing for visitors, that note names the reason.
2. Does the box exist? with no box of that key — or with no saved box 7 — shows an administrator note saying so and nothing to visitors.
3. Is the licence active? See 3.1.
4. Is the entry empty? A review box renders nothing at all if its Product field is empty; a product box with no title, image, price or ASIN has nothing to draw.

4.3 A red dashed note appears where the box should be#

That note is shown only to administrators; visitors see nothing at all, so your article is never defaced. The note names the reason. The three you can see are:

• This block needs the Premium version. Nothing is shown to visitors.
• <Feature> need a Premium licence.
• <Kind> ID N not found.

The first two are 3.1; the third means the ID in the shortcode does not match any saved entry — check the list on the relevant tab for the correct number.

4.4 The box disappears only for some visitors#

That is geotargeting, set to hide. Under Settings → Affiliate Box → Geotargeting → When the visitor’s store has no ASIN, the option Hide the box for that visitor does exactly that.

Change it to A search on their own store if you would rather send them somewhere useful. See section 8.

5. Something appears, but it looks wrong#

5.1 The box has no styling at all#

The stylesheet is not reaching the page. In order of likelihood:

1. A caching or optimisation plugin is serving an old copy. This is by far the most common cause after an update — plugins that combine and minify CSS often do not notice that a file’s contents changed. Purge the CSS cache, then hard-reload the browser.
2. Both plugin versions are active. The free stylesheet does not contain the Premium elements, so review boxes and comparison tables render bare. See 3.3.

How to tell them apart in ten seconds: open the page, view source, find the address of affiliate-box.css, open that address and search it for the class you are missing — for example abfa-review.

5.2 My theme overrides the box’s colours#

The plugin deliberately avoids inline styles so that themes can restyle boxes. Where a theme goes further than you want, set the plugin’s CSS custom properties rather than fighting individual rules:

: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 has its own, so one value restyles it completely:

.abfa-review { --abfa-review-accent: #0f766e; }

The plugin does not set a font family — boxes inherit your theme’s typeface on purpose, so they read as part of the article.

5.3 The product image is the wrong size#

Three settings decide this, in increasing priority:

1. Settings → Affiliate Box → Product Boxes → Image size — Small, Medium or Large (90px / 140px / 200px on desktop).
2. image_size="large" on the individual shortcode.
3. The layout: Sidebar (vertical) caps the whole box at 320px, so images are smaller there whatever you choose.

If the image is enormous and unstyled, the stylesheet is missing — see 5.1.

5.4 The discount badge or the crossed-out price does not appear#

Both need two values. Either alone shows nothing:

		

			


				
				


					
					
					
					
											

							$69.78
															$89.99
								-22%
													
					
					

						
							
							Buy on Amazon
						
					

											
As an Amazon Associate we earn from qualifying purchases.
					
				
			
		
		

On a saved box, tick Show original price + savings badge when on sale and fill in both fields. On a bestseller list, the switch is show_savings.

5.5 The review count shows as 11 instead of 11,482#

You typed the number with a thousands separator into a hand-written shortcode. Use a plain number — rating_count="11482" — and the separator is added for display in the reader’s locale.

The box editor strips separators for you; only hand-written shortcodes are affected.

5.6 The button has no text on it#

The Button text field under Settings → Affiliate Box → General was saved empty. Clear it back to blank and the shipped default (Buy on Amazon) returns, or type the wording you want.

5.7 The button’s text is invisible#

You set a dark Button color and the label vanished into it. Until 2.19.0 the stylesheet fixed that label at near-black and let only the background be changed: on the default orange that reads at 7.9:1, on a dark blue at 1.0:1 — black on near-black.

Update to 2.19.0 or later. The label’s colour is now measured against the background and set to black or white, whichever reads. Nothing needs reconfiguring; the colour you already chose simply gets a readable label.

It affected every button the plugin draws — product boxes, saved boxes, search grids, review boxes — and, from 2.20.1, the buttons in a comparison table both at rest and under the pointer. If you are on an older version and cannot update yet, pick a light button colour: anything Amazon-orange or lighter reads with the dark label.

5.8 A colour I pick does not show in the editor’s preview#

Until 2.19.0 the colour pickers wrote their value into the field but announced it to nothing, so the live models beside them sat still while you dragged. Saving showed the real result, which made the previews look broken rather than late.

Update to 2.19.0 or later. Every picker now reports its change, and the models in Product Boxes, Comparison Tables and Bestseller Lists follow as you choose.

5.9 A colour scheme made my prices hard to read#

A bestseller list’s price took the scheme’s accent, and an accent is designed to be a surface — a button, a ribbon — where the text on it is calculated. As text on a light row, Amazon orange measures 2.1:1.

Update to 2.20.0 or later. Schemes carry a second, darker shade of the accent for exactly this, and picking a scheme again sets it. The list’s own readability report will confirm it: it names every combination below about 4.5:1, and since 2.20.0 it recalculates as you choose instead of showing the last saved state.

6. Amazon API: connection and credentials#

6.1 “Test connection” fails#

First, the one that is not a credential problem at all: if you have entered no Associates Tracking ID, the test does not run. Amazon requires one on every request. The tab says so and offers a button to the Marketplaces tab — see 8.7 for what a Tracking ID looks like. Beside the test button, Tag to be used always names the ID the request would carry; (none — will fail) there is the same warning.

Otherwise, work through these five in order. Four of the five are the same mistake in different clothing.

1. Are these Creators API credentials? AWS Access Key and Secret Key do not work. Amazon retired the older Product Advertising API on 15 May 2026 and now answers it with HTTP 403. You need a Credential ID and a Credential Secret from Associates Central under Tools → Creators API.
2. Is the secret complete? A valid secret is exactly 80 characters. The Amazon API tab reports the stored length and warns when it is short — a partial selection when copying is the usual cause.
3. Is it in the right region row? A credential only works for the marketplaces of its own region. See 6.4.
4. Did you actually replace the secret? The field shows a masked placeholder and leaving it blank keeps the stored one. To replace it you must paste the whole value.
5. Is there a Tracking ID for the marketplace you are testing? The test uses that marketplace’s Associates Tracking ID; without one the request cannot be built.

The Recent API errors table and the Last raw API response (debug) panel below the test button show exactly what Amazon sent.

6.2 Amazon answers “invalid_client”#

invalid_client comes from Amazon’s token service and means the credential pair itself was rejected — before any product request is made.

Almost always one of three things:

• The secret is not the full 80 characters (check the length shown on the Amazon API tab).
• The credential is in the wrong region row.
• The values are PA-API keys, not Creators API credentials.

Re-paste the complete secret. Remember that leaving the field blank keeps the old value, so you must paste the full new one to replace it.

6.3 Amazon answers with “[InvalidAssociate]”#

The plugin appends Amazon’s own machine-readable reason in square brackets, so the message you see looks like

Some message from Amazon [InvalidAssociate]

InvalidAssociate means Amazon rejected the Associates Tracking ID sent with the request, not the credential. Check that:

• The Tracking ID on Settings → Affiliate Box → Marketplaces for that store is correct and still active in Associates Central.
• The ID belongs to the same country as the store being queried — see 8.7.

The reason code is worth keeping in any support message: Amazon can reword the sentence at any time, but the code stays searchable.

6.4 Which region do my credentials belong in?#

Amazon issues one credential per region, and a credential only works for the marketplaces of that region.

Most sites need one. The version shown next to your Credential ID in Associates Central tells you which row it belongs in.

The Health tab reports when a store has a Tracking ID but no credential covering its region.

6.5 “Amazon throttled this site. Pausing API calls.”#

Amazon refused requests because they arrived too quickly, and the plugin has deliberately paused to let the limit recover.

A fresh Creators API account gets one request per second and 8,640 per day. Without a pause, one throttled response leads straight to the next and the account never climbs out — so the plugin stops asking for a while. The message tells you how many seconds remain.

Do not press Test connection during the pause. The tab will tell you Not sent — Amazon is currently throttling this site. Testing now would only extend the pause.

To reduce how often this happens:

• Set Cache duration to 24 hours (recommended) on the Amazon API tab.
• Switch on the nightly refresh so lists are fetched once a day rather than on demand.
• Avoid pages carrying many separate live lists.

6.6 Do I even need Amazon API credentials?#

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

You do need credentials for bestseller lists, search grids, automatic filling from an ASIN or keyword, and the nightly refresh.

If a screen looks disabled and you have no credentials, that is why — it is not a licence problem.

7. Amazon API: missing or wrong product data#

7.1 Products arrive 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. The plugin’s own note explains the usual reason: 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 that titles and images would still load rather than the whole box failing.

The Last raw API response (debug) panel shows exactly what Amazon sent, which is the fastest way to tell the two apart.

Until it is resolved you can type prices in by hand — every box accepts a typed price.

7.2 Star ratings and review counts are always empty#

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 why no Amazon affiliate plugin fills these reliably.

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

Fill in the review count as well when you can: 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.

7.3 My prices are out of date#

Check these five, in order:

1. Cache duration — Settings → Affiliate Box → Amazon API. Amazon data is held for up to 24 hours by design.
2. Is the nightly refresh switched on and scheduled? The Health tab reports both. See 7.5.
3. Comparison tables are not covered by the nightly refresh. They store the product data you fetched in the admin. Use the Fetch from Amazon button inside the table.
4. Hand-written
   Buy on Amazon

   As an Amazon Associate we earn from qualifying purchases.

   shortcodes are never refreshed. Their data lives in the shortcode text. Use a saved box if you want a price maintained in one place.
5. A page cache may be serving an old copy of the article itself.

7.4 “Amazon returned nothing for that ASIN”#

You pressed Refresh on a saved box and Amazon had no answer for that product ID. The box was left exactly as it was — nothing was overwritten.

Three things to check:

• Is the ASIN correct? It is exactly 10 letters or digits.
• Does the ASIN belong to the marketplace the box is set to? An ASIN is only valid in its own store. A German ASIN on a box pointing at amazon.com refers to a different product or to nothing at all. This is the most common cause after duplicating a box and changing the product.
• Is the product still listed? Amazon removes products, and a discontinued ASIN stops answering.

7.5 The nightly refresh never runs#

WordPress cron is not a clock. It runs when somebody visits the site, and many hosts disable it entirely with DISABLE_WP_CRON. If your site is quiet overnight, or cron is switched off, the refresh simply never fires.

The Health tab reports both whether the job is scheduled and whether cron is disabled on this site.

If your host disables WP-Cron, set up a real server cron job that calls wp-cron.php — most hosts document how. Then set Preferred refresh time to an off-peak hour such as 02:00–04:00.

7.6 A box filled itself with the wrong product#

This happens after duplicating a box and then searching Amazon for a different product. Check three fields together:

• the ASIN,
• the image,
• and the marketplace.

The marketplace must match the store the ASIN came from. The plugin sets it to the store you searched in when you click a result, but if you edited fields by hand afterwards they can fall out of step.

7.7 Can I use any Amazon image I like?#

No. The Associates Operating Agreement limits which Amazon product images you may display. Images obtained through the Amazon API for products you are linking to are generally permitted; images copied from Amazon pages by other means often are not.

Fetch from Amazon fills the image field from the 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, which is one reason review boxes are built around them.

8. Geotargeting#

8.1 Geotargeting does nothing at all#

Work through these five in order.

1. Is it switched on? Settings → Affiliate Box → Geotargeting → Detect visitor country.
2. Do at least two stores have a Tracking ID? With only one there is nothing to route between, and geotargeting genuinely does nothing. The Health tab reports this as Only one store has a Tracking ID.
3. Is a country being detected? Use the test on the Geotargeting tab — it names which source answered.
4. Is an old country cached in your browser? This is the single most common reason a test appears to fail. See 8.3.
5. Is /wp-json blocked? Security plugins frequently block the WordPress REST API, and the country route lives there. The Health tab checks whether it answers.

Also worth knowing: geotargeting needs JavaScript. It runs in the reader’s browser on purpose, so that your pages stay fully cacheable. A reader with JavaScript disabled sees the box exactly as you built it, with a working affiliate link.

8.2 A VPN does not change which store I am sent to#

Almost always the 24-hour cache in your own browser, not the VPN. See 8.3.

Two other possibilities:

• Your VPN exit is not where you think. The Geotargeting tab’s own test tells you which country the plugin currently sees for you.
• You have no Tracking ID for the store of that country. Readers there are deliberately left where they are — see 8.5.

8.3 Geotargeting still shows the old country after I changed location#

The detected country is cached in the reader’s browser for 24 hours. That is deliberate — it means most page views cost no network call at all — and it is also why most geotargeting tests appear to fail.

Clear it with the button on the Geotargeting tab’s test, or in the browser console:

localStorage.removeItem('abfa_geo_v1')

Test any country without a VPN by setting it directly:

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

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

8.4 The price and stars vanish when a box changes store#

This is intended, and it protects you.

A price belongs to one store in one currency. Over a link to a different store 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.

The same reasoning applies to the star rating, which is that store’s customers’ rating.

To keep a price, fill in the per-store price — price_de and its siblings, or the Price field on a store row in the box editor. A price survives only where the box carries one for the store it is moving to.

In a comparison table, the price row falls for the whole table as soon as any column changes store. 179 € next to a gap next to $149.99 reads as an answer and is not one.

8.5 Readers are sent to a store I do not earn in#

They are not — that is precisely what the plugin refuses to do.

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

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. Moving somebody there would cost you the commission rather than move it.

If you want those readers routed, enrol in that country’s Associates programme and enter the ID under Settings → Affiliate Box → Marketplaces. The Reports tab counts exactly how many readers this affects and from which countries.

To see which stores are affected, open the Marketplaces tab. The panel at the top names how many stores your saved content links to without a Tracking ID, and every such row is marked amber with the count of items pointing at it. A row that is blank and unmarked is one nothing of yours links to — it costs you nothing to leave it empty.

8.6 Readers land on a search page instead of the product#

That is the setting A search on their own store, and it is the default.

An ASIN belongs to one Amazon store. Where you have not supplied a per-store ASIN for the reader’s country, the plugin cannot know the product’s ID there — so it sends them to a search for the product on their own Amazon, under your Tracking ID for that country. Anything they buy in the next 24 hours counts.

To send them to the product itself instead, fill in asin_de (and its siblings) for the stores that matter. To change the behaviour, use Settings → Affiliate Box → Geotargeting → When the visitor’s store has no ASIN.

A box with no search term falls back to leaving the link alone, whatever you choose — a search for nothing is an empty page.

8.7 “Check this Tracking ID” warning on the Marketplaces tab#

Amazon Tracking IDs end in a country-specific suffix. The plugin compares the suffix of the ID you entered against the store it is filed under and warns when they disagree:

Check this Tracking ID. IDs for this store normally end in -21, but this one ends in -20.

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, and an ID from one country’s programme usually earns nothing on another country’s store.

8.8 Does geotargeting work with page caching?#

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

8.9 Is geotargeting a privacy or GDPR problem?#

On the default path no third party is involved at all. The reader’s browser asks your own site, and your server reads a country that arrived with the request — your site already received that request, so answering a question about it tells nobody anything new.

The one thing to decide is the external lookup: Settings → Affiliate Box → Geotargeting → If the server cannot say → Ask a free external service instead. That sends the reader’s IP address outside your site, and it is the switch a European site usually wants off.

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

8.10 “This request carried no country”#

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 country header only on public traffic, not on admin requests.

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

9. Comparison tables, bestseller lists and search grids#

9.1 My comparison table shows empty columns#

A column is drawn only when it has something to show. Check that the slot has at least a title or an ASIN — a column with only a feature value and no product is skipped.

If the whole table is missing, see 4.2.

9.2 My bestseller list is empty#

In order:

1. Are Amazon API credentials configured and working? Bestseller lists are fetched live and cannot work without them. Run Test connection on the Amazon API tab.
2. Is the browse node valid for that marketplace? Category IDs differ per store — a node from amazon.com does not exist on amazon.de.
3. Do the keywords return anything? Try them in Amazon’s own search first.
4. Is the site being throttled? See 6.5.
5. Is there a Tracking ID for that marketplace? Without one the request cannot be built.

9.3 My comparison table’s prices are stale#

Comparison tables are not covered by the nightly refresh. They store the product data you fetched in the admin and do not re-query Amazon on page load.

Open the table and press Fetch from Amazon.

9.4 Bestseller lists and search grids ignore geotargeting#

They do, and they cannot do otherwise.

Their products are fetched live from Amazon for one store. The bestsellers of amazon.de are different products from those of amazon.com — different ASINs, in a different order. There is nothing to rewrite: the list would have to be fetched again for every reader’s country, and 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, documented rather than hidden.

Product boxes, saved boxes, comparison tables and review boxes are geotargeted.

9.5 Feature bullets bury the price in my bestseller grid#

Switch them off. Show feature bullets is off by default for that reason: Amazon’s bullets run to several lines each, and three under every card push the price and the button out of sight.

Switch them on only for a single-column list layout, where there is room to read them.

10. Review boxes#

10.1 “Add a photo” does nothing#

The button opens the WordPress media library, which the plugin loads only on its own settings page.

• Reload the settings page. A JavaScript error from another plugin earlier in the page can stop the media library from initialising.
• Check the browser console for errors from other plugins.
• Confirm you are on Settings → Affiliate Box → Reviews and not on a copy of the screen inside another plugin’s interface.

10.2 A criterion I typed does not appear in the box#

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

The row stays saved in the editor — nothing is lost — it is simply not drawn. Type a score next to it and it appears, bar and all.

The live preview beside the form always shows exactly what the reader will get.

10.3 “Photo beside the text” stays stacked#

Two conditions must both be met. The box falls back to the stacked layout until they are, rather than showing a hole while you are still typing:

1. At least one photo. A two-column layout with an empty picture column is a void, not a narrower layout.
2. A wide enough column — 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 width.

10.4 I picked a background colour and the text is hard to read#

The box works out the text colour from the background, so it is never black on black — but no text colour reaches a comfortable contrast on a mid tone. A medium grey, a medium blue or a medium green cannot carry body text in any colour at all; that is a property of the colour, not a setting.

The editor shows the measured contrast under the Background colour field. Below 4.5:1 it says so outright. Move the colour nearer to white or nearer to black and the number rises.

Everything else follows automatically: on a dark card the text turns light, the green and red of the pros and cons are lifted, and the price is brightened from Amazon’s red, which on a dark background would be almost invisible.

10.5 What happens to my scores if I change the scale?#

They are converted, not discarded. 9 out of 10 becomes 4.5 out of 5, and 4.5 out of 5 becomes 9 out of 10 again if you change back.

This was not always so. Before version 2.6.3 every score above the new scale was simply dropped, so switching from 10 to 5 could turn a published verdict of 8.5 into 4.0 without any warning. If you changed a scale on an older version, check the review’s scores.

The preview beside the form shows the converted numbers before you save.

10.6 My score shows a different number from the one I typed#

You have criteria filled in and the Overall score field empty, so the criteria are being averaged.

• To use your own number, type it into Overall score — a typed value always wins.
• To use the average, leave it empty.

The editor shows the running average as you type so the two never surprise you.

10.7 Why does my review box show no Amazon star rating?#

By design. A review box shows your score and never Amazon’s.

A large number sitting beside an Amazon price and an Amazon button reads as Amazon’s rating unless something says whose it is. That is why the score always carries a label — Our score by default, freely editable — and why Amazon’s own stars do not appear at all. One box, one verdict, one voice.

The stars you can switch on in a review box are drawn from your score, rescaled to five.

10.8 The review box shows no button, price or disclosure#

The ASIN field is empty. Without one there is nowhere to send anybody, so the whole footer is left out.

That is a perfectly good review — fill in the ASIN only if you want the affiliate button.

10.9 My review photos disappeared after moving the site#

Photos are stored as media library attachments, which is exactly what makes them survive a move — provided the media library moved with the site.

If the pictures are gone from Media → Library as well, they were not migrated. Restore them, and the review boxes will show them again. If an attachment was deleted outright, the review simply leaves that picture out rather than showing a broken image.

11. Reports#

11.1 Reports shows no numbers at all#

Four things to check:

1. Is it switched on? Settings → Affiliate Box → Reports → Count views and clicks. It is off until you tick it.
2. Has an admin page been loaded since the update? The database table is created on the first admin page load after updating.
3. Are you looking at your own visits? Reports filters obvious machine traffic, and counting happens in the reader’s browser. View the page while logged out, in a private window.
4. Is the element counted at all? Only saved boxes, comparison tables, reviews and boxes inside posts carry a counting identifier.

11.2 Clicks are not being counted#

Clicks are sent in a way that does not hold the reader up, so you will not see an ordinary request in the browser’s network panel. Filter it for abfa/v1/stats.

Note that controls inside a box do not count — the thumbnails of a review box gallery, for instance. Only clicks that lead out to Amazon are counted, which is what makes the click rate meaningful.

If views are counted but clicks are not, or clicks appear in the box table but the country table stays at zero, suspect a stale combined JavaScript file before anything else — see 12.6.

11.3 A comparison table counts one view, not four#

Correct. A table is one unit however many columns it has. A page with one table and two boxes reports three views, not six.

11.4 What does “Left behind — no Tracking ID for their store” mean?#

It is the most valuable number on the tab: how often a box was shown to somebody whose Amazon store you have no Tracking ID for.

Those readers were deliberately not moved, because Amazon credits a sale to the ID of the store the purchase happens in and you have none there. A purchase from them is credited to nobody.

The countries are listed beside the figure. Enrol in the Associates programme of the country at the top of that list and the number turns into revenue.

11.5 Is Reports a privacy problem?#

Only sums are stored: a day, which box, a country, a routing mode, a view count and a click count. Specifically not stored — no IP address, no identifier, no session, and no timestamp finer than the day.

Numbers older than about 400 days are removed automatically, and the whole table is dropped when the plugin is uninstalled.

12. Speed, caching and conflicts#

12.1 Does the plugin slow my site down?#

It loads its stylesheet and scripts only on pages that actually use a shortcode, and Amazon responses are cached for up to 24 hours, so a normal page view usually makes no request to Amazon at all.

The two things that do cost time are live elements — bestseller lists and search grids — on a page whose cache has expired. Set Cache duration to 24 hours and switch on the nightly refresh.

12.2 A caching plugin is breaking the boxes#

Two distinct symptoms:

• No styling at all → the CSS cache is stale. See 5.1.
• Old prices or old content → the page cache is serving an old copy of the article. Purge it.

Geotargeting itself is safe with page caching: the HTML is identical for everyone and the rewriting happens in the browser afterwards.

12.3 Another affiliate plugin or a link cloaker interferes#

Link cloakers rewrite outbound links, which can strip the Tracking ID or break geotargeting — the geotargeter rewrites the links in the box, and a cloaker that rewrites them again afterwards wins.

Exclude the plugin’s boxes from the cloaker, or exclude Amazon links from it altogether. The plugin’s links already carry rel="nofollow noopener sponsored", which is what a cloaker is usually there to add.

12.4 The geotargeting script does not run#

It needs JavaScript. Beyond that, the usual causes are a JavaScript error from another plugin stopping all scripts on the page, or an optimiser deferring or combining scripts in a way that breaks them. Check the browser console for errors, and try switching off script combining.

Without the script, boxes show the store you built them for, with a working affiliate link — the page is never broken, only unlocalised.

12.5 /wp-json is blocked on my site#

Security plugins often block the WordPress REST API. The plugin uses two routes:

With the first blocked, every country lookup falls back to the external service — or fails entirely, if you switched that off. With the second blocked, Reports records nothing.

The Health tab checks whether /wp-json answers at all.

12.6 After an update the plugin still behaves like the old version#

A speed plugin that combines JavaScript into one file — SiteGround Speed Optimizer, WP Rocket, LiteSpeed Cache, Autoptimize — stores that combined file under a name of its own. The name does not contain the plugin’s version number, so updating the plugin does not replace it. Your visitors, and you, keep running the old code until that cache is cleared.

Page caches usually clear themselves on an update. File-combining caches often do not.

The symptom is a fix that is listed in the changelog and demonstrably present in the files on the server, yet does nothing on the site. It cost an afternoon of testing here before it was found, so it is worth ruling out early.

To clear it: purge the page cache and, separately, the file or JavaScript cache in your speed plugin’s own settings — they are two different buttons. Then reload the article with Ctrl+F5.

To confirm what is actually being served, open the article, press F12, and paste this into the Console:

(async()=>{for(const s of document.querySelectorAll('script[src]')){try{const t=await (await fetch(s.src)).text();if(t.indexOf('data-abfa-unit')>-1){console.log(s.src.slice(-60));}}catch(e){}}console.log('done');})()

It prints the file that carries the plugin’s counting code. If nothing is printed, the script has been combined into a bundle or inlined — which is exactly the case where this section applies.

13. Moving a site, staging and several sites#

13.1 I moved the site and the licence stopped working#

Licences are tied to a site address. After moving to a new domain, reactivate the licence from the plugin’s own account screen in the WordPress admin.

Everything else survives a move: settings, Tracking IDs, saved boxes, tables, lists and reviews all live in the WordPress database and move with it.

13.2 Can I use the plugin on a staging site?#

Yes, but the licence is per site. If activating on staging uses up your only seat, deactivate it there before going live, or use the free version on staging — the free features behave identically and the Premium ones simply do not render.

13.3 Do my Amazon API credentials move with the site?#

They are stored in the WordPress database, so they move with a database copy. On a staging site that means staging will make API calls against your Amazon account, which counts towards the same daily allowance.

If that matters, clear the credentials on staging.

13.4 Review box photos after a migration#

They survive, because photos are stored as media library attachments rather than as web addresses — that is exactly why. Provided the media library was migrated, the pictures reappear. See 10.9.

14. Uninstalling and your data#

14.1 I deleted the plugin and my boxes are gone#

Uninstalling removes everything the plugin created: settings, Tracking IDs, API credentials, saved boxes, comparison tables, bestseller lists, review boxes, cached Amazon responses, scheduled jobs and the Reports table.

This is intentional and it is what WordPress asks a plugin to do — a plugin that leaves rows behind pollutes the database of everyone who ever tried it.

Deactivating deletes nothing. If you only want to switch the plugin off, or you are troubleshooting, deactivate rather than delete.

There is no way to recover deleted data other than a database backup.

14.2 How do I keep my content but stop using the plugin?#

Deactivate it and leave it installed. Nothing is deleted, and the shortcodes stop rendering — they will show as plain text in your articles, so remove them from posts first if that matters.

14.3 What is left behind if I deactivate?#

Everything. Deactivation only stops the plugin from running.

15. Error message index#

Every message the plugin itself can produce, with what it means. Amazon’s own messages are passed through as they arrive, with Amazon’s reason code appended in square brackets.

15.1 Amazon API errors#

15.2 Amazon’s own reason codes#

15.3 Messages on the settings screens#

15.4 Routing outcomes in Reports#

These are not errors. They are what happened to each reader.

16. What to send to support#

16.1 What information makes a support request answerable in one reply?#

Sending these six things turns most tickets into a single answer:

1. The plugin version, from Plugins or the top of the settings page.
2. Free or Premium, and whether the licence shows as active.
3. The exact error message, copied as text — including anything in square brackets such as [InvalidAssociate]. A screenshot of an error is harder to search than the text of it.
4. A screenshot of the Health tab. It answers a dozen questions at once.
5. The shortcode you used, copied exactly.
6. A link to a page where the problem is visible, if there is one.

16.2 Where do I find the version number?#

Plugins → Installed Plugins, next to Doozly Affiliate Box for Amazon. It is also shown at the top right of every settings tab of the plugin.

16.3 What should I send for an Amazon API problem?#

In addition to the six above:

• The contents of the Recent API errors table on the Amazon API tab.
• The Last raw API response (debug) panel below it — that is Amazon’s own answer and usually contains the reason outright.
• Which region row your credential is in, and the stored secret length the tab reports. Never send the secret itself.

16.4 What should I never send?#

Never send your Credential Secret, and never paste it into a support form, a forum or a chat. The length reported on the Amazon API tab is enough to diagnose a truncated secret.

Tracking IDs are not secret — they appear in every affiliate link on your site — so those are fine to include.

Troubleshooting guide for Doozly Affiliate Box for Amazon 2.20.1. Every error message and setting name in this document is taken from the plugin source.