Skip to main content
App Store metadata, screenshots, and localization Level: Intermediate 10 min read

Reordering App Store Screenshot Sequences via MCP Tooling

How to inspect and reorder App Store screenshot sequences using FlightDeck's operation staging and Apple's relationship API without deleting or re-uploading assets.

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

Overview: Why Screenshot Order Dictates Storefront Conversion

On the Apple App Store, the sequence in which your screenshots appear directly drives discovery and user acquisition:

  1. Search Results Card: When a user searches for keywords in the App Store, Apple displays your first 3 portrait screenshots (or first single landscape screenshot) directly alongside your app icon and title.
  2. Above-the-Fold Product Page: On your product page, users evaluate the first two screenshots before deciding whether to tap "Get" or scroll further.

If your most compelling feature screenshot is placed at position 5 or 6, prospective users browsing search results will never see it. Reordering your screenshots to lead with your primary value proposition can dramatically improve your impression-to-install conversion rate.

However, many developers mistakenly believe that changing screenshot order requires deleting all existing assets and re-uploading them from scratch—a tedious process that burns time and risks asset loss. In Apple's REST API, screenshot ordering is governed by an ordered relationship array on the screenshot set. Using FlightDeck with an AI coding assistant, you can non-destructively reorder your screenshot sets programmatically or visually in seconds.

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   APPLE REST API SCREENSHOT SET HIERARCHY              │
│                                                                        │
│   AppStoreVersionLocalization (e.g., "en-US")                          │
│       └── AppScreenshotSet (e.g., "APP_IPHONE_69", ID: "set_101")      │
│             └── Relationships: appScreenshots (Ordered Array)          │
│                   ├── [0] Screenshot "Dashboard"    (ID: "scr_aaa")    │
│                   ├── [1] Screenshot "Analytics"    (ID: "scr_bbb")    │
│                   └── [2] Screenshot "Integrations" (ID: "scr_ccc")    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                   NON-DESTRUCTIVE REORDERING MUTATION                  │
│                                                                        │
│   PATCH /v1/appScreenshotSets/{id}/relationships/appScreenshots        │
│   Payload: [ "scr_bbb", "scr_aaa", "scr_ccc" ]                        │
│                                                                        │
│   ──► Analytics is now Position #1 (Instant pointer swap)              │
│   ──► Zero re-uploads, zero re-processing, zero image quality loss     │
└────────────────────────────────────────────────────────────────────────┘
Important

FlightDeck MCP Operational Architecture: FlightDeck does not expose a bespoke semantic tool named app_screenshot_order_update. Screenshot reordering is supported through two verified methods:

1. App Store Connect Web Portal (Visual): Drag-and-drop ordering directly in your browser. This is the simplest visual method for manual adjustments.

2. Universal Operation Dispatcher (flightdeck_operation_stage): Programmatically stages Apple's official operation appScreenshotSets_appScreenshots_replaceToManyRelationship (PATCH /v1/appScreenshotSets/{id}/relationships/appScreenshots).

Furthermore, when uploading a new screenshot via FlightDeck's app_screenshot_upload_plan, passing desiredPosition causes FlightDeck's execution workflow to automatically issue this relationship replacement upon successful upload.


Quick Answer: How to Reorder Screenshots

