App Events

Manage App Store in-app events for your iOS apps

The app-events command provides management of in-app events, which are timely occurrences in your app or game that you can showcase on the App Store.

Overview

In-app events help users discover engaging experiences within your app:

Event Types - Challenges, competitions, live events, major updates, new seasons, and premieres
Scheduling - Set start/end times and publish dates
Territories - Control where events appear
Localizations - Provide event details in multiple languages
Media - Showcase events with screenshots and video previews

List App Events

List all in-app events for an app.

asc app-events list --app "APP_ID"

Required Flags:

--app - App ID (or ASC_APP_ID env)

Optional Flags:

--limit - Results per page (1-200)
--paginate - Fetch all pages
--next - Pagination URL

Example:

# List all events
asc app-events list --app "123456789"

# Fetch all pages
asc app-events list \
  --app "123456789" \
  --paginate

Get Event Details

Retrieve details for a specific event.

asc app-events view --event-id "EVENT_ID"

Required Flags:

--event-id - App event ID

Create App Event

Create a new in-app event.

asc app-events create \
  --app "APP_ID" \
  --name "Summer Challenge" \
  --event-type CHALLENGE \
  --start "2026-06-01T00:00:00Z" \
  --end "2026-06-30T23:59:59Z"

Required Flags:

--app - App ID (or ASC_APP_ID env)
--name - Reference name (internal identifier)
--event-type - Event badge type (see Event Types)

Optional Flags:

--start - Event start time (RFC3339 format)
--end - Event end time (RFC3339 format)
--publish-start - Publish start time (when event appears on App Store)
--territories - Comma-separated territory codes (e.g., USA,CAN,GBR)
--deep-link - Deep link URL to open event in app
--purchase-requirement - Currently supported: NO_COST_ASSOCIATED
--primary-locale - Primary locale (e.g., en-US)
--priority - Priority: HIGH, NORMAL (see Priority)
--purpose - Purpose: see Purpose values

Examples:

# Create basic challenge event
asc app-events create \
  --app "123456789" \
  --name "Summer Challenge" \
  --event-type CHALLENGE \
  --start "2026-06-01T00:00:00Z" \
  --end "2026-06-30T23:59:59Z"

# Create high-priority premiere
asc app-events create \
  --app "123456789" \
  --name "Season 2 Launch" \
  --event-type PREMIERE \
  --priority HIGH \
  --purpose ATTRACT_NEW_USERS \
  --territories "USA,CAN,GBR"

# Create live event with deep link
asc app-events create \
  --app "123456789" \
  --name "Championship Finals" \
  --event-type LIVE_EVENT \
  --start "2026-07-15T18:00:00Z" \
  --end "2026-07-15T21:00:00Z" \
  --deep-link "myapp://event/championship" \
  --priority HIGH

Update App Event

Update an existing app event.

asc app-events update \
  --event-id "EVENT_ID" \
  --priority HIGH

Required Flags:

--event-id - Event ID to update

Optional Flags:

--name - Reference name
--event-type - Event badge type
--start - Event start time
--end - Event end time
--publish-start - Publish start time
--territories - Territory codes
--deep-link - Deep link URL
--purchase-requirement - Purchase requirement
--primary-locale - Primary locale
--priority - Priority level
--purpose - Event purpose

Examples:

# Update priority
asc app-events update \
  --event-id "EVENT_ID" \
  --priority HIGH

# Update event type and name
asc app-events update \
  --event-id "EVENT_ID" \
  --name "Updated Challenge" \
  --event-type SPECIAL_EVENT

# Update purchase requirement
asc app-events update \
  --event-id "EVENT_ID" \
  --purchase-requirement NO_COST_ASSOCIATED

Delete App Event

Delete an app event.

asc app-events delete \
  --event-id "EVENT_ID" \
  --confirm

Required Flags:

--event-id - Event ID to delete
--confirm - Confirm deletion

Event Types

Event types determine the badge shown on the App Store:

CHALLENGE - In-app challenges or quests
COMPETITION - Competitive events or tournaments
LIVE_EVENT - Live streaming or real-time events
MAJOR_UPDATE - Significant app updates
NEW_SEASON - New season or content drops
PREMIERE - Content or feature premieres
SPECIAL_EVENT - Other special occasions

Badge Selection:

Choose the badge that best represents your event
Users filter events by type on the App Store
Consistent badge usage improves discoverability

Priority

Priority determines event prominence on the App Store:

HIGH - Featured prominently; limited to 5 active events per app
NORMAL - Standard display; no limit on active events

Best Practices:

