Add Seller Runbook

When to Use

Onboarding a new Amazon seller account (new tenant) into StickyMetrics.

Prerequisites

• Seller must have an SP-API application registered in Seller Central
• You need: client_id, client_secret, refresh_token from the app
• Marketplace ID (US = ATVPDKIKX0DER)

Steps

cd ~/stickymetrics
python3 scripts/add_seller.py \
  --seller-id <lowercase_id> \
  --label "Human Name (Region)" \
  --marketplace-id ATVPDKIKX0DER \
  --vault-prefix <UPPERCASE_PREFIX> \
  --client-id "amzn1.application-oa2-client...." \
  --client-secret "amzn1.oa2-cs.v1...." \
  --refresh-token "Atzr|...."

What It Does

1. Validates LWA refresh-token + client creds against Amazon
2. Calls SP-API marketplaceParticipations to confirm marketplace is authorized
3. Stores secrets in Vaultwarden as {PREFIX}_SP_API_CLIENT_ID, _CLIENT_SECRET, _REFRESH_TOKEN
4. Inserts row into raw.sellers

After Onboarding

• Run initial backfill: python3 scripts/backfill_orders.py --seller <id> --days 365
• Add seller to nightly refresh (currently hardcoded to ecomhd_us in the script - needs parameterization for multi-tenant)
• Set up Ads API separately via add_seller_ads.py if they have advertising

Naming Convention

• seller_id: <brand>_<region> (e.g., ecomhd_us, luma_us)
• vault_prefix: <BRAND> (e.g., ECOMHD, LUMA)