> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# App events

# 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.

```bash theme={null} theme={null}
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:**

```bash theme={null} theme={null}
# 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.

```bash theme={null} theme={null}
asc app-events view --event-id "EVENT_ID"
```

**Required Flags:**

* `--event-id` - App event ID

## Create App Event

Create a new in-app event.

```bash theme={null} theme={null}
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](#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](#priority))
* `--purpose` - Purpose: see [Purpose](#purpose) values

**Examples:**

```bash theme={null} theme={null}
# 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.

```bash theme={null} theme={null}
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:**

```bash theme={null} theme={null}
# 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.

```bash theme={null} theme={null}
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:**

```bash theme={null} theme={null}
# 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.

```bash theme={null} theme={null}
# 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.

```bash theme={null} theme={null}
# 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.

```bash theme={null} theme={null}
# 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.

```bash theme={null} theme={null}
asc app-events links --event-id "EVENT_ID"
```

## Submission

Submit an app event for App Store review.

```bash theme={null} theme={null}
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

```bash theme={null} theme={null}
#!/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

```bash theme={null} theme={null}
#!/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

```bash theme={null} theme={null}
# 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)

## Related Commands

* [Apps](/commands/apps) - Manage app metadata
* [Screenshots](/commands/screenshots) - App Store screenshot management

## API Reference

* [App Events](https://sosumi.ai/documentation/appstoreconnectapi/appevent)
* [App Event Localizations](https://sosumi.ai/documentation/appstoreconnectapi/appeventlocalization)
* [App Event Screenshots](https://sosumi.ai/documentation/appstoreconnectapi/appeventscreenshot)
* [App Event Video Clips](https://sosumi.ai/documentation/appstoreconnectapi/appeventvideoclip)