Skip to main content
App Store metadata, screenshots, and localization Level: Beginner 9 min read

App Store Promotional Text Explained: When and How to Update It

A complete guide to App Store Promotional Text: how it differs from your description, why it can be edited anytime without App Review, and how to update it via FlightDeck MCP.

Published: 2026-11-02 • Last Updated: 2026-11-02 • Author: Kip Lawrence
Key MCP Tools: app_store_versions_listapp_store_version_localizations_listapp_store_version_localization_updateapp_store_version_localization_get

Overview: The Live-Editable Field in App Store Connect

When managing an iOS, iPadOS, or macOS application in App Store Connect, almost every customer-facing marketing copy field on your product page—your App Name, Subtitle, Description, Keywords, and Screenshots—becomes locked the moment your version is approved and released to the public (READY_FOR_SALE). If you want to fix a typo in your description or announce a weekend discount in your primary copy, Apple requires you to create a new version draft, attach a new build, and wait for full App Review.

While non-copy operational metadata (such as pricing schedules, territory availability, in-app purchases, and privacy nutrition labels) can also be adjusted independently of an app release, there is one major exception for customer-facing storefront marketing copy: Promotional Text.

Promotional text is an optional, high-visibility 170-character field that appears at the very top of your app's storefront description. Crucially, Promotional text is the sole customer-facing product page copy field that Apple permits updating at any time on a live app (READY_FOR_SALE) without creating a new app version or submitting for App Review. Changes go live across Apple's edge CDN within minutes.

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│              CUSTOMER-FACING MARKETING COPY MUTABILITY                 │
│                                                                        │
│   Description (4,000 Chars) ──► LOCKED upon App Review Approval        │
│   Keywords (100 Chars)      ──► LOCKED upon App Review Approval        │
│   Screenshots & Video       ──► LOCKED upon App Review Approval        │
│                                                                        │
│   PROMOTIONAL TEXT (170)    ──► EDITABLE ANYTIME ON LIVE APP           │
│                                 (Zero Review Delay, Zero Rebuilds)     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   APP STORE CUSTOMER STOREFRONT VIEW                   │
│                                                                        │
│   [ App Icon ]  PeakPulse: Daily Habit Log                             │
│                 Build Better Routines                                  │
│                                                                        │
│   ┌────────────────────────────────────────────────────────────────┐   │
│   │ PROMOTIONAL TEXT (Bold Top Banner, Above the Fold):            │   │
│   │ "⚡ New Year Flash Sale: Unlock Lifetime Pro for 50% off      │   │
│   │    this week only! Updated with iOS 18 interactive widgets."   │   │
│   └────────────────────────────────────────────────────────────────┘   │
│                                                                        │
│   Description (Truncated behind "...more" link):                       │
│   PeakPulse helps you track daily habits and stay accountable...       │
└────────────────────────────────────────────────────────────────────────┘
Important

Not Indexed for Search Ranking: Unlike your App Name, Subtitle, and Keywords, Promotional Text is NOT indexed by Apple's search algorithm. Stuffing keywords into this field will not improve your search placement. Its sole purpose is Conversion Rate Optimization (CRO)—capturing the customer's attention the moment they view your product page.


Quick Answer: How to Update Promotional Text in Seconds

To update your live promotional text using your AI coding assistant and FlightDeck:

  1. Ask your assistant to draft a timely announcement within 170 characters.
  2. Instruct the assistant to inspect your currently live App Store version and locate the localization ID.
  3. The assistant calls app_store_version_localization_update targeting promotionalText.
  4. FlightDeck intercepts the mutation and presents a confirmation card in the Desktop Approval Center.
  5. Click Approve. FlightDeck transmits the change directly to Apple's API. The update reflects immediately on the App Store without entering the App Review queue.

Copyable Prompts for Your AI Coding Assistant

1. Update Live Promotional Text (Seasonal Announcement)

Use this prompt to publish a time-limited promotional notice or feature announcement on your live storefront:

MARKDOWN
We need to update the Promotional Text on our live App Store listing to announce our holiday discount:
1. Query App Store Connect via FlightDeck to find our current live version (READY_FOR_SALE) and inspect its English localization.
2. Draft a compelling, customer-focused promotional message announcing: "Holiday Special: 40% off all Annual Pro plans through December 31! New widget customization included."
3. Ensure the text is strictly 170 characters or fewer (including spaces and punctuation).
4. Stage the update to our live version's promotional text using FlightDeck.
5. Confirm when the change set is waiting in the FlightDeck Desktop Approval Center.

2. Multilingual Promotional Text Update

To synchronize promotional banners across international storefronts simultaneously:

MARKDOWN
We want to update our Promotional Text across all active storefront languages for our current live release:
1. List all configured localizations on our live App Store version using FlightDeck.
2. Translate our approved English announcement: "⚡ Summer Update: Experience 2x faster sync and new dark mode themes!" into each active language (e.g., es-ES, fr-FR, de-DE, ja).
3. Ensure every localized string is under 170 characters.
4. Present a preview table with character counts, then stage the updates in FlightDeck for my desktop approval.

Promotional Text Specifications & Rules

Attribute Specification Developer Impact
Character Limit Exactly 170 characters maximum. API returns HTTP 400 validation error if character count is 171 or higher.
Positioning Placed above the main description, preceding the "...more" expansion button. Highest visibility text element on your product page after your subtitle.
Review Requirements Zero review requirement. Bypasses App Review entirely; updates propagate globally in near real-time.
Search Indexing None. Apple's search crawler ignores this field. Do not waste characters on comma-separated keywords.
HTML / Markdown Plain text only. Emoji characters are supported and encouraged; Markdown asterisks (**) render literally.
Version Scope Bound to an AppStoreVersionLocalization record. Can be updated on both active draft versions and released live versions.

