Goal: Amazon Client Integration

This project is to prepare for a first, extremely simplified capability for users of the Arda System to provide an Amazon URL and have the system create an Item from it. The project is responsible for the preparation steps; the actual user interaction surface and workflow will be part of a follow-up project by another team member.

The project will deliver:

1. A modification to the Item Module (Endpoint, Service, Persistence) to allow persisting Amazon Image URLs instead of only allowing paths that refer to self-hosted images. See the image upload project if more information is needed. (operations repository)
2. A Route in the BFF (Server) section of arda-frontend-app and associated supporting utilities that given an Amazon ASIN or an Amazon product page URL, it will query Amazon’s APIs to retrieve all the associated product information and the full Amazon associates product URL with Arda’s Amazon affiliate information. 2.1. Amazon Affiliates information should be retrieved from:
   • A configuration file or constants file if the information is public.
   • A Secret only known to the BFF and installed by the Deployment process from a source in 1Password (it can be set in a GH Organizational Secret if needed).

Tracking

• Linear (this project): PDEV-446 — Amazon Creator API Integration (technical subticket under umbrella PDEV-445 — Create Item from Amazon URL).
• Linear (deferred sibling, out of scope): PDEV-429 — Order From Amazon: one-click cart link from Order Queue.
• Linear (e2e baseline, separate workstream): PDEV-439 — Flaky e2e auth setup + two @full-regression failures on main.

Repositories

