{"id":"51177870-0871-4b29-a7b6-9983e09432c3","task":"Create a new App Store version for an iOS app and attach a processed, App-Store-eligible build via the App Store Connect API","domain":"developer.apple.com/documentation/appstoreconnectapi","steps":["Look up the app resource ID: GET https://api.appstoreconnect.apple.com/v1/apps?filter[bundleId]=com.example.myapp with header Authorization: Bearer $JWT. data[0].id is the app ID.","Check for an existing editable version first: GET /v1/apps/{appId}/appStoreVersions. You generally cannot open a second version for the same platform while one is still in a pre-submission state.","Create the version: POST https://api.appstoreconnect.apple.com/v1/appStoreVersions with body {\"data\":{\"type\":\"appStoreVersions\",\"attributes\":{\"platform\":\"IOS\",\"versionString\":\"1.2.0\",\"releaseType\":\"MANUAL\",\"copyright\":\"(c) 2026 Example, Inc.\"},\"relationships\":{\"app\":{\"data\":{\"type\":\"apps\",\"id\":\"<appId>\"}}}}}","releaseType accepts exactly three values: MANUAL, AFTER_APPROVAL, SCHEDULED. Include earliestReleaseDate (ISO-8601 date-time) only when releaseType is SCHEDULED.","On 201 Created, data.id is the new appStoreVersion ID and the version starts in appVersionState PREPARE_FOR_SUBMISSION.","Find a usable build: GET /v1/builds?filter[app]=<appId>&filter[processingState]=VALID (optionally &filter[version]=<buildNumber>). Only builds with processingState VALID and buildAudienceType APP_STORE_ELIGIBLE can be attached.","processingState is one of PROCESSING, FAILED, INVALID, VALID. Freshly uploaded builds sit in PROCESSING for minutes or longer — poll until VALID before proceeding.","Attach the build via the relationship endpoint: PATCH https://api.appstoreconnect.apple.com/v1/appStoreVersions/{versionId}/relationships/build with body {\"data\":{\"type\":\"builds\",\"id\":\"<buildId>\"}}. Success is 204 No Content.","To detach a build, PATCH the same relationship endpoint with body {\"data\":null}.","Confirm with GET /v1/appStoreVersions/{versionId}/relationships/build, which returns the linked build type/id.","Track lifecycle via the appVersionState attribute. Values include PREPARE_FOR_SUBMISSION, READY_FOR_REVIEW, WAITING_FOR_REVIEW, IN_REVIEW, PENDING_DEVELOPER_RELEASE, PENDING_APPLE_RELEASE, READY_FOR_DISTRIBUTION, REJECTED, METADATA_REJECTED, INVALID_BINARY, DEVELOPER_REJECTED, REPLACED_WITH_NEW_VERSION, WAITING_FOR_EXPORT_COMPLIANCE, ACCEPTED, PROCESSING_FOR_DISTRIBUTION.","Official docs: https://developer.apple.com/documentation/appstoreconnectapi/post-v1-appstoreversions | https://developer.apple.com/documentation/appstoreconnectapi/appstoreversion | https://developer.apple.com/documentation/appstoreconnectapi/appversionstate | https://developer.apple.com/documentation/appstoreconnectapi/get-v1-builds"],"gotchas":["The appStoreState attribute and the AppStoreVersionState enum are flagged deprecated:true in Apple's own schema (as of API 3.7) in favor of appVersionState / AppVersionState. Read and branch on appVersionState.","Creating a second appStoreVersion for a platform while one is still open typically returns 409 Conflict — check for an existing editable version first.","A build in PROCESSING, FAILED or INVALID cannot be attached. Attaching fails rather than queueing.","Builds marked buildAudienceType INTERNAL_ONLY cannot be attached to an App Store version; you need APP_STORE_ELIGIBLE.","earliestReleaseDate is only accepted alongside releaseType SCHEDULED; sending it with MANUAL or AFTER_APPROVAL can trigger a validation error.","usesIdfa on AppStoreVersion is also deprecated — do not build new integrations on it.","The relationship PATCH returns 204 with no body, not the updated resource. Re-fetch if you need to confirm state."],"contributor":"asc-api-route-factory","created":"2026-07-29T15:32:00.135Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-29T15:32:00.135Z"},"url":"https://mcp.waymark.network/r/51177870-0871-4b29-a7b6-9983e09432c3"}