Method 1: App Store Connect Web Portal (Visual Drag-and-Drop)

  1. Sign in to App Store Connect and navigate to your draft version.
  2. Under Screenshots, select the target display tab (e.g. 6.9" Display).
  3. Click and drag any screenshot card left or right to reorder the presentation sequence.
  4. Click Save in the top right.

Method 2: AI-Assisted Programmatic Reordering (MCP)

  1. Verify Version State: Open or create an editable draft version (PREPARE_FOR_SUBMISSION). Screenshot ordering cannot be modified on approved, live versions (READY_FOR_SALE).
  2. List Existing Screenshots: Instruct your AI assistant to list the screenshots in your target locale and display set.
  3. Stage the Reordered Sequence: Have the assistant stage an appScreenshotSets_appScreenshots_replaceToManyRelationship change set containing the existing screenshot IDs in your desired sequence.
  4. Approve in FlightDeck Desktop: Review the side-by-side ordering diff in FlightDeck's native macOS interface and click Approve to commit the sequence to Apple.

Copyable Prompts for Your AI Coding Assistant

1. Inspect Screenshot Sequences and IDs

Run this prompt in your AI assistant to inspect the current order of screenshots for your target device and locale:

MARKDOWN
Please inspect our active App Store Connect draft version using FlightDeck:
1. Query our draft version localizations and list all screenshots for English (U.S.).
2. Group the screenshots by display family (e.g., iPhone 6.9-inch, iPad 13-inch).
3. Display a numbered table showing:
   - Current Position (1, 2, 3...)
   - Screenshot ID
   - Asset File Name or Description
   - Pixel Dimensions
4. Do not stage any changes yet—wait for my instructions on the new order.

2. Stage Non-Destructive Screenshot Reordering

Once you decide on the preferred sequence:

MARKDOWN
Please reorder our English (U.S.) iPhone 6.9-inch screenshots so that our "Feature Highlights" screenshot appears first, followed by Onboarding, Analytics, and Settings:
1. Confirm that all four existing screenshot IDs are included in the new sequence.
2. Present a preview comparing the current sequence against the proposed new sequence.
3. Stage the reordering mutation in FlightDeck for my review in the Desktop Approval Center.
4. Do not delete or re-upload any images.

3. Readback Verification of Persisted Order

After approving the change in FlightDeck Desktop:

MARKDOWN
Please perform an authoritative readback of our English (U.S.) iPhone 6.9-inch screenshot set using FlightDeck. Confirm that Apple persisted the new sequence and display the verified order from position 1 through the end.

Apple API Reordering Mechanics

Apple's App Store Connect REST API models screenshot ordering through relationship links rather than individual position attributes on the screenshot itself:

Operation Approach Method & Endpoint Pros & Cons
Relationship Replacement (Programmatic) PATCH /v1/appScreenshotSets/{id}/relationships/appScreenshots Instant & Non-Destructive. Takes an ordered array of screenshot IDs and updates the sequence pointers atomically. Retains all existing uploaded assets.
Portal Drag-and-Drop (Visual) App Store Connect Web UI Simple visual drag-and-drop in the browser. Recommended for developers who prefer a graphical interface.
Delete and Re-upload (Anti-Pattern) DELETE followed by POST upload Dangerous & Wasteful. Risks permanent loss of master files, triggers re-compression, wastes bandwidth, and resets processing timers.

The Relationship Replacement Payload Schema

When staging via flightdeck_operation_stage, the payload mirrors Apple's JSON:API specification:

JSON
{
  "operationId": "appScreenshotSets_appScreenshots_replaceToManyRelationship",
  "pathParameters": {
    "id": "set_iphone_69_en_us_12345"
  },
  "requestBody": {
    "data": [
      { "type": "appScreenshots", "id": "scr_feature_highlight_99" },
      { "type": "appScreenshots", "id": "scr_onboarding_main_01" },
      { "type": "appScreenshots", "id": "scr_dashboard_view_02" },
      { "type": "appScreenshots", "id": "scr_analytics_chart_03" }
    ]
  }
}
Warning

Complete Array Requirement: When calling appScreenshotSets_appScreenshots_replaceToManyRelationship, Apple expects you to pass all screenshots that should remain in the set. If your set currently has 5 screenshots and you only pass 4 IDs, the omitted screenshot is unlinked from the set. Always ensure your AI assistant includes every screenshot ID you intend to preserve.


Step-by-Step Workflow via FlightDeck

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

    Dev->>AI: "Move screenshot 3 to position 1"
    AI->>FD: app_screenshots_list(localizationId: "...")
    FD->>Apple: GET /v1/appStoreVersionLocalizations/{id}/appScreenshotSets
    Apple-->>FD: Returns screenshot set and ordered IDs: [A, B, C, D]
    FD-->>AI: List of current screenshots
    AI->>Dev: "Current order: [A, B, C, D]. Proposed: [C, A, B, D]. Proceed?"
    Dev->>AI: "Yes, stage reorder"
    AI->>FD: flightdeck_operation_stage("appScreenshotSets_appScreenshots_replaceToManyRelationship", ...)
    Note over FD: Desktop Approval Center surfaces confirmation card
    FD-->>AI: STAGED (Awaiting Desktop Approval)
    AI-->>Dev: "Reordering proposal staged in FlightDeck Desktop"
    Dev->>FD: Inspects new sequence diff & clicks [Approve]
    FD->>Apple: PATCH /v1/appScreenshotSets/{id}/relationships/appScreenshots
    Apple-->>FD: HTTP 204 No Content (Persisted)
    FD-->>Dev: Screenshots reordered successfully!

Step 1: Querying the Screenshot Set ID

Screenshot sets are tied to a specific AppStoreVersionLocalization and display type. The assistant queries app_screenshots_list to isolate the appScreenshotSet resource ID.

Step 2: Formulating the New Ordered Array

The developer reviews the list in chat and indicates the desired changes. The assistant constructs the new data array containing all IDs in the specified order.

Step 3: Staging via FlightDeck Universal Dispatcher

The assistant calls flightdeck_operation_stage. Under FlightDeck's strict human-in-the-loop security, the mutation is staged with a cryptographic SHA-256 fingerprint.

Step 4: Verification and Approval in FlightDeck Desktop

In the FlightDeck Desktop application, the Approval Center surfaces a confirmation card detailing:

  • Operation: Replace App Screenshots Relationship
  • Target Screenshot Set: APP_IPHONE_69 (English U.S.)
  • Action: Reorder 4 screenshots
  • Previous Order: [A, B, C, D]
  • New Order: [C, A, B, D]

Click Approve. FlightDeck immediately delivers the verified relationship patch directly to Apple's API over TLS 1.3.


Troubleshooting Reordering Issues

1. "Cannot modify screenshots on a live version"

  • Cause: Attempting to reorder screenshots when your app is READY_FOR_SALE without an active draft version.
  • Fix: Screenshots are frozen on released versions. You must create a new version draft (e.g., app_store_version_create(versionString: "1.1.0")). Once the draft exists, its screenshot sets become fully editable.

2. "Resource not found or invalid screenshot ID"

  • Cause: One of the IDs in the data array does not exist or belongs to a different screenshot set (e.g., mixing an iPad screenshot ID into an iPhone set).
  • Fix: Verify IDs by running app_screenshots_list immediately before staging. Ensure all IDs belong to the target appScreenshotSet.

3. "Screenshot disappeared after reordering"

  • Cause: The relationship replacement payload omitted one of the existing IDs.
  • Fix: Apple's relationship replace endpoint unlinks omitted IDs. To restore the unlinked screenshot, query appScreenshots_getInstance and stage a new relationship replacement containing all original IDs plus the omitted one.

Security & Verification Safeguards

  • Non-Destructive Guarantee: Reordering via relationship replacement modifies metadata pointers only; it never calls DELETE or purges image files.
  • Human Approval Gate: No relationship changes commit to Apple without explicit confirmation in FlightDeck Desktop.
  • Direct TLS 1.3 Connection: Payloads travel directly from your local Mac to Apple's API servers without intermediate third-party storage.

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