Reserve HIGH priority for your most important events
Plan ahead to stay within the 5-event limit
Use NORMAL for recurring or minor events

Purpose

Purpose helps App Store Connect categorize your event:

APPROPRIATE_FOR_ALL_USERS - Suitable for all audiences
ATTRACT_NEW_USERS - Designed to attract new users
BRING_BACK_LAPSED_USERS - Re-engage inactive users
KEEP_ACTIVE_USERS_INFORMED - Keep current users engaged

Date and Time Format

All dates use RFC3339 format with UTC timezone:

YYYY-MM-DDTHH:MM:SSZ

Examples:

2026-06-01T00:00:00Z - June 1, 2026 at midnight UTC
2026-07-15T18:30:00Z - July 15, 2026 at 6:30 PM UTC

Converting from Local Time:

# Convert from local time to UTC
date -u -d "2026-06-01 10:00:00 EST" +"%Y-%m-%dT%H:%M:%SZ"
# Output: 2026-06-01T15:00:00Z

Localizations

Provide localized event details for different languages.

# Create localization
asc app-events localizations create \
  --event-id "EVENT_ID" \
  --locale "en-US" \
  --name "Summer Challenge" \
  --short-description "Compete for exclusive rewards" \
  --long-description "Join the biggest summer challenge ever!"

# List localizations
asc app-events localizations list --event-id "EVENT_ID"

# Update localization
asc app-events localizations update \
  --localization-id "LOCALIZATION_ID" \
  --name "Updated Event Name"

# Delete localization
asc app-events localizations delete \
  --localization-id "LOCALIZATION_ID" \
  --confirm

Required Fields:

Name (30 characters max)
Short description (50 characters max)
Long description (120 characters max)

Screenshots

Upload event screenshots to showcase your event.

# Upload screenshot
asc app-events screenshots create \
  --event-id "EVENT_ID" \
  --locale "en-US" \
  --path "./event-screenshot.png" \
  --asset-type EVENT_DETAILS_PAGE

# List screenshots
asc app-events screenshots list \
  --localization-id "LOCALIZATION_ID"

# Delete screenshot
asc app-events screenshots delete \
  --screenshot-id "SCREENSHOT_ID" \
  --confirm

Screenshot Requirements:

Format: PNG or JPG
Dimensions: Match device screen sizes (e.g., 1284 x 2778 for iPhone 13 Pro Max)
Maximum file size: 8MB
Minimum: 1 screenshot per localization
Maximum: 8 screenshots per localization

Video Clips

Add video previews to highlight your event.

# Create video clip
asc app-events video-clips create \
  --event-id "EVENT_ID" \
  --locale "en-US" \
  --path "./event-preview.mov" \
  --asset-type EVENT_DETAILS_PAGE \
  --preview-frame-time-code "00:00:02.500"

# List video clips
asc app-events video-clips list \
  --localization-id "LOCALIZATION_ID"

# Delete video clip
asc app-events video-clips delete \
  --clip-id "VIDEO_ID" \
  --confirm

Video Requirements:

Format: .mov, .mp4, .m4v
Duration: 15-30 seconds
Resolution: Minimum 1920 x 1080
Maximum file size: 500MB
Frame rate: 23.976-30 fps

Relationships

View relationships between events and other resources.

asc app-events links --event-id "EVENT_ID"

Submission

Submit an app event for App Store review.

asc app-events submit --event-id "EVENT_ID" --confirm

Requirements before submission:

At least one localization
At least one screenshot per localization
Event dates configured
All required metadata fields completed

Common Workflows

Create Complete Event

#!/bin/bash
# Create a fully configured app event

APP_ID="123456789"

# 1. Create event
EVENT_RESPONSE=$(asc app-events create \
  --app "$APP_ID" \
  --name "Summer Championship" \
  --event-type COMPETITION \
  --start "2026-06-01T00:00:00Z" \
  --end "2026-06-30T23:59:59Z" \
  --priority HIGH \
  --purpose ATTRACT_NEW_USERS \
  --territories "USA,CAN,GBR" \
  --output json)

EVENT_ID=$(echo "$EVENT_RESPONSE" | jq -r '.data.id')

# 2. Add English localization
LOC_RESPONSE=$(asc app-events localizations create \
  --event-id "$EVENT_ID" \
  --locale "en-US" \
  --name "Summer Championship" \
  --short-description "Compete for the ultimate prize" \
  --long-description "Join players worldwide in the biggest summer championship event. Win exclusive rewards!" \
  --output json)

LOC_ID=$(echo "$LOC_RESPONSE" | jq -r '.data.id')

