Skip to main content
Pricing, subscriptions, and availability Level: Intermediate 11 min read

Uploading In-App Purchase Review Screenshots via FlightDeck MCP

Learn how to resolve 'Missing Metadata' on In-App Purchases and subscriptions by uploading App Review proof screenshots with FlightDeck MCP.

Published: 2026-11-01 • Last Updated: 2026-11-01 • Author: Kip Lawrence
Key MCP Tools: monetization_review_screenshot_uploadiap_review_screenshot_getsubscription_review_screenshot_get

Overview: Resolving "Missing Metadata" on IAPs and Subscriptions

When creating an In-App Purchase (IAP) or auto-renewable subscription in App Store Connect, developers frequently encounter the MISSING_METADATA status flag. Even after filling out product identifiers, localized titles, descriptions, and pricing tiers, App Store Connect refuses to allow the product to be submitted for review.

In almost all cases, this happens because Apple requires a Review Screenshot (also called "review proof") for every new monetization product before review specialists can evaluate it.

Through FlightDeck connected to your AI coding assistant (such as Cursor, Claude Code, Xcode with MCP, or Antigravity), you can inspect whether a product already has a review screenshot, stage the upload of an updated paywall image, and verify Apple's backend processingβ€”all through natural-language prompts.

Warning

Critical Destructive-Replacement Warning:

Apple's API strictly permits only one review screenshot per product. When you replace an existing review screenshot, FlightDeck must delete the old asset on Apple's servers before Apple completes validation of the new image's dimensions, colorspace, or alpha channel.

If the new upload fails Apple's ingestion validation, or if a network interruption aborts the transfer, the previous screenshot is permanently gone from Apple's servers and cannot be recovered. The product reverts to MISSING_METADATA. Human approval in FlightDeck does not make the replacement reversible. Always maintain a local backup of your previously approved screenshots before replacing them.


Why Apple Requires Review Proof Screenshots

Apple's App Store Review team must verify that digital purchases meet App Store Review Guidelines (specifically Guidelines 3.1.1 and 3.1.2) before allowing them to be sold to the public.

A review screenshot provides Apple reviewers with proof of:

  1. User Visibility: Reviewers verify that the item is clearly visible in the application's interface and that customers know what they are buying.
  2. Pricing Transparency: The displayed price, billing frequency, and currency must match the pricing tiers configured in App Store Connect.
  3. Mandatory Subscription Terms: For auto-renewable subscriptions, the paywall screenshot must show the title of the service, subscription duration, renewal terms, and functional links to both the Privacy Policy and Terms of Use (EULA).
  4. Authentic App UI: The screenshot must be an uncropped capture of the running app interface where the purchase is triggeredβ€”not a marketing graphic, promotional banner, or logo.

Review Screenshots vs. Public Storefront Screenshots

A frequent point of confusion is mistaking review screenshots for standard App Store display assets:

Characteristic In-App Purchase Review Screenshot Public App Store Screenshot (appScreenshots)
Audience Apple App Review Staff Only (Confidential) Public Customers on the App Store product page
Purpose Proof of in-app paywall, terms, and purchase button Marketing and product showcase across device form factors
Visibility Never visible to end users on the App Store Publicly browsable in search results and storefronts
Required For Any new IAP or subscription product App version submission across required display sizes


Technical Image Specifications

Before uploading, prepare an authentic screenshot of your app's paywall or purchase flow meeting Apple's criteria:

  • Format: High-resolution PNG or flattened RGB JPEG.
  • Transparency / Alpha Channel: No alpha channel. If an image contains an alpha channel (transparency), Apple's processing pipeline flags assetDeliveryState: FAILED with a transparency error.
  • Standard Dimensions: Must match valid physical iOS device screen resolutions:
  • iPhone 6.7" / 6.9" Display: 1290 x 2796 pixels (or 1320 x 2868 pixels)
  • iPhone 6.1" / 6.3" Display: 1179 x 2556 pixels (or 1206 x 2622 pixels)
  • iPad 13" Display: 2064 x 2752 pixels (for iPad-only or universal apps)
  • Content: The actual paywall screen as rendered on an iPhone or iPad, without simulator window frames, desktop chrome, or device mockups.

The Primary Prompt: Inspect and Upload a Review Screenshot

Connect your AI coding assistant to FlightDeck and paste the following prompt:

TEXT
Please help me upload an App Review proof screenshot for my In-App Purchase using FlightDeck:

Target Product ID: [e.g., focusflow_monthly_sub]
Target Product Type: [subscription OR inAppPurchase]
Screenshot File Path: [/absolute/path/to/paywall_screenshot.png]

Instructions:
1. First, check if a review screenshot is already attached to this product in App Store Connect.
2. If an existing screenshot exists, WARN me explicitly that replacing it is a destructive action that deletes the old screenshot on Apple's servers before Apple validates the new file.
3. Validate that the local image exists and is a non-empty PNG or JPEG.
4. Stage the upload proposal for my approval in the FlightDeck Desktop Approval Center.
5. Once I approve the proposal, monitor the upload until Apple marks processing as COMPLETE.
6. Confirm that the screenshot appears on the product, report Apple's asset processing state, and report any remaining missing review metadata without assuming the product immediately leaves MISSING_METADATA.

What Happens Behind the Prompt

When you run this prompt, your assistant guides the asset through Apple's ingestion sequence:

TEXT
Developer Prompt: "Inspect and upload review screenshot for [Product]"
                                β”‚
                                β–Ό
       [1. Existing Asset Check & Safety Audit]
       Assistant checks iap_review_screenshot_get or
       subscription_review_screenshot_get to detect pre-existing assets
                                β”‚
                                β–Ό
       [2. FlightDeck Desktop Approval Center]
       Developer reviews product ID, file path, and replacement warnings
                                β”‚
                                β–Ό
       [3. Atomic Deletion (if replacing) & Asset Reservation]
       FlightDeck creates Apple asset record and streams binary parts
                                β”‚
                                β–Ό
       [4. Verification & Processing Readback]
       Assistant polls Apple until assetDeliveryState reports COMPLETE

1. Existing Asset Inspection

Your assistant calls iap_review_screenshot_get or subscription_review_screenshot_get to determine whether an asset is already attached.

  • If no asset exists, it proceeds directly to staging.
  • If an asset already exists, it issues a prominent warning in chat, reminding you that Apple requires deleting the existing asset before reserving a new one.

2. Desktop Approval Center Authorization

Because modifying store assets alters your live account, FlightDeck creates a staged proposal card in the native Approval Center on your Mac.

Illustrative representation of the FlightDeck Approval Center sheet:

TEXT
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  FlightDeck Approval Center: Review Screenshot Upload                 β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Target: Subscription (ID: focusflow_monthly_sub)                     β”‚
β”‚  File Path: /Users/dev/assets/paywall_1290x2796.png                   β”‚
β”‚  File Size: 1.2 MB                                                     β”‚
β”‚                                                                        β”‚
β”‚  Existing Screenshot: None (Initial upload)                           β”‚
β”‚  Action: Reserve asset container and stream PNG parts to Apple.        β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                       [ Reject ]      [ Approve ]                      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

You inspect the file path and target product ID, then click Approve.

3. Direct Streaming and Apple Backend Validation

Upon approval, FlightDeck handles the multi-step asset delivery pipeline:

  1. Deletes the previous screenshot (if replacing an existing asset).
  2. Reserves a new screenshot container with Apple's API.
  3. Streams the image in chunks directly to Apple's presigned upload workers over HTTPS.
  4. Notifies Apple that chunk transmission is complete (uploaded: true).
  5. Polls Apple's backend until thumbnail generation succeeds and assetDeliveryState reports COMPLETE.

Verify Success: Confirming Screenshot Ingestion

Confirm that Apple received and processed the review screenshot by asking your assistant:

TEXT
Check the review screenshot status for product [focusflow_monthly_sub] on [Your App Name]. Verify upload completion, confirm that the screenshot is attached to the product, report Apple's asset processing state, and report any remaining missing review metadata.

What Your Assistant Reports:

  1. Upload Status: Confirms that binary chunk transmission finished.
  2. Asset Presence: Verifies that a review screenshot asset record exists on the product container.
  3. Apple Asset Processing: Reads Apple's assetDeliveryState (e.g., COMPLETE, AWAITING_UPLOAD, or FAILED).
  4. Remaining Metadata Status: Reports whether the product has satisfied all other prerequisites (localized description, display name, base pricing tier). If pricing or description fields are still empty, the product legitimately remains in MISSING_METADATA until those are supplied.

First-Time IAP Submissions vs. Subsequent Updates

Keep in mind Apple's procedural rule regarding when digital purchases are evaluated:

  • First In-App Purchase for an App: Must be submitted attached to a new app binary version. You cannot submit your app's first IAP for standalone review. When preparing your version 1.0.0 release submission, link the new IAP products under "In-App Purchases and Subscriptions" on the version page before submitting.
  • Subsequent In-App Purchases: Once an app has at least one approved IAP live on the App Store, subsequent products can be submitted for standalone review at any time without compiling a new binary.

Troubleshooting In-App Purchase Screenshot Uploads

Error Symptom Cause Resolution
Asset processing failed (Transparency error) The PNG file contains an alpha channel (transparency). Open the image in Preview, export as PNG with the "Alpha" checkbox unchecked, or save as a flattened high-quality JPEG.
Product remains in MISSING_METADATA Missing pricing tier or localized description. A review screenshot is only one requirement. Verify that the product also has a pricing tier and at least one active localization.
HTTP 409 Conflict during upload An asset reservation is already open or stuck in Apple's queue. Wait a few minutes for Apple's queue to settle, or inspect the existing screenshot status via chat.
Simulator Window Chrome in Screenshot Reviewer rejected screenshot for non-standard UI elements. Crop the image so only the native iOS screen contents (status bar down to home indicator) are visible. Remove desktop window shadows or frames.

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