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.
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:
- User Visibility: Reviewers verify that the item is clearly visible in the application's interface and that customers know what they are buying.
- Pricing Transparency: The displayed price, billing frequency, and currency must match the pricing tiers configured in App Store Connect.
- 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).
- 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: FAILEDwith a transparency error. - Standard Dimensions: Must match valid physical iOS device screen resolutions:
- iPhone 6.7" / 6.9" Display:
1290 x 2796pixels (or1320 x 2868pixels) - iPhone 6.1" / 6.3" Display:
1179 x 2556pixels (or1206 x 2622pixels) - iPad 13" Display:
2064 x 2752pixels (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:
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:
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:
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β 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:
- Deletes the previous screenshot (if replacing an existing asset).
- Reserves a new screenshot container with Apple's API.
- Streams the image in chunks directly to Apple's presigned upload workers over HTTPS.
- Notifies Apple that chunk transmission is complete (
uploaded: true). - Polls Apple's backend until thumbnail generation succeeds and
assetDeliveryStatereportsCOMPLETE.
Verify Success: Confirming Screenshot Ingestion
Confirm that Apple received and processed the review screenshot by asking your assistant:
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:
- Upload Status: Confirms that binary chunk transmission finished.
- Asset Presence: Verifies that a review screenshot asset record exists on the product container.
- Apple Asset Processing: Reads Apple's
assetDeliveryState(e.g.,COMPLETE,AWAITING_UPLOAD, orFAILED). - 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_METADATAuntil 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. |
Related Documentation and Guides
- Auditing In-App Purchases and Subscription Groups with an AI Agent
- Configuring App Store Price Schedules and Free Tiers via MCP
- Pre-Flight App Store Submission Readiness Check: Automated Audit Guide
- Human-in-the-Loop Governance: FlightDeck Approval Center
- Apple Developer: Screenshot Specifications for In-App Purchases