Sanniv Khare 7 min read

App Store Connect API 4.6: deprecations the OpenAPI spec misses

App Store Connect API 4.6: deprecations the OpenAPI spec misses

The short version: App Store Connect API 4.6 (4 November 2026) adds 34 operations for retention messages and offers, and its release notes deprecate the INSTALLS report type on GET /v1/salesReports: “As of November 4, 2026, Apple no longer generates new reports of this type.” The OpenAPI spec for 4.6 still lists INSTALLS as a valid value and marks nothing new as deprecated. The same is true for the screenshot and preview endpoints that 4.5.1 deprecated. If your CI relies on a generated client or on spec validation to warn you, it will not. Grep your scripts by hand; we give a checker below.

We diffed four versions of Apple’s spec, 4.4.1, 4.5, 4.5.1 and 4.6, as kept in the open-source appstoreconnect-swift-sdk repository, which commits each new Apple spec (the 4.6 update is 7afd00b, 4 November). That repo occasionally patches the spec for its code generator; none of the counts below come from those patches.

Why we did this: the release pipelines we run for client banking apps talk to App Store Connect from CI: builds, metadata, screenshots and a nightly sales report pull. We wanted to know which of those calls 4.5 to 4.6 put on notice.

What the three releases added

Release What Apple’s notes add
4.5 GET /v1/apps/{id}/performanceOverviews; Game Center score moderation and blocked players; marketSettings and multiSeatStatus on Subscription; ALL and TWELVE_PLUS in koreaAgeRatingOverride
4.5.1 The App Asset Library (images, videos, placements) and a new IPHONE_DUO display class
4.6 Retention messages, message localizations, retention offers, and a subscription’s retention message relationship

The spec agrees with the additions. Our diff script lists every operation that appears in the newer file and not the older one:

import json, sys
a, b = (json.load(open(p)) for p in sys.argv[1:3])
M = ("get", "post", "patch", "delete")
def ops(s):
    return {(m.upper(), p): o for p, i in s["paths"].items()
            for m, o in i.items() if m in M}
oa, ob = ops(a), ops(b)
print(a["info"]["version"], "->", b["info"]["version"])
for k in sorted(ob.keys() - oa.keys()):
    print("+ op ", *k)
for k in sorted(oa.keys() - ob.keys()):
    print("- op ", *k)
for k in sorted(oa.keys() & ob.keys()):
    if ob[k].get("deprecated") and not oa[k].get("deprecated"):
        print("! deprecated", *k)

From 4.4.1 to 4.5 it finds the 7 new operations the notes describe, all of them performanceOverviews and Game Center moderation. From 4.5 to 4.5.1 it finds 33 (the asset library and its placement relationships on localizations). From 4.5.1 to 4.6 it finds 34, every one under retentionMessages, retentionMessageVersions, retentionMessageLocalizations, retentionOffers or a subscription’s retention relationships. No operation was removed in any of the three steps.

The 4.6 notes name four of those 34 by title (“Create a retention message”, “Create a retention message localization”, “Create a retention offer”, “Replace the retention message for a subscription”); the other 30 are the reads, updates, deletes and relationship endpoints around them. Apple’s 4 November news post adds that “API access is available by request”, so a 4.6 client can see these endpoints before your team is allowed to call them.

The deprecations the spec does not show

Here is the same diff, counted per version:

Terminal output: the spec grows from 1263 to 1337 operations across 4.4.1, 4.5, 4.5.1 and 4.6, while the number of operations marked deprecated stays at 159

Real output from our test server, on the four spec files from the repository’s history.

The 159 operations marked deprecated: true are the same in all four files. Yet the release notes deprecate three things in this window:

Release Deprecated in the notes In the spec
4.5 The territories relationship on app tags and its two endpoints Both endpoints present, not flagged
4.5.1 App Screenshot Sets, App Screenshots, App Preview Sets, App Previews, App Event Screenshots, App Event Video Clips; replaced by the App Asset Library (“Migrating to the App Asset Library”) All 28 of those operations present, none flagged
4.6 The INSTALLS report type on GET /v1/salesReports; historical reports still download INSTALLS still in the filter[reportType] enum, operation not flagged

So the spec is a good source for what was added and a poor one for what is going away. A generated Swift, Kotlin or TypeScript client built from the 4.6 file will compile your INSTALLS call without a warning, and the request will be valid. It will just find no new reports.

The INSTALLS report: what to change in a nightly job

Apple names no replacement for INSTALLS in the 4.6 notes. What the spec offers is the same endpoint with the other report types. Here is the query a nightly job would build, checked against the 4.6 spec’s enums (not sent to Apple):

import json, sys, urllib.parse
spec = json.load(open(sys.argv[1]))
op = spec["paths"]["/v1/salesReports"]["get"]
allowed = {p["name"]: p["schema"]["items"].get("enum")
           for p in op["parameters"] if "items" in p["schema"]}
query = {
    "filter[vendorNumber]": "VENDOR_NUMBER",
    "filter[frequency]": "DAILY",
    "filter[reportType]": "SALES",      # was INSTALLS
    "filter[reportSubType]": "SUMMARY",
    "filter[reportDate]": "2026-11-17",
}
for k, v in query.items():
    ok = allowed.get(k)
    assert ok is None or v in ok, f"{k}={v} not in spec"
print(spec["info"]["version"], "query valid")
print("/v1/salesReports?" + urllib.parse.urlencode(query))

It prints 4.6 query valid. Change SALES back to INSTALLS and it still prints 4.6 query valid, which is the whole problem in one line. Before you switch, check that the SALES summary carries the columns your dashboard read from INSTALLS; that comparison depends on your report and is worth doing against an old INSTALLS file you already downloaded.

A checker for your own scripts

Because the spec will not tell you, we grep. This script lists every call to an endpoint or value that 4.5 to 4.6 deprecated, per file:

import re, sys, pathlib
GONE = {
    r"\bINSTALLS\b": "4.6 salesReports INSTALLS",
    r"/appScreenshotSets|/appScreenshots\b": "4.5.1 screenshots",
    r"/appPreviewSets|/appPreviews\b": "4.5.1 previews",
    r"/appEventScreenshots|/appEventVideoClips": "4.5.1 app events",
    r"appTags/[^\"']*/territories": "4.5 app tag territories",
}
hits = {}
for p in pathlib.Path(sys.argv[1]).rglob("*"):
    if p.suffix not in (".rb", ".py", ".swift", ".ts", ".js", ".sh"):
        continue
    if "spec" in p.parts or "test" in p.parts:
        continue
    s = p.read_text(errors="ignore")
    for pat, why in GONE.items():
        n = len(re.findall(pat, s))
        if n:
            hits.setdefault(why, []).append(
                (str(p.relative_to(sys.argv[1])), n))
for why, files in hits.items():
    print(f"{why}: {sum(n for _, n in files)} in {len(files)} files")
    for f, n in files[:3]:
        print(f"  {f} ({n})")

We ran it on fastlane, which most iOS teams use for uploads:

Terminal output: fastlane's spaceship still calls the screenshot set endpoints 11 times in 2 files and the preview set endpoints 10 times in 1 file

Real output from our test server, fastlane main at 3a9429c.

fastlane’s spaceship client calls the 4.5.1-deprecated screenshot and preview set endpoints in connect_api/tunes/tunes.rb, and deliver builds its screenshot upload on them (upload_screenshots.rb, sync_screenshots.rb). A search of the same checkout for appAssetLibrary finds nothing yet. Deprecated is not removed, and these endpoints still answer; but if your release lane uploads screenshots with deliver, the App Asset Library move is fastlane’s to make, and worth watching in its changelog. No hits for INSTALLS or app tag territories.

What to check on your own setup

  • Run the checker on your release scripts and any internal App Store Connect wrappers. Every hit is a line to plan for.
  • Nightly sales jobs: look for INSTALLS in config files too, not only code; the script above only reads source files, so add .yml or .json if your job keeps report types there.
  • If you generate a client from the spec, read the “Deprecated” section of each release note by hand when you bump the spec. The spec will not mark it.
  • If you want retention messages, request API access first; the endpoints are in the 4.6 spec either way.
  • Watch for 4.6.1 or 4.7 releasing an updated spec. If a later file starts flagging these operations, the diff script above will print them as ! deprecated lines.

Made by the team behind this post

Apps from our studio

  • Goes with this post

    Cardigami

    Pop-up greeting cards that rise out of the fold on iPhone Duo.

    iPhone · App Store

    Get
  • Nix

    The Mac uninstaller that finds what the Trash leaves behind: caches, logs, derived data and saved states.

    macOS

    Get
  • BMDB.fun

    Your Bollywood world at a glance, with links straight to the OTT app that streams each film.

    Android TV · Web · Mobile

    Get
  • OneClick QuitAll

    Quit every running app in one click. See memory and CPU first.

    macOS · Mac App Store

    Get

Need this built? Let’s talk.

We build and run apps for Mac, TV, mobile and the web, and write about what we learn.