| name | amazon-shared |
| description | Common Amazon Seller Central / advertising-console mechanics — marketplace TLD map; version-aware navigation (New Seller Central 'NGS' vs classic, navigate by direct URL); sign-in as a challenge LOOP with Ziniao auto-fill of password / OTP (紫鸟验证码服务) / hosted passkey (已托管账号Passkey, native overlay → coordinate-click), Ziniao-stored-else-human rule; ad-console vs seller-central account caveat; capture rule. Prerequisite: every other amazon-* skill (amazon-ads, amazon-reports, amazon-invoice, amazon-listing / amazon-fbn / etc.) expects this loaded for cross-cutting auth and navigation patterns. |
Amazon — Shared (auth, navigation, common patterns)
This skill covers what every Amazon Seller Central or advertising-
console task needs: marketplace endpoints, the hamburger-menu hover
pattern, login / Ziniao / OTP handling, and the ad-console vs
seller-central account caveat. Operation-specific skills
(amazon-ads, amazon-reports, amazon-invoice, future
amazon-listing / amazon-fbn / etc.) load this first.
1. Marketplace TLDs
Amazon Seller Central is per-country. Use the country-specific TLD
in URLs — paths are usually identical.
| Marketplace | Seller Central | Advertising console |
|---|
| US | sellercentral.amazon.com | advertising.amazon.com |
| UK | sellercentral.amazon.co.uk | advertising.amazon.co.uk |
| (others) | sellercentral.amazon.<tld> | advertising.amazon.<tld> |
For the canonical per-country base URLs and path table, read
knowledge/project/common/amazon-sites.md — that file is the source
of truth for seller-central paths (inventory, listings, orders,
performance, etc.). Don't guess seller-central paths.
Unified multi-marketplace accounts: one Amazon seller-id, multiple
marketplaces. Inventory differs (~10–20% of ASINs are listed on one
but not the others). Listing-status enums differ (e.g. one marketplace
omits DetailPageRemoved from a filter dropdown while another includes
it — read the live dropdown). Custom Reports's All-Listings TSV is
byte-identical across the marketplaces' subdomains (account-level). Stranded Inventory is a single pool. When debugging
a specific listing, always specify which marketplace; "the inventory
for store X" is ambiguous.
2. Sign-in flow (browser-side)
The first hit per session typically redirects through Amazon sign-in
(/ap/signin) even if a previous session is still good. The modern
flow is multi-step: email → Continue → password → (optional 2FA).
Ziniao pre-fills the email and password; the agent advances each step
and lets the redirect settle.
browser-use <<'PY'
new_tab("https://sellercentral.amazon.<tld>/home")
wait_for_load()
js("var c=document.querySelector('#continue,input#continue'); if(c) c.click();")
wait_for_load()
js("var b=document.querySelector('#signInSubmit'); if(b) b.click();")
wait_for_load()
print(page_info())
PY
page_info() does NOT show auto-filled input values — fields appear
empty even when filled. Confirm with
js("return document.querySelector('#ap_password')?.value ? 'filled':'empty'")
(null-safe ?. — the same snippet runs on steps where the field is
absent) before deciding whether to ask the user.
Login is a challenge LOOP, not a fixed sequence
Which challenges Amazon presents — password, OTP, passkey, or a
combination — is decided by Amazon's risk control and varies run to
run (a passkey can still be followed by OTP; a trusted session skips
both). So do not hard-code an order. After each submit, re-read the
page and resolve whatever challenge is shown, repeating until the URL
reaches /home or /amazonsell/business.
Decision rule at every challenge — Ziniao-stored → use Ziniao;
otherwise → ask a human. Ziniao "has it" when the field is pre-filled
(password) or a Ziniao panel appears (紫鸟验证码服务 for OTP,
已托管账号Passkey for passkey). If the expected Ziniao affordance never
appears for a required step, stop and ask the user — never loop forever
on a challenge Ziniao can't satisfy.
2a. Ziniao helper panels are NATIVE overlays — screenshot, don't querySelector
When a step needs a code or a passkey, Ziniao renders its own panel:
the OTP service (紫鸟验证码服务) and the hosted-passkey picker
(已托管账号Passkey). These are Ziniao-native overlays, NOT part
of the page DOM — document.querySelector can't find them and a JS
.click() silently no-ops (verified: navigator.credentials.get hooks
never fire). Drive them by sight: capture_screenshot(path) → read the
button's pixel position → click_at_xy(x, y). A human clicks these the
same way, so the agent can too — coordinate-click reaches them because
they render inside the browser viewport.
2b. OTP / 2FA
If the flow lands on /ap/mfa (Two-Step Verification), Ziniao fetches
the code and fills the OTP field (its 紫鸟验证码服务 panel shows
验证码获取成功). Submit (#signInSubmit is usually in the page DOM
here; coordinate-click the "Sign in" button if not). This path is the
long-standing default and needs no special handling beyond the submit.
2c. Passkey (accounts Amazon has moved to passkey login)
Some accounts no longer offer a usable password/OTP login and are
forced onto passkeys. The store's passkey is hosted by Ziniao
(not an OS/biometric credential), so login stays fully automatable —
there is no Touch ID / Windows Hello dialog:
- At the password step, take the passkey branch: click "Sign in with
a passkey" (a real page-DOM link — JS or coordinate click both work).
- Ziniao pops its
已托管账号Passkey overlay listing the hosted
Amazon credential for the account, with a blue 使用该Passkey登录
("sign in with this passkey") button. This overlay is native (§2a) —
capture_screenshot() then click_at_xy() on that blue button. Do
not try to querySelector it. The overlay floats to a different
position each time (its Y shifts run to run), so re-screenshot and
read the button's coordinates every attempt — never reuse hardcoded
x/y.
- The flow then continues the challenge LOOP above — for this account it
routes on to OTP (§2b), which Ziniao autofills; a lower-risk session
may go straight to
/home. Resolve each step until you land on the
dashboard.
Daemon-drop gotcha: a successful passkey navigation sometimes tears
down the browser-use session (next call fails with a socket
FileNotFoundError). That's not a login failure — rotate VIBE_TASK_ID
and re-open the home URL to confirm the logged-in state.
Robustness / when to ask a human: the only genuine blocker is the
hosted-passkey overlay never appearing after "Sign in with a passkey"
(passkey not provisioned in Ziniao for this store). If it does appear,
coordinate-click it — do not escalate. If the URL is still on
/ap/signin ~8s after the coordinate-click, re-screenshot (the button
may have shifted) and click again before giving up.
3. Ad-console vs Seller-Central — different accounts
For some merchants, the advertising console (advertising.amazon.<tld>)
is on a different underlying Amazon account from the seller-
central account (different email, different entityId), even
though SSO usually bridges them transparently.
When debugging an "I logged in but it shows the wrong account"
issue:
- Check the email in the Ziniao password-fill dialog.
- Check the
entityId in the ad-console URL (?entityId=ENTITY[A-Z0-9]+)
— that's what's actually active.
Both indicate which account is currently signed in.
4. Navigation — two UI generations (New Seller Central vs classic)
Amazon is rolling out New Seller Central ("NGS"). A migrated account
looks and navigates differently from a classic one, so first know which
you're on — then use the one navigation method that works on both.
4a. Navigate by DIRECT URL — the version-agnostic path (do this first)
The redesign changed the chrome (menus, tabs, dashboard), but the
underlying page paths are unchanged — /reportcentral/...,
/payments/reports-repository, /orders-v3, /business-reports,
/myinventory/inventory, etc. all load directly on both UIs (verified).
So for a known destination, just new_tab(<url>) — do not open the
menu at all. Canonical per-country paths live in
knowledge/project/common/amazon-sites.md; that is the source of truth.
Only fall back to the menu (§4c/§4d) when you need to discover a page
whose URL you don't have.
4b. Detecting the version
Load /home and check where you land / what renders:
- New Seller Central (NGS) —
/home redirects to
/amazonsell/business (?ref=homepage_redirect_ngs); the page has
a "New Seller Central" toggle in the top bar, a dashboard
channel-tab row (My business / Products / Supply chain / Orders /
Finance / Customers / Marketing) and casino-* web components
(document.querySelector('casino-greeting-header, navigation-favorites-bar')).
- Classic — plain
/home dashboard, no casino-* elements; the old
hamburger hover-menu (§4d).
- Force classic when a page misbehaves under NGS: append
?ngs_do_not_redirect_flag=1 to /home to stay on the classic home.
4c. NGS chrome (for discovery only)
- Favorites / quick-nav bar (
navigation-favorites-bar, top,
horizontal): direct links (Manage All Inventory, Payments, Business
Reports, …). Read their real hrefs from the bar's (shadow) DOM and open
them.
- Hamburger (
navigation-hamburger-menu, top-left) opens a
full-height left drawer with categories (Catalog, Inventory,
Pricing, Orders, Advertising, Stores, Growth, Reports, Payments,
Performance, Apps and Services, Brands, Learn). Categories expand to a
flyout; if a stable selector isn't obvious, capture_screenshot() then
click_at_xy(x, y).
4d. Classic chrome — hamburger hover-to-reveal
On a classic account the hamburger menu uses a hover-to-reveal
pattern — dispatch mouseover (not click) on a parent category:
browser-use <<'PY'
js("document.querySelector('navigation-hamburger-menu').shadowRoot.querySelector('[role=button]').click()")
wait_for_load()
js("""
var cat = [...document.querySelectorAll('[aria-expanded=false]')]
.find(e => e.textContent.trim() === 'Reports');
cat.dispatchEvent(new MouseEvent('mouseover', {bubbles: true})); # NOT click — click navigates away
""")
js("""[...document.querySelectorAll('a, [role=button]')]
.find(e => e.textContent.trim() === 'Business Reports').click();""")
PY
If a stable selector isn't obvious, capture_screenshot() + click_at_xy(x, y).
But prefer §4a (direct URL) over any of this whenever you know the path.
5. Capture rule
Per-run live data (campaign captures, search-term exports, screenshots,
ad-spend snapshots) goes to /tmp/<run-slug>/. Never under
~/.vibe-seller/knowledge/ — that path is for codified, reusable
facts about the platform, NOT per-run private business data. The
catalog gets synced into agent contexts, so private data there leaks
across sessions.
6. Common "always load X first" pattern
Before any browser-use call against Amazon:
- Load
browser-use skill (heredoc helper interface + wrapper rules).
- Load this skill (
amazon-shared) for the mechanics above.
- Load the operation-specific skill (
amazon-ads, amazon-reports,
…) and any of its references that the task needs.
The wrapper auto-starts the browser on first new_tab(...), so you
don't need to pre-warm the CDP proxy. Just open the URL, call
wait_for_load(), then read state with print(page_info()).
See also
amazon-ads — Sponsored Products / Brands / Display + Couponsamazon-reports — Business / Fulfillment / Tax / Payments / Advertising reportsamazon-invoice — Tax-invoice PDF generation from order data
