Affiliate Link Auto-Tag: On Every Publish, the Rule

What the auto-tag rule is

P-tag-rule: every review-publish deploy runs an affiliate-link-rewrite pass. The pass scans every review frontmatter + body for amazon.com (and other canonical-Amazon) URLs and rewrites them to https://amzn.to/<agenticbotsit-20-tag>.

The pass is part of the build, not a one-off. It’s idempotent, run-at-deploy, audit-visible — meaning re-running on the same content yields the same output (no double-tag, no drift), the rewrite happens automatically at ship (never as a manual click), and every deploy emits a single line of numbers that the operator reads to confirm the pass ran. Without all three, the convention erodes: manual passes drift, non-idempotent passes duplicate, invisible passes fail silently. The convention exists because ABS publishes ~"30" review posts a week and each has at least one raw Amazon URL in it — hand-tagging "30" inputs a week is "15" minutes of operator time reclaimed by an automated pass. The math compounds.

Where it lives

The build script affiliate-link-tag.py (or similar — see package.json) runs as a pre-build or post-content-resolve step. The output:

affiliate-link-tag: scanned N review files, tagged M Amazon links in K files.
affiliate-link-tag: idempotence verified.

The “tagged M” number is the count of rewrites the pass performed. A non-zero count is normal — review files contain raw Amazon links that get tagged at deploy; "0" counts are normal for guide-only batches. The pass is wired as a build hook so neither operator nor agent has to invoke it. The script is versioned, reviewed, tested, pure-code (no runtime services), stdout-only audit.

The rewrite rules

Three URL shapes get rewritten:

1. Canonical Amazon: https://www.amazon.com/dp/<ASIN> → https://amzn.to/<agenticbotsit-20>
2. Amazon shortlink: https://amzn.com/<ASIN> → https://amzn.to/<agenticbotsit-20>
3. amzn.to without tag: https://amzn.to/<existing-short> → https://amzn.to/<agenticbotsit-20> (only if existing tag is missing or non-canonical)

What does NOT get rewritten:

• Already-tagged amzn.to/<agenticbotsit-20>. The pass detects and skips idempotently. Re-running the pass on the same file produces no double-tag.
• Internal ABS review links. /reviews/<slug> in markdown body stays as-is.
• External non-Amazon links. https://example.com stays https://example.com.
• Image src URLs. The image stays as-is; the affiliate tag applies to review body links only.

A note on rule 3: it only fires when the existing amzn.to carries no tag or a non-canonical one. This protects against clobbering an operator-introduced tag — but the botsitter-review input convention forbids operator-introduced tags, so rule 3 is a safety net, never the load-bearing path. The “not rewritten” list is also a contract: external non-Amazon retailer URLs (Best Buy, Target, Walmart) pass through untouched by design. New retailers get a new P-tag-rule, not an expansion of this one.

The “tag” tag in frontmatter

Each review file can declare an affiliate boolean in frontmatter:

affiliate: true   # This post contains affiliate links; show disclosure
affiliate: false  # This post does not contain affiliate links

The auto-tag pass uses this to decide whether to log a “tagged M” line. False-affiliate review files with Amazon links are flagged as warnings — usually a content bug. The field is also load-bearing for the disclosure component: affiliate: true renders the disclosure block, affiliate: false does not. Changing the boolean and re-running the build rewires the disclosure.

The convention of <agenticbotsit-20>

The tag suffix -20 is the Amazon Associates tag-track suffix (the “Associates ID” comes after the tag-track identifier). Every amzn.to that resolves through this tag-track credits ABS’s affiliate account with the sale.

The specific tag string is operator-configured; today’s value is agenticbotsit-20. To change:

# Edit /opt/data/.env (per the botsitter-review config)
AFFILIATE_TAG="agenticbotsit-NN"

Changing the tag mid-year is fine; Amazon’s cookie is "24" hours, so a reader clicking an old-tagged link still credits. But the canonical content is the new tag — operators reading the corpus a quarter from now will see the legacy tag in old posts and the new tag in new posts, and that’s expected. The env var path (/opt/data/.env) is the single edit point; changing the tag in the build script directly is forbidden by the P-tag-rule — one source of truth, and it’s the env var.

The audit visibility

Each build emits a per-deploy line:

affiliate-link-tag: scanned 37 review files, tagged 56 Amazon links in 31 files.

The "37" / "56" / "31" pattern is operator-readable. Numbers should be:

• Scanned: equal to total review files.
• Tagged: ~"1.5" per review file (most reviews have 1 product; some have "2-3").
• Files with tags: ~"85%" of reviews.

A zero-tag run is suspicious for review-heavy batches; investigate before pushing. Specifically, was the batch guide-only (in which case "0" is expected) or did the env var drift (in which case the operator should redo the deploy with the corrected env)? The audit line is a single stdout emission, no log file or external service. Replay the build and the line matches because the source is deterministic and the pass is idempotent.

The verify at three points

Three places to verify:

1. Pre-build verify. Run npm run build locally; the tagger outputs the count. Check vs prior builds.
2. Post-build verify. grep "amzn.to/agenticbotsit-20" dist/reviews/<slug>/index.html | wc -l should be > "0" for any review file with Amazon links.
3. Live verify. curl https://agenticbotsitter.com/reviews/<slug>/ | grep amzn.to should show the amzn.to URLs. Compare the rendered URL — the amzn.to → amazon.com redirect should preserve the tag.

The three points form a chain: local (sanity), dist (correctness), live (delivery). Missing any one means partial verification — and regressions slip through partial verification. The pre-build check is fast; the post-build check confirms the rewrite made it to the rendered HTML; the live check confirms deploy propagation. A fresh deploy isn’t live until the edge cache is purged — ABS uses Cloudflare Tunnel + rsync, so rsync-then-purge serves stale HTML, purge-then-rsync serves the new HTML immediately.

The failure shapes

Failure	Detection	Fix
Affiliate tag string drift	Build emits 0 tags	Re-set AFFILIATE_TAG in env
Build skips the pass	No affiliate-link-tag: line in output	Verify package.json hook
Double-tagging	Same URL appears twice with the tag	Reduce — pass is now idempotent
Tagger misses /reviews/<slug>	grep count < expected on rendered	Investigate; could be a slug mismatch

Each row is an observed failure mode. Tag drift: env restored from old backup, regex matches the current tag and finds none. Build-skip: a package.json refactor drops the hook during rebase; the audit line disappears, which is the alarm. Double-tagging was a real failure shape in early versions — the table keeps it on record so a contributor doesn’t reintroduce the bug. Slug-mismatch is more content-shape than pipeline: a /reviews/<slug> the tagger didn’t see renders with fewer links than expected. None require rolling back the deploy — they require a fix and a fresh build.

What NOT to do

• Don’t manually hand-tag amazon.com URLs in markdown. The pass handles it; manual tags drift.

• Don’t commit a review file without running the build. The tag pass is the gate.

• Don’t change the tag string without bumping the env config everywhere. The convention is one.

• Don’t trust a "tagged 0" line without investigating.

• Don’t trust a tagged 0 line without investigating.

These are the four ways the convention has been subverted. Manual tags are the most common: an operator types a tag into a URL in a hurry, ships, and the next build’s idempotence check refuses to rewrite. Trusting a zero-tag line on a review-heavy batch is the silent bug — investigate every "tagged 0" before pushing.

The work the tag pass saves is real: ~30 seconds of manual tagging per review file, ~15 minutes / week at today’s volume. The convention earns its keep quietly.

Sources

• ABS live reviews: Botsitter Reviews
• Amazon Associates linking
• ABS companion: Botsitter-Review Affiliate Link Convention
• ABS companion: Review Publishing Pipeline

Last verified: 2026-07-14. Today’s live review files: scanned 37 / tagged 56 / in 31 files — pattern holds.