# 3. Upload screenshots
for i in {1..3}; do
  asc app-events screenshots create \
    --event-id "$EVENT_ID" \
    --locale "en-US" \
    --path "./screenshots/event-${i}.png" \
    --asset-type EVENT_DETAILS_PAGE
done

# 4. Submit for review
asc app-events submit --event-id "$EVENT_ID" --confirm

echo "Event created and submitted: $EVENT_ID"

Schedule Seasonal Events

#!/bin/bash
# Create quarterly seasonal events

APP_ID="123456789"

# Spring Event
asc app-events create \
  --app "$APP_ID" \
  --name "Spring Festival" \
  --event-type NEW_SEASON \
  --start "2026-03-20T00:00:00Z" \
  --end "2026-04-20T23:59:59Z" \
  --priority HIGH

# Summer Event
asc app-events create \
  --app "$APP_ID" \
  --name "Summer Games" \
  --event-type COMPETITION \
  --start "2026-06-21T00:00:00Z" \
  --end "2026-07-21T23:59:59Z" \
  --priority HIGH

# Fall Event
asc app-events create \
  --app "$APP_ID" \
  --name "Autumn Challenge" \
  --event-type CHALLENGE \
  --start "2026-09-22T00:00:00Z" \
  --end "2026-10-22T23:59:59Z" \
  --priority HIGH

# Winter Event
asc app-events create \
  --app "$APP_ID" \
  --name "Winter Wonderland" \
  --event-type SPECIAL_EVENT \
  --start "2026-12-21T00:00:00Z" \
  --end "2027-01-21T23:59:59Z" \
  --priority HIGH

Export Event Schedule

# Export all events to JSON
asc app-events list \
  --app "$APP_ID" \
  --paginate \
  --output json \
  > events-schedule.json

# Format for calendar view
jq '[.data[] | {name: .attributes.referenceName, badge: .attributes.badge, start: .attributes.territorySchedules[0].eventStart, end: .attributes.territorySchedules[0].eventEnd, priority: .attributes.priority}] | sort_by(.start)' events-schedule.json

Best Practices

Event Planning

Plan events at least 2 weeks in advance for review
Align event timing with actual in-app content availability
Don’t overlap too many high-priority events
Consider timezone differences for global audiences

Event Types

Choose the most accurate badge type
Be consistent with badge usage across similar events
Don’t use “Major Update” for minor changes
Reserve “Live Event” for truly live experiences

Localizations

Localize for all languages your app supports
Keep descriptions concise and compelling
Highlight what makes the event unique
Use action-oriented language

Media

Show actual event content, not generic app screenshots
Use high-quality images that stand out
Include a video for high-priority events
Update media to reflect current event state

Timing

Set publish start before event start to build anticipation
Don’t set event end too far in the future (reduces urgency)
Update or remove events that are delayed
Archive completed events promptly

Limitations

Maximum 5 high-priority events active at once
Maximum 10 total active events per app
Events must be approved before they appear on the App Store
Minimum event duration: No enforced minimum (use judgment)
Maximum event duration: No enforced maximum (shorter events typically perform better)

Apps - Manage app metadata
Screenshots - App Store screenshot management

Overview

App Management

TestFlight & Builds

Monetization & Analytics

Signing

Review & Release

Team & Access

Automation & Utilities

App events

App Events

Overview

List App Events

Get Event Details

Create App Event

Update App Event

Delete App Event

Event Types

Priority

Purpose

Date and Time Format

Localizations

Screenshots

Video Clips

Relationships

Submission

Common Workflows

Create Complete Event

Schedule Seasonal Events

Export Event Schedule

Best Practices

Event Planning

Event Types

Localizations

Media

Timing

Limitations

API Reference

​App Events

​Overview

​List App Events

​Get Event Details

​Create App Event

​Update App Event

​Delete App Event

​Event Types

​Priority

​Purpose

​Date and Time Format

​Localizations

​Screenshots

​Video Clips

​Relationships

​Submission

​Common Workflows

​Create Complete Event

​Schedule Seasonal Events

​Export Event Schedule

​Best Practices

​Event Planning

​Event Types

​Localizations

​Media

​Timing

​Limitations

​Related Commands

​API Reference

App Events

Overview

List App Events

Get Event Details

Create App Event

Update App Event

Delete App Event

Event Types

Priority

Purpose

Date and Time Format

Localizations

Screenshots

Video Clips

Relationships

Submission

Common Workflows

Create Complete Event

Schedule Seasonal Events

Export Event Schedule

Best Practices

Event Planning

Event Types

Localizations

Media

Timing

Limitations

Related Commands

API Reference