App Store Connect Metadata Updater

Update app metadata on App Store Connect via the REST API v2. Supports all text fields (description, what's new, promotional text, keywords, title, subtitle) across multiple locales in a single run.

Prerequisites

1. App Store Connect API Key: Create one at https://appstoreconnect.apple.com/access/integrations/api
   • Role: Admin or App Manager
   • Download the .p8 file and note the Key ID and Issuer ID
2. App version must already exist in App Store Connect (draft or editable state)
3. Python 3.10+ (uses stdlib only, no pip install needed)

Configuration

Set these environment variables (or pass as CLI flags):

export ASC_KEY_ID="YOUR_KEY_ID"
export ASC_ISSUER_ID="YOUR_ISSUER_ID"
export ASC_KEY_FILE="/path/to/AuthKey_XXXXX.p8"
export ASC_APP_ID="123456789"

Metadata JSON Format

Create a JSON file with locale keys mapping to metadata fields:

{
  "en-US": {
    "description": "Full app description...",
    "whatsNew": "What's new in this version...",
    "promotionalText": "Short promotional text...",
    "keywords": "keyword1,keyword2,keyword3",
    "name": "App Title",
    "subtitle": "App Subtitle"
  },
  "zh-Hans": {
    "description": "...",
    "whatsNew": "...",
    "promotionalText": "...",
    "keywords": "..."
  }
}

Field Reference

Field	API Target	Limit	Notes
description	appStoreVersionLocalizations	4,000 chars	Full app description
whatsNew	appStoreVersionLocalizations	4,000 chars	Release notes / what's new
promotionalText	appStoreVersionLocalizations	170 chars	Editable without new version
keywords	appStoreVersionLocalizations	100 chars	Comma-separated, no spaces after commas
name	appInfoLocalizations	30 chars	App title on the store
subtitle	appInfoLocalizations	30 chars	Shown below title

Only include fields you want to update. Omitted fields are left unchanged.

Usage

How to invoke

When the user asks to update App Store metadata, run the Python script at update_metadata.py in this skill's directory.

Workflow

1. Prepare metadata JSON - Generate it from the ASO metadata doc or create manually
2. Dry run first - Always preview what will be updated before pushing
3. Push to ASC - Run the actual update

Step 1: Dry Run (always do this first)

python3 <skill-dir>/update_metadata.py \
  --version "1.5" \
  --metadata-file /path/to/metadata.json \
  --dry-run

Step 2: Push metadata

source /path/to/.env && \
python3 <skill-dir>/update_metadata.py \
  --key-id "$ASC_KEY_ID" \
  --issuer-id "$ASC_ISSUER_ID" \
  --key-file "$ASC_KEY_FILE" \
  --app-id "$ASC_APP_ID" \
  --version "1.5" \
  --metadata-file /path/to/metadata.json

Common Options

# Update only specific locales
--locales en-US,zh-Hans,ja

# Update only specific fields
--fields description,whatsNew,promotionalText

# Skip confirmation prompt
--yes

# Dry run (preview only, no API writes)
--dry-run

Generating metadata JSON from a markdown doc

The agent should parse the ASO metadata markdown document and generate the JSON file. Example:

python3 <skill-dir>/update_metadata.py \
  --version "1.5" \
  --metadata-file /path/to/metadata.json \
  --fields description,whatsNew,promotionalText \
  --locales en-US,zh-Hans,zh-Hant,ja,ko,ru,tr

Troubleshooting

• "Version not found": The version must exist in App Store Connect in an editable state
• "401 Unauthorized": Check API key permissions (needs Admin or App Manager role)
• Character limit exceeded: The script validates limits before pushing and will abort with details
• "name" or "subtitle" not updating: These use a different API endpoint (appInfoLocalizations). Ensure the app info exists for that locale.

Details

• Pure Python 3.10+ (no external dependencies)
• JWT signing implemented with stdlib (no PyJWT needed)
• Validates character limits before pushing
• Supports partial updates (only specified fields)