Best Practices vs. Anti-Patterns

Effective Use Cases (High Conversion Impact)

  • Limited-Time Offers & Sales: "🎉 Spring Sale: Unlock Pro for 50% off this week only! Try our award-winning routine planner risk-free." (104 chars)
  • Major Milestone or Press Accolade: "Selected as Apple Editors' Choice! Discover why over 100,000 creators organize their day with FlowTrack." (104 chars)
  • Time-Sensitive Event or Tournament: "🏆 Season 4 Championship starts this Friday! Compete for global leaderboards and exclusive custom badges." (105 chars)
  • Breaking Feature Announcement: "Now optimized for iOS 18! Add interactive home screen widgets and customize control center shortcuts." (104 chars)

Anti-Patterns to Avoid

  • Evergreen Descriptions: Do not repeat the first paragraph of your app description. If the copy never changes, keep it in the primary description field.
  • Keyword Stuffing: Writing "productivity, habit tracker, daily planner, habits, routines, todo" wastes prime storefront real estate without boosting search rankings.
  • Hardcoded Pricing Without Currencies: Avoid "Now only $4.99" unless you localize every single currency; users in the UK, Europe, or Japan will find hardcoded dollar amounts confusing.

Step-by-Step Execution Workflow via FlightDeck

MERMAID
sequenceDiagram
    autonumber
    actor Dev as Developer
    participant AI as AI Coding Assistant (IDE)
    participant FD as FlightDeck Desktop (MCP)
    participant Apple as Apple App Store Connect

    Dev->>AI: "Update promotional text on our live app"
    AI->>FD: app_store_versions_list(appId)
    FD->>Apple: GET /v1/apps/{id}/appStoreVersions
    Apple-->>FD: Active version in READY_FOR_SALE
    FD-->>AI: Returns live versionId
    AI->>FD: app_store_version_localizations_list(versionId)
    FD->>Apple: GET /v1/appStoreVersions/{id}/appStoreVersionLocalizations
    Apple-->>FD: Returns localizationId (en-US)
    FD-->>AI: Returns localizationId
    AI->>Dev: Displays proposed 115-char message
    Dev->>AI: "Approved, publish now"
    AI->>FD: app_store_version_localization_update(localizationId, promotionalText)
    Note over FD: Approval Center intercepts mutation<br/>Generates visual diff card
    FD-->>AI: STAGED (Awaiting Desktop Approval)
    AI-->>Dev: "Staged in FlightDeck. Please approve in GUI."
    Dev->>FD: Inspects diff in Desktop GUI & clicks [Approve]
    FD->>Apple: PATCH /v1/appStoreVersionLocalizations/{id}
    Apple-->>FD: HTTP 200 OK (Instant Commit)
    FD-->>Dev: Live storefront banner updated

Step 1: Identifying the Target Version and Locale

Your AI assistant calls app_store_versions_list to locate the active versions. To update the live storefront banner immediately, your assistant must target the localization ID of the version currently in READY_FOR_SALE state (even if an upcoming draft version also exists). If you instead update an unsubmitted draft version, the change is saved only on the upcoming release and will not appear on the live App Store until that version is approved and released.

Step 2: Drafting the Message Within 170 Characters

The AI assistant drafts a concise message and verifies the exact character count:

TEXT
"🔥 Black Friday Event: Unlock all premium filters and 4K export presets for 50% off through Sunday midnight!"
Length: 109 characters (Valid: <= 170)

Step 3: Invoking FlightDeck MCP

The assistant calls app_store_version_localization_update:

JSON
{
  "localizationId": "loc_en_us_45678912",
  "promotionalText": "🔥 Black Friday Event: Unlock all premium filters and 4K export presets for 50% off through Sunday midnight!"
}

Step 4: Inspecting the Approval Card

In the FlightDeck Desktop application, an Approval Center card opens displaying:

  • Action: Update Promotional Text
  • Status: Target Version is READY_FOR_SALE
  • Target Locale: en-US
  • Field: promotionalText
  • Character Count: 109 / 170 characters
  • Preview: Shows previous promotional text vs new promotional text.

Click Approve. FlightDeck immediately issues the PATCH request to Apple's API.


Authoritative Readback Verification

To verify that Apple has persisted the live promotional banner, run this prompt:

MARKDOWN
Please perform a readback of our live version's promotional text using FlightDeck to confirm that Apple accepted the update and returned HTTP 200.

The assistant invokes app_store_version_localization_get(localizationId: "...") and outputs the confirmed promotionalText attribute from Apple.


Troubleshooting Common Errors

1. "Promotional text exceeds 170 characters"

  • Cause: The text is 171 characters or longer. Note that emojis count as 2 characters (and certain complex emojis count as up to 4 characters in UTF-16).
  • Fix: Shorten the copy and use the AI assistant to re-count characters before staging.

2. "You cannot modify description on a live app"

  • Cause: The AI assistant accidentally passed both description and promotionalText in the app_store_version_localization_update payload on a READY_FOR_SALE version.
  • Fix: Apple strictly forbids editing description on a live version without a new version release. Ensure your prompt explicitly instructs the assistant: "Only update the promotionalText field; do not include description or keywords."

Security & Verification Safeguards

  • Credential Isolation: The developer's App Store Connect API keys remain secured within the macOS Keychain.
  • Fail-Closed Execution: Mutations are bounded by FlightDeck's cryptographic change sets. If an operator rejects the change set in FlightDeck Desktop, zero data is sent to Apple.
  • Instant Rollback: If a promotional message needs to be retracted or cleared, simply call the tool with promotionalText: "" to restore a clean storefront banner.

Official Apple Documentation

Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store