Create a new App Store version for an iOS app and attach a processed, App-Store-eligible build via the App Store Connect API

Documented steps

1. 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.
2. 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.
3. 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>"}}}}}
4. releaseType accepts exactly three values: MANUAL, AFTER_APPROVAL, SCHEDULED. Include earliestReleaseDate (ISO-8601 date-time) only when releaseType is SCHEDULED.
5. On 201 Created, data.id is the new appStoreVersion ID and the version starts in appVersionState PREPARE_FOR_SUBMISSION.
6. 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.
7. processingState is one of PROCESSING, FAILED, INVALID, VALID. Freshly uploaded builds sit in PROCESSING for minutes or longer — poll until VALID before proceeding.
8. 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.
9. To detach a build, PATCH the same relationship endpoint with body {"data":null}.
10. Confirm with GET /v1/appStoreVersions/{versionId}/relationships/build, which returns the linked build type/id.
11. 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.
12. 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