Repository	Role	Planned Changes
arda-frontend-app	Primary implementation	New BFF Route Handler under src/app/api/amazon/... with route logic in src/server/routes/amazon/; Creators API client wrapping amazon-creators-api@1.2.2 (Apache-2.0 npm wrapper around Amazon’s official Node.js SDK; pinned exactly) under src/server/lib/amazon/; pure ASIN extractor + affiliate-URL builder + types + MARKETPLACE constant under src/lib/shared/amazon/; unit tests for each; addition of AMAZON_CREATORS_CREDENTIAL_ID, AMAZON_CREATORS_CREDENTIAL_SECRET, AMAZON_CREATORS_CREDENTIAL_VERSION, AMAZON_ASSOCIATE_TAG to src/lib/env.ts and to the `env
operations	Minimal change	Branch service/ItemPrinter.signImageUrl on host: sign URLs whose host matches the configured CDN as today, pass through any other URL unchanged. Roughly 2 files (ItemPrinter.kt and a unit-test file). The save-time validator (persistence/ItemValidator.kt) already accepts non-CDN URLs and is explicitly tested for that policy — no validator change is needed.
infrastructure	Required	Adds the four Amazon Creators API values to each partition’s deployment, following the existing 1Password → AWS Secrets Manager → Amplify env-var pipeline (the same path used for ARDA_API_KEY, HUBSPOT_*, etc.). Concrete file edits (per context-exploration.md § “IaC Compliance per Partition”): (a) src/main/cfn/partitionSecrets.cfn.yaml — add AmazonCreatorsApi parameter + multi-field AWS::SecretsManager::Secret resource named ${Infrastructure}-${Partition}-AmazonCreatorsApi (JSON SecretString with credentialId, credentialSecret, version, associateTag) + ARN output. (b) src/main/cfn/amplify.cfn.yaml — four new entries in the EnvironmentVariables block, each using field-extract syntax against the cross-stack secret ARN (applies only to the full-IaC partition Alpha001:demo). (c) amm.sh — op read four fields per partition vault, pass as CFN parameter override; for partial-IaC partitions (Alpha002:dev, Alpha002:stage, Alpha001:prod) extend the existing aws amplify update-app --environment-variables jq-merge block to also inject the four AMAZON_* values fetched from the partition’s Secrets Manager secret. The Alpha001:prod region anomaly (Amplify app in us-east-2) is handled by the existing per-partition region selection in .github/workflows/amm.yml; no new cross-region logic is needed.
documentation	Required	New BFF-route reference page at current-system/functional/reference-data/item/amazon-bff-api.md. New operator runbook at process/sre/runbooks/amazon-creators-api-onboarding.md describing the Account Holder steps to register, create an Application, populate 1Password vaults, and configure each Amplify app’s env vars. Inherited supporting material in this directory’s context-exploration.md. Standard CHANGELOG entry.

api-proxy is not part of this project.

Success Criteria

1. Operations: non-CDN image URLs round-trip cleanly. Saving an Item with an Amazon-hosted imageUrl continues to succeed (already true today); at print time, the URL signer signs CDN-host URLs as today and passes through non-CDN URLs unchanged. Unit tests cover both branches.
2. BFF route accepts Amazon inputs and returns the v1 DTO. A signed-in tenant user can POST a bare ASIN or a canonical Amazon product URL (with marketing slug and arbitrary query params) to the new BFF route and receive a JSON response in the v1 DTO shape: name, image (large URL plus width and height), price (current Buy Box: amount + currency), unitCount (integer pack count if Amazon exposes one), unit (free-text size / unit-of-measure string if Amazon exposes one), upc, asin, and productUrl (Amazon’s detailPageURL verbatim when present — see Constraint 3). The route is a faithful proxy/adaptor for Amazon’s GetItems response and does not impose stricter field-presence requirements than Amazon does. The fields name, image, price, and productUrl are nullable — missing fields are returned as null; unitCount, unit, and upc are also nullable as previously noted. The route signals a sparse upstream response with HTTP 206 when any of name, image, price, or productUrl is null; it returns HTTP 200 when all four are populated. Exact field names, types, and the 200/206 rule are settled in specification.md.
3. BFF route rejects unsupported inputs with structured error codes. Short links (a.co, amzn.to), unparseable URLs, non-US Amazon hosts (e.g. amazon.co.uk), Amazon throttling responses, and per-ASIN errors each map to a stable error code with a human-readable default message — see Constraint 7 for the code set.
4. ASIN extraction is encapsulated in a single utility module under the Shared layer (src/lib/shared/amazon/), so the recognised URL-form set can be expanded later without changing the BFF route or its callers.
5. Configuration is split as documented in Constraint 12. The four runtime values (AMAZON_CREATORS_CREDENTIAL_ID, AMAZON_CREATORS_CREDENTIAL_SECRET, AMAZON_CREATORS_CREDENTIAL_VERSION, AMAZON_ASSOCIATE_TAG) are sourced from 1Password (vaults Arda-DemoOAM, Arda-DevOAM, Arda-StageOAM, Arda-ProdOAM) and delivered to each Amplify app as branch environment variables; they are aggregated through src/lib/env.ts. The marketplace string is a source constant. No secret material is committed.
6. A new current-system reference page at documentation/src/content/docs/current-system/functional/reference-data/item/amazon-bff-api.md describes the BFF route’s purpose, input shape, output shape, error codes, and configuration touchpoints, so the follow-up project’s implementor can integrate without re-reading the BFF source.
7. Inherited context (Creators API selection, IP License image-rehosting prohibition, IP License caching rule, IP License ASIN-persistence permission, affiliate-tag canonicalisation rule, US-only marketplace scope, URL-form parsing reference, third-party-scraper out-of-scope analysis) lives in context-exploration.md in this directory and is grounded in original sources (Amazon Associates legal documents with consultation dates, court rulings with case citations). Technical specifics of the Creators API (request body shape, response field paths, error codes, throttling parameters) are deferred to specification.md and confirmed against the live Creators API at implementation time. v1’s decision audit trail is self-contained and does not depend on the parked project remaining accessible.
8. Pre-push checks pass locally: make check in arda-frontend-app (lint + typecheck + build + Jest unit tests + Chromium e2e), ./gradlew check in operations, make pr-checks in documentation.

Context

This project is the first preparation step for a future user-facing “Create Item from Amazon URL” workflow. The user-facing surface (item-creation form pre-fill, “Import from Amazon” affordance, error UX, persistence of Amazon-derived data into Item and ItemSupply) is deliberately out of scope and will be delivered by another team member in a follow-up project. v1 lays the infrastructure: the operations-side image-URL fix and a BFF route that the follow-up project’s SPA can call.

A predecessor exploration was conducted on this project between 2026-04-29 and 2026-05-06 under the name Amazon Client Integration (Extended) and is parked under roadmap/on-hold/amazon-client-integration-extended/. The decisions and analyses that survive into v1 — Amazon API selection (Creators API, not the deprecated PA-API 5), the IP License image-rehosting prohibition, the IP License caching rule, the affiliate-tag canonicalisation rule, the US-only marketplace scope, the third-party-scraper out-of-scope position, the URL-form parsing reference — are recorded in context-exploration.md in this directory with citations to original sources (Amazon Associates legal documents, court rulings). Technical specifics of the Creators API are deferred to specification.md and confirmed at implementation time against the live API. v1’s decision audit trail is therefore self-contained and does not depend on the parked project’s continued availability.

Scope

In Scope

• Operations (operations repository). A small change to service/ItemPrinter.kt (branch signImageUrl on host: sign CDN-host URLs as today, pass through any other URL unchanged) plus the corresponding unit-test additions. The save-time validator (persistence/ItemValidator.kt) requires no change.

• BFF route (arda-frontend-app). A new server-only Route Handler under src/app/api/amazon/... that accepts an ASIN or canonical Amazon product URL, calls Amazon’s Creators API to retrieve the data needed to populate a stable Arda-side DTO, and returns that DTO. The DTO is the v1 contract for follow-up consumers — its shape is fixed regardless of how Amazon’s upstream response shape evolves. The Creators API request asks for exactly the resources that map to the DTO fields — nothing more, nothing less. v1 DTO fields:

  • name — the listing’s display title.
  • image — the primary image at “Large” size: the full URL of the Amazon-hosted image plus width and height. Image URL passed through unchanged (no rehosting, no signing).
  • price — the current Buy Box price: amount + currency (USD for the US-only v1). Future expansion (not v1): a follow-up may extend the DTO to carry “all listings” (Buy Box plus other available offers); the v1 single-listing shape should be designed to accept that as an additive change.
  • unitCount — the integer pack count when Amazon exposes one (e.g. 12 for a 12-pack); nullable.
  • unit — the free-text size / unit-of-measure string Amazon exposes alongside the listing (e.g. "32 oz", "Large"); nullable. Mapping to Arda’s structured Quantity.Value.unit (drawn from operations’ lookup-units) is the follow-up project’s concern.
  • upc — Universal Product Code when Amazon returns one; nullable.
  • asin — the canonical Amazon identifier.
  • productUrl — Amazon’s detailPageURL verbatim from the getItems response when present (already carries Arda’s partnerTag plus Amazon’s tracking parameters; stripping or rebuilding it breaks attribution per Amazon’s API Rates guidance — see Constraint 3); null when Amazon’s response omits the field.

  The DTO is a faithful proxy/adaptor of Amazon’s response: name, image, price, and productUrl are nullable — the route does not reject sparse Amazon responses but passes null for absent fields. unitCount, unit, and upc are also nullable. The route returns HTTP 206 when any of name, image, price, or productUrl is null; HTTP 200 when all four are populated.

  Exact field names, types, nullability semantics, and the upstream-to-DTO mapping are settled in specification.md once verified against the live Creators API.

• ASIN-from-URL extraction utility in the Shared layer (src/lib/shared/amazon/), accepting bare ASINs and the canonical URL forms (/dp/, /<slug>/dp/, /gp/product/, /gp/aw/d/) with arbitrary query params stripped.

• Affiliate-URL builder utility in the Shared layer that emits https://www.amazon.com/dp/<ASIN>?tag=<assoc-tag> from an ASIN. v1 does not use this for the BFF response (we pass through Amazon’s detailPageURL); the builder is provided as a Shared utility for future use cases (notably PDEV-429 cart-link work) where no Creators API response is available.

• Creators API client under src/server/lib/amazon/ based on the amazon-creators-api npm package (Apache-2.0 wrapper around Amazon’s official Node.js SDK; pinned to version 1.2.2). The client wraps the SDK’s TypedDefaultApi.getItems to expose a typed item-lookup method whose signature accepts a list of ASINs (so a future bulk path is additive, even though v1 only ever calls with one ASIN). The SDK handles OAuth 2.0 client_credentials token acquisition, caching, automatic refresh, and v2 Cognito vs v3 LWA endpoint routing transparently.

• Tenant-scoped JWT verification on the BFF route, identical to other /api/arda/* routes.

• Public Associate Tag in server-side configuration; private credentials in deployment-injected secrets (1Password or GH org secret).

• New documentation page at current-system/functional/reference-data/item/amazon-bff-api.md describing the BFF route surface for follow-up implementors.

• context-exploration.md in this directory — self-contained context for v1 decisions, citing original sources (Amazon Associates legal documents, court rulings).

• Tests at the unit level for: ASIN extractor, affiliate-URL builder, Creators API client (mocked HTTP), the BFF route (mocked client), and the operations signer change.

Out of Scope

• User-facing UI for “Create Item from Amazon” — built by the follow-up project.
• Item creation flow (mapping Creators API response onto ItemInput and POSTing to the operations item endpoint) — follow-up project.
• primarySupply / ASIN persistence on Items — follow-up project decides where ASIN, supplier name, supplier URL, price, etc. are stored on the Item.
• 24-hour refresh / staleness of Amazon-sourced fields — follow-up project (the IP License’s caching constraint is on whoever stores the URL; v1 does not store).
• Read-only Amazon-managed fields in the UI — follow-up project.
• Order From Amazon (cart-link generation from the order queue) — tracked separately as PDEV-429.
• Short-link redirect-following (a.co, amzn.to) — rejected with a clear error in v1; the follow-up project may add it once the share of real-world short-link inputs is known.
• Non-US Amazon marketplaces (amazon.co.uk, amazon.de, etc.) — rejected with a clear error. See Constraint 6 for the unblock conditions.
• Bulk import (multiple ASINs in one request) — out of scope for v1; the BFF client interface still takes a list to leave room for later batching.
• All-listings pricing. v1 returns the current Buy Box price only. A future enhancement may extend the DTO to carry all available listings (Buy Box plus other offers); v1 chooses field shapes that allow this as an additive change rather than a breaking one.
• Third-party scraper APIs (Rainforest, ScraperAPI, Bright Data, etc.) — out of scope. Rationale in context-exploration.md.
• ESLint enforcement of layer rules — out of scope. The follow-up project may introduce it when it adds SPA code.
• Amplify preview gate — Amplify still builds, but no user-facing surface to demo in v1.

Constraints

1. The BFF code should all be in the server or lib areas of the code in arda-frontend-app/src.

   • api for BFF route declarations
   • server for the bff code.
   • server/lib for bff utilities
   • lib/shared for utilities that can be used by the bff and the spa.

2. Amazon credentials are BFF-only. The Credential ID and Secret pair never appear in any module reachable from SPA code. Tokens (~1 h TTL) are cached in BFF-process memory.

3. Affiliate-tagged product URL is taken verbatim from Amazon’s response. The DTO’s productUrl field is the detailPageURL value Amazon returns from getItems, passed through unchanged. Amazon’s verbatim guidance from the API Rates page (https://affiliate-program.amazon.com/creatorsapi/docs/en-us/concepts/api-rates): “You are using the links provided by Creators API when linking back to Amazon. Do not edit any of the URL parameters.” The returned URL contains Arda’s affiliate tag (set in the request’s partnerTag) plus Amazon’s tracking parameters (linkCode, language, th, psc) needed for proper attribution. Stripping or rebuilding these breaks attribution. The Shared affiliate-url.ts builder utility (which constructs https://www.amazon.com/dp/<ASIN>?tag=<assoc-tag> from an ASIN) is provided as a fallback for cases where Amazon’s response is unavailable (e.g. PDEV-429 cart-link work) but is not how productUrl is produced in v1. Scope of the rule: image URLs (image.url) and any other media URL is the Amazon-hosted URL passed through unchanged — same as productUrl.

4. No image rehosting. The Amazon-hosted image URL is returned unchanged in the BFF response. v1 does not download the image, copy it to S3, or proxy it. The Associates Program IP License prohibits storing or caching Product Advertising Content consisting of an image; downstream callers of this BFF must respect the License’s 24-hour caching rule. See context-exploration.md for verbatim citations.

5. Use the official Amazon Creators API via the amazon-creators-api npm wrapper. PA-API 5 is deprecated as of 2026-05-15 (per the deprecation banner on webservices.amazon.com/paapi5/documentation/); v1 imports amazon-creators-api@1.2.2 (Apache-2.0; pinned exact version, no caret) which republishes Amazon’s official Node.js SDK plus a thin TypeScript wrapper. Data API host: creatorsapi.amazon (/catalog/v1/...). Authentication: OAuth 2.0 client_credentials, v3 LWA (token endpoint https://api.amazon.com/auth/o2/token, scope creatorsapi::default, ~1-hour access tokens cached in BFF-process memory with a 30-second pre-expiry buffer; the SDK handles all of this). Documented downgrade path: vendor Amazon’s official creatorsapi-nodejs-sdk archive as a workspace package if the wrapper goes silent or is compromised.

6. US-only marketplace (amazon.com). Three system-level constraints make non-US support a separate project: (a) Amazon Associates programs are per-locale, so Arda’s US tag does not pay commission on amazon.co.uk clicks; (b) Creators API credentials are region-scoped (Arda will be issued NA-region credentials); (c) the IP License grant is tied to the US Associates program. v1 rejects non-US hosts with a clear error. Unblock conditions for a future iteration: Arda enrols in another locale’s Associates program, gains credentials for another Creators API region, or the product roadmap commits to multi-marketplace.

7. Structured error contract. The BFF route returns errors with stable machine-readable codes plus human-readable default messages, so the follow-up SPA can localise or override the copy. Codes for v1: INVALID_REQUEST (HTTP 400 — malformed JSON or missing/non-string input field), UNSUPPORTED_SHORT_LINK, UNRECOGNIZED_AMAZON_URL, UNSUPPORTED_AMAZON_LOCALE, AMAZON_API_THROTTLED (rate-limited by Amazon), AMAZON_ITEM_NOT_ACCESSIBLE (Amazon could not return this listing), AMAZON_API_UNAVAILABLE (upstream Amazon API failure or network failure). The exact mapping from upstream Amazon errors to these codes is settled in specification.md once verified against the live Creators API.

8. Authentication on the BFF route. Tenant-scoped JWT verification, identical to other /api/arda/* routes. Anonymous open access would let an attacker burn Arda’s Amazon TPS quota.

9. Documentation page mandatory. The new page at current-system/functional/reference-data/item/amazon-bff-api.md ships in the same PR as the route, describing input shape, output shape, error codes, and configuration touchpoints. Input/output shapes are defined as TypeScript types so the page can reference them directly.

10. No long-lived response caching. The BFF route does not memoise Creators API responses for more than 24 hours. The recommended posture for v1 is no in-process cache at all (each request triggers a fresh upstream call); a future memoisation layer must respect the 24-hour ceiling per the IP License’s non-image caching rule (verbatim in context-exploration.md).

11. Single ASIN-extraction utility. All URL → ASIN parsing logic lives in one Shared module so the recognised URL-form set can be evolved by editing one file. The BFF route, tests, and any future SPA caller import from this single source.

12. Configuration source split — secrets via Amplify env vars sourced from 1Password; one true constant in source. v1 uses four server-side environment variables (no NEXT_PUBLIC_ prefix; matches the existing arda-frontend-app <SERVICE>_<PROPERTY> convention):

    • AMAZON_CREATORS_CREDENTIAL_ID
    • AMAZON_CREATORS_CREDENTIAL_SECRET
    • AMAZON_CREATORS_CREDENTIAL_VERSION
    • AMAZON_ASSOCIATE_TAG

    These four are aggregated through src/lib/env.ts (the existing server-side env aggregator) with mock-mode fallbacks. They must also be added to the env | grep allowlist in arda-frontend-app/amplify.yml so Amplify writes them to the build’s .env. The marketplace string "www.amazon.com" is a source constant (e.g. in src/lib/shared/amazon/constants.ts) — true invariant per Constraint 6, not a runtime config. Source of truth for the four secrets: 1Password vaults Arda-DemoOAM, Arda-DevOAM, Arda-StageOAM, Arda-ProdOAM, each with a single multi-field entry. Delivery to Amplify: branch environment variables on each Amplify app (operator copies from 1Password to Amplify Console — see the operator runbook for the exact step). v1 uses the same single credential triple in all four vaults (no per-environment isolation) and a single Associate Tag in all four vaults.

Open Items (non-blocking, recorded for the next phase)

• Short-link prevalence. Estimate or measure what share of real-world user pastes are short links (a.co, amzn.to). The number drives whether the follow-up project should prioritise server-side redirect-following or rely on the rejection message indefinitely.
• Documentation page exact section structure. The location is fixed (current-system/functional/reference-data/item/amazon-bff-api.md); the section breakdown can be drafted alongside the implementation.
• Amplify env-var IaC pipeline (in scope; mechanism fully settled). The four AMAZON_* env vars flow through the existing pipeline: 1Password vault → op read in amm.sh → CFN parameter override → AWS Secrets Manager (multi-field secret) → CloudFormation {{resolve:secretsmanager:…}} in amplify.cfn.yaml (full-IaC partitions) or aws amplify update-app --environment-variables jq-merge in amm.sh’s else branch (partial-IaC partitions) → Amplify env var → amplify.yml’s env | grep allowlist → Next.js .env → process.env.X. The split between full-IaC and partial-IaC partitions, and the Alpha001:prod us-east-2 region anomaly, are documented end-to-end in context-exploration.md § “IaC Compliance per Partition”; the concrete file edits are listed there and in the infrastructure row of the Repositories table above.
• Eligibility-loss monitoring. Creators API access is conditional on Arda generating qualified referring sales every 30 days (per Amazon’s API Rates page). If Arda goes 30 consecutive days without qualified sales the Associates account loses Creators API access; restored within 2 days of the next qualifying sale. Worth recording as an operational risk; not a blocker.

Deliverables

Planning artefacts (this directory)

#	Deliverable	Location
1	goal.md (this document)	This directory
2	context-exploration.md — self-contained context for v1 decisions, grounded in original sources	This directory
3	requirements.md — concrete requirements derived from this goal	This directory (next phase)
4	verification.md — acceptance criteria mapped to success criteria	This directory (next phase)
5	specification.md — design specification for the BFF route, the operations signer change, the utilities, and the configuration touchpoints	This directory (next phase)
6	implementation-changes.md — task plan with concrete files to create or modify	This directory (next phase)

Code PRs

#	Deliverable	Location
7	Operations PR — service/ItemPrinter.kt + tests (~2 files)	operations repo
8	arda-frontend-app PR — amazon-creators-api dependency added (pinned 1.2.2); Creators API client, BFF route, Shared utilities (parser, builder, types, MARKETPLACE constant); the four AMAZON_* env vars wired through src/lib/env.ts and added to the amplify.yml allowlist; unit tests; CHANGELOG entry	arda-frontend-app repo
9	infrastructure PR — Amplify branch env-var configuration for the four AMAZON_* variables on each of demo, dev, stage, prod apps; mechanism settled in round-2 investigation (CDK / CloudFormation update; secret reference rather than literal where applicable)	infrastructure repo
10	Documentation PR — amazon-bff-api.md + process/sre/runbooks/amazon-creators-api-onboarding.md + this directory’s planning artefacts + CHANGELOG entry	documentation repo

Documentation deliverables

#	Deliverable	Location
11	BFF-route reference page describing the route’s input shape, output shape (the v1 DTO), error codes, and configuration touchpoints	documentation/src/content/docs/current-system/functional/reference-data/item/amazon-bff-api.md
12	Operator runbook (Account Holder persona) with Creators API registration steps, Application + credential creation, the four 1Password vault entries, and Amplify-side credential delivery	documentation/src/content/docs/process/sre/runbooks/amazon-creators-api-onboarding.md

Operator artefacts (executed via the runbook above, not by engineering)

#	Deliverable	Where
13	Creators API Application + credential set in Associates Central (Account Holder persona)	Amazon Associates Central → Tools → Creators API
14	Single multi-field entry Amazon Creators API in vault Arda-DemoOAM with fields credentialId, credentialSecret, version, associateTag	1Password vault Arda-DemoOAM
15	Same entry in vault Arda-DevOAM (v1: same credential triple as Demo)	1Password vault Arda-DevOAM
16	Same entry in vault Arda-StageOAM (v1: same credential triple as Demo)	1Password vault Arda-StageOAM
17	Same entry in vault Arda-ProdOAM (v1: same credential triple as Demo)	1Password vault Arda-ProdOAM
18	The four AMAZON_* Amplify branch env vars set on each of demo, dev, stage, prod Amplify apps — populated from the corresponding 1Password vault, delivered via the IaC mechanism settled in round-2 investigation	infrastructure-managed Amplify configuration

Reference Documents

v1 supporting material (in this directory)

• context-exploration.md — self-contained context for v1 decisions, grounded in original sources (Amazon Associates legal documents and court rulings). Covers the Creators API selection, the IP License (image-rehosting prohibition, 24-hour caching rule, ASIN-persistence permission, pricing/availability disclaimer), the affiliate-tag canonicalisation rule, the US-only marketplace scope, the URL-form parsing reference, and the third-party-scraper out-of-scope analysis. Technical specifics of the Creators API (request body, response shape, error codes, throttling) are deferred to specification.md.
• requirements.md, verification.md, specification.md, implementation-changes.md — produced via the project-planning skill once this goal is approved.

Parked-project material (read on demand)

The predecessor exploration was parked under roadmap/on-hold/amazon-client-integration-extended/ on a separate branch (PR pending merge to main). Until that PR lands, the parked artifacts are not yet linkable from main; once they are, the four files of interest are goal.md (prior goal document — worked example, not a binding spec), project-handover.md (orientation document with the full decision history), amazon-product-api-exploration.md (desk research on Creators API vs. PA-API 5, authentication, rate limits, IP License analysis, third-party-scraper analysis), and vendor-sourced-items-exploration.md (Arda ItemInput / ItemSupplyInput field surface alongside the Creators API field surface). v1’s decision audit trail in context-exploration.md is self-contained and does not depend on these.

Internal references

• Image upload project — context for the existing CDN/S3 image pipeline that the operations signer change interacts with.
• /Users/jmp/code/arda/scratch/itemApi.json — live Item OpenAPI snapshot (re-fetched 2026-05-06).

External references

• Creators API documentation root — https://affiliate-program.amazon.com/creatorsapi/docs/ (JS-rendered SPA; pages are accessible via a JS-capable browser, not anonymous static fetch).
• Creators API API Reference index — https://affiliate-program.amazon.com/creatorsapi/docs/en-us/api-reference.
• Creators API GetItems — https://affiliate-program.amazon.com/creatorsapi/docs/en-us/api-reference/operations/get-items.
• Creators API resources used in v1: …/resources/item-info, …/resources/images, …/resources/offersV2 (note camelCase URL).
• Creators API API Rates — https://affiliate-program.amazon.com/creatorsapi/docs/en-us/concepts/api-rates.
• Creators API Error Codes & Messages — https://affiliate-program.amazon.com/creatorsapi/docs/en-us/troubleshooting/error-codes-and-messages.
• Creators API Migration from PA-API — https://affiliate-program.amazon.com/creatorsapi/docs/en-us/migrating-to-creatorsapi-from-paapi.
• Creators API Using SDK — https://affiliate-program.amazon.com/creatorsapi/docs/en-us/get-started/using-sdk.
• Creators API Register for Creators API — https://affiliate-program.amazon.com/creatorsapi/docs/en-us/onboarding/register-for-creators-api.
• amazon-creators-api (Apache-2.0 npm wrapper) — https://github.com/ryanschiang/amazon-creators-api, https://www.npmjs.com/package/amazon-creators-api.
• Associates Program IP License — section of https://affiliate-program.amazon.com/help/operating/policies.
• Associates Program Operating Agreement — https://affiliate-program.amazon.com/help/operating/agreement.
• PA-API 5 deprecation banner — https://webservices.amazon.com/paapi5/documentation/get-items.html.

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved