App Store Submission

Publish with publish appstore --submit, then use validate or submit for follow-up checks

Automate the complete App Store submission process with the canonical high-level publish command, then use the lower-level submission lifecycle commands to inspect or cancel review state when needed.

Overview

Use these surfaces deliberately:

asc publish appstore --submit - canonical App Store publish path
asc release stage - prepare a version without submitting it
asc validate - canonical readiness check before submission
asc submit status - inspect submission or version review state
asc submit cancel - cancel an active submission

In 1.0, the deprecated asc submit preflight and deprecated asc submit create paths were removed. Use the Migrate to 1.0 guide if you are updating older scripts.

Prerequisites

Before submitting, ensure you have:

A processed build uploaded to App Store Connect
App Store version created with required metadata
All localizations configured with required fields
Screenshots uploaded for at least one device type
Privacy information and app review details completed

Canonical Publish Workflow

Prepare your app version

Create an App Store version if it doesn’t exist:

asc versions create \
  --app "YOUR_APP_ID" \
  --version "1.0.0" \
  --platform IOS

Or list existing versions:

asc versions list --app "YOUR_APP_ID" --platform IOS

Verify localization metadata

The CLI automatically validates that required localization fields are present:

Description
Keywords
What’s New text
Marketing URL (if applicable)

Update missing localizations:

asc app-setup info set \
  --app "YOUR_APP_ID" \
  --locale "en-US" \
  --name "My App" \
  --subtitle "Amazing app subtitle" \
  --privacy-policy-url "https://example.com/privacy"

Update version-specific metadata:

asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --description "Full app description" \
  --keywords "productivity,tools,utility" \
  --whats-new "Bug fixes and improvements"

Find your build ID

List builds for your app version:

asc builds list \
  --app "YOUR_APP_ID" \
  --version "1.0.0" \
  --build-number "42" \
  --output json

Or get the latest build:

asc builds list \
  --app "YOUR_APP_ID" \
  --sort "-uploadedDate" \
  --limit 1

Run the publish command

Publish with the canonical App Store flow:

asc publish appstore \
  --app "YOUR_APP_ID" \
  --ipa "./build/MyApp.ipa" \
  --version "1.0.0" \
  --submit \
  --confirm

Use asc release stage instead when you want the same preparation flow without creating the review submission yet:

asc release stage \
  --app "YOUR_APP_ID" \
  --version "1.0.0" \
  --build "BUILD_ID" \
  --copy-metadata-from "0.9.0" \
  --confirm

Lower-level submission lifecycle

Use the submit command family when you need to inspect or manage the review submission itself instead of running the full publish pipeline.

Validate readiness

asc validate --app "YOUR_APP_ID" --version "1.0.0"

Monitoring Submission Status

Check submission status

Using submission ID:

asc submit status --id "SUBMISSION_ID"

Using version ID:

asc submit status --version-id "VERSION_ID"

Check version state

View detailed version information:

asc versions view --version-id "VERSION_ID" --output json

asc versions view is the canonical command here. If older scripts still use the deprecated asc versions get, update them during your 1.0 migration.The version state indicates the current stage:

PREPARE_FOR_SUBMISSION: Metadata incomplete
WAITING_FOR_REVIEW: Submitted, awaiting review
IN_REVIEW: Currently being reviewed
PENDING_DEVELOPER_RELEASE: Approved, awaiting your release
READY_FOR_SALE: Live on the App Store
REJECTED: Rejected by review team

Managing Submissions

Cancel a Submission

If you need to cancel a submission before review:

asc submit cancel --id "SUBMISSION_ID" --confirm

Or cancel using version ID:

asc submit cancel --version-id "VERSION_ID" --confirm

You can only cancel submissions that are in WAITING_FOR_REVIEW state. Once review begins, you cannot cancel.

Resubmit After Changes

If you need to make changes after submitting:

Cancel the current submission

asc submit cancel --version-id "VERSION_ID" --confirm

Make your changes

Update metadata, upload new screenshots, or attach a different build as needed.

Resubmit

asc publish appstore \
  --app "YOUR_APP_ID" \
  --ipa "./build/MyApp.ipa" \
  --version "1.0.0" \
  --submit \
  --confirm

Complete Example: iOS App Submission

Here’s a complete workflow for publishing an iOS app:

#!/bin/bash
set -e

# Configuration
export ASC_APP_ID="YOUR_APP_ID"
VERSION="1.0.0"
PLATFORM="IOS"

# 1. Find or create the app version
echo "Creating version $VERSION..."
VERSION_RESPONSE=$(asc versions create \
  --app "$ASC_APP_ID" \
  --version "$VERSION" \
  --platform "$PLATFORM" \
  --output json 2>/dev/null || true)

# Extract version ID (adjust based on actual JSON structure)
VERSION_ID=$(echo "$VERSION_RESPONSE" | jq -r '.data.id')

if [ -z "$VERSION_ID" ]; then
  echo "Version already exists, fetching ID..."
  VERSION_ID=$(asc versions list \
    --app "$ASC_APP_ID" \
    --platform "$PLATFORM" \
    --output json | jq -r '.data[] | select(.attributes.versionString == "'$VERSION'") | .id' | head -1)
fi

echo "Version ID: $VERSION_ID"

# 2. Get the latest build
echo "Finding latest build..."
BUILD_ID=$(asc builds list \
  --app "$ASC_APP_ID" \
  --sort "-uploadedDate" \
  --limit 1 \
  --output json | jq -r '.data[0].id')

echo "Build ID: $BUILD_ID"

# 3. Update localizations (example for en-US)
echo "Updating localizations..."
asc localizations update \
  --version "$VERSION_ID" \
  --locale "en-US" \
  --description "Your app description here" \
  --keywords "productivity,tools" \
  --whats-new "Bug fixes and performance improvements"

# 4. Run the canonical publish command
echo "Submitting for review..."
asc publish appstore \
  --app "$ASC_APP_ID" \
  --ipa "./build/MyApp.ipa" \
  --version "$VERSION" \
  --submit \
  --confirm

echo "Submission complete!"

# 5. Check status
asc submit status --version-id "$VERSION_ID"

Preflight Validation

The CLI performs automatic preflight checks before submission:

Localization Validation

Checks that all required fields are present for each localization:

Description
Keywords
What’s New text (for updates)

If any fields are missing, the submission will fail with a detailed error:

Submit preflight failed: submission-blocking localization fields are missing:
  - en-US: description, keywords
  - es-ES: whats-new
Fix these with `asc apps info edit` (optionally using `--copy-from-locale`) before retrying `asc validate` or `asc publish appstore --submit`.

Fixing Validation Errors

Copy complete localization from one locale to another:

asc apps info edit \
  --app "YOUR_APP_ID" \
  --locale "es-ES" \
  --copy-from-locale "en-US"

Then update locale-specific fields:

asc localizations update \
  --version "VERSION_ID" \
  --locale "es-ES" \
  --description "Descripción de la aplicación" \
  --keywords "productividad,herramientas"

Troubleshooting

”No app store version localizations found”

Problem: The version has no localizations configured. Solution: Add at least one localization:

asc localizations update \
  --version "VERSION_ID" \
  --locale "en-US" \
  --description "App description" \
  --keywords "keyword1,keyword2" \
  --whats-new "What's new in this version"

“Failed to attach build”

Problem: The build may not be compatible with the version or is still processing. Solution: Verify build status:

asc builds info --build-id "BUILD_ID"

Ensure the build:

Has finished processing
Matches the app ID
Supports the correct platform
Has passed automatic checks

”Stale review submission found”

Problem: A previous submission attempt left an orphaned submission. Solution: The CLI automatically cancels stale submissions. If you see this warning, it’s informational and the new submission will proceed.

Submission Rejected

If your submission is rejected:

Check rejection details in App Store Connect web interface
Address the issues mentioned in the rejection
Upload a new build if code changes are needed, or just update metadata
Resubmit with the canonical publish command:

asc publish appstore \
  --app "YOUR_APP_ID" \
  --ipa "./build/MyApp.ipa" \
  --version "1.0.0" \
  --submit \
  --confirm

Platform-Specific Considerations

macOS Apps

For macOS apps, specify the MAC_OS platform:

asc publish appstore \
  --app "YOUR_APP_ID" \
  --ipa "./build/MyMacApp.ipa" \
  --version "1.0.0" \
  --platform MAC_OS \
  --submit \
  --confirm

tvOS Apps

For tvOS apps, use the TV_OS platform:

asc publish appstore \
  --app "YOUR_APP_ID" \
  --ipa "./build/MyTVApp.ipa" \
  --version "1.0.0" \
  --platform TV_OS \
  --submit \
  --confirm

visionOS Apps

For visionOS apps, use the VISION_OS platform:

asc publish appstore \
  --app "YOUR_APP_ID" \
  --ipa "./build/MyVisionApp.ipa" \
  --version "1.0.0" \
  --platform VISION_OS \
  --submit \
  --confirm

Best Practices

Always use --confirm flag: Prevents accidental submissions
Test with TestFlight first: Distribute to internal testers before submitting to the App Store
Validate metadata beforehand: Use asc localizations list to verify all required fields are present
Monitor submission status: Check status regularly during the review process
Keep builds ready: Have builds processed and ready before starting the submission workflow
Use version IDs for lifecycle automation: Version IDs are reliable for submit status and submit cancel
Handle stale submissions: The CLI automatically cleans up orphaned submissions, but verify in case of errors

TestFlight Distribution - Test builds before App Store submission
Metadata Management - Manage app metadata and localizations
Screenshots - Upload App Store screenshots
Build Management - Manage and monitor builds

Getting Started

Core Concepts

Guides

CI/CD Integration

Configuration

App store submission

App Store Submission

Overview

Prerequisites

Canonical Publish Workflow

Lower-level submission lifecycle

Validate readiness

Monitoring Submission Status

Managing Submissions

Cancel a Submission

Resubmit After Changes

Complete Example: iOS App Submission

Preflight Validation

Localization Validation

Fixing Validation Errors

Troubleshooting

”No app store version localizations found”

“Failed to attach build”

”Stale review submission found”

Submission Rejected

Platform-Specific Considerations

macOS Apps

tvOS Apps

visionOS Apps

Best Practices

​App Store Submission

​Overview

​Prerequisites

​Canonical Publish Workflow

​Lower-level submission lifecycle

​Validate readiness

​Monitoring Submission Status

​Managing Submissions

​Cancel a Submission

​Resubmit After Changes

​Complete Example: iOS App Submission

​Preflight Validation

​Localization Validation

​Fixing Validation Errors

​Troubleshooting

​”No app store version localizations found”

​“Failed to attach build”

​”Stale review submission found”

​Submission Rejected

​Platform-Specific Considerations

​macOS Apps

​tvOS Apps

​visionOS Apps

​Best Practices

​Related Commands

App Store Submission

Overview

Prerequisites

Canonical Publish Workflow

Lower-level submission lifecycle

Validate readiness

Monitoring Submission Status

Managing Submissions

Cancel a Submission

Resubmit After Changes

Complete Example: iOS App Submission

Preflight Validation

Localization Validation

Fixing Validation Errors

Troubleshooting

”No app store version localizations found”

“Failed to attach build”

”Stale review submission found”

Submission Rejected

Platform-Specific Considerations

macOS Apps

tvOS Apps

visionOS Apps

Best Practices

Related Commands