Six App Store Connect rules nobody documents

By Imad Alinajar, FORWHILEDO LLC. August 2026.

At the end of the last post I said the App Store Connect submission lore was probably its own article. This is it.

One thing to be clear about before the list, because it is the part people get wrong when they write these up. None of these is an App Review rejection. The game has never been rejected by App Review. Every item below is either an upload validation rule that stops you before a human ever sees the build, or a piece of App Store Connect interface behaviour that quietly changes what goes live. They are worse than rejections in one specific way: a rejection comes with a written reason, and these do not.

01 Screenshots are refused if they contain an alpha channel

An iOS screenshot, taken on the device or in the Simulator, ships with an alpha channel. It is fully opaque. Nothing is transparent. App Store Connect blocks the upload on the presence of the channel alone, not on whether anything in the image is actually see through.

If you composite your screenshots in any tool that writes RGBA by default, which is nearly all of them, you will hit this. The fix is one line at export: flatten to RGB and drop the channel. In Pillow that is img.convert("RGB") before saving. In ImageMagick it is -alpha off.

The exact wording is Images can't contain alpha channels or transparencies. It is worth reading that carefully, because the natural reading is wrong: it is not asking whether anything is transparent. Every pixel in a screenshot is fully opaque and it is refused anyway. The channel merely existing is the whole objection.

One caution on the fix. Do not flatten through a format that re-encodes the colour, such as a JPEG round trip. Redraw into an opaque bitmap context and re-encode as PNG. Because the source alpha is uniformly 255, the RGB values come out untouched, which is what you want for a screenshot you are about to put on a store page.

02 The in-app purchase review screenshot must be 640 x 920

Every in-app purchase needs a review screenshot, and it has its own required size: 640 x 920. That is not any store screenshot dimension, it is not a device resolution, and Apple's own in-app purchase help page does not state it.

So the obvious move, taking a screenshot of your purchase screen on a phone and uploading it, fails, because a modern iPhone screenshot is nothing like 640 x 920. You have to resize deliberately to a number you have no reason to know.

Two details make this worse than it sounds. First, Apple's help page does document a size for in-app purchases: 1024 x 1024, for the promotional image, which is a different field entirely. That near miss is what sends people down the wrong path, because it looks like the answer. Second, 640 x 920 is a legacy number, roughly an iPhone 4 screen minus the status bar. Marketing screenshots moved to per device class sizes years ago and this one did not, because it is a review artefact rather than a store asset.

A modern phone screenshot is about 0.46 wide by tall, and the target is about 0.70, so scaling the whole thing letterboxes it badly. Crop to the centre first, then resample. The crop is usually an improvement anyway, because it fills the frame with the actual purchase panel instead of background.

03 A new version cannot reuse the build that is already live

Suppose the code is fine and you only want to change screenshots, keywords and the description. Reasonable expectation: create a new version, edit the metadata, submit, no build needed.

App Store Connect hides the currently live build from a new version's build picker. It will show you builds newer than the live one. It will not show you the live one itself. So a metadata only update is not actually available: you need a fresh binary, which means a fresh build number, an archive and an upload, for a change that touches no code at all.

This is worth knowing before you plan a release, because it changes the shape of the work. Since a build is going anyway, any small code fix you were saving for later should ride along. It costs nothing extra in review.

04 The Marketing URL is locked on the live version, and the docs disagree

Some App Store metadata fields can be edited on the live version at any time, with no review. Promotional text is the famous one. Apple's documentation lists the Marketing URL among the editable fields.

In the current App Store Connect interface it is not editable. The field renders greyed with no Edit control, while Copyright, sitting directly beneath it, has one. There is no error and no explanation, just the absence of a link you were told would be there.

The practical rule I now work by: when Apple's documentation and the App Store Connect interface disagree, the interface is right. The docs describe an intended behaviour, the interface describes the current one, and shipping depends on the current one. This was the second time the same lesson arrived; the first was a subcategory that the documentation said existed and the interface did not offer.

05 Promotional text does not carry over to a new version

Promotional text is the one field that publishes to a live listing with no review, so it is the field you use most and think about least.

Create a new version and it comes up blank. It does not inherit from the version that is live. If you do not notice, you will ship a release that silently deletes the promotional text that was working, and nothing anywhere warns you.

Copy it out of the live version before you start, and paste it back verbatim into the new one. Treat that as part of creating any version, not as an optional check.

06 Promo codes cannot gift an in-app purchase

Every version gives you 100 promo codes, and the standard advice for a new app is to send them to reviewers, press and creators. For a free app with a paid unlock, that advice does not survive contact with the system.

• App Store Connect offers App Promo Codes only.
• An app promo code grants exactly what tapping Get already grants. For a free app, that is nothing at all.
• Offer Codes, the mechanism that can grant a purchase, are subscriptions only. A non-consumable unlock cannot be gifted through them.

So if your app is free with a one time unlock, you have 100 codes that do nothing and no supported way to hand out the thing people would actually want. Plan the outreach around that rather than discovering it when a reviewer asks for a code.

The pattern underneath all six

Every one of these is silent. Not one produces a message that tells you what to change. Three stop you at upload with an error about the wrong thing, and three change the outcome without saying anything at all.

Which suggests one working habit worth more than the list itself: before every submission, diff what is about to go live against what is live now, field by field. Not what you think you edited. What the interface currently holds. Two of the six above are invisible to any other check.

The game

All of this was learned shipping ForWhileDo LiRoHop, a free iPhone arcade game where one run passes through five different games: a cloud bouncer, a space flight, a river race, a colour matching board, and a rotation puzzle where gravity always points down so you turn the room instead. Clear the fifth and the run starts again, faster and repainted. 8.6 MB, no ads, no tracking, no account.

ForWhileDo LiRoHop on the App Store · Press kit