Subscriptions

Manage auto-renewable subscription groups and subscriptions in App Store Connect

The subscriptions command provides comprehensive management of auto-renewable subscriptions, including groups, pricing, offers, and submission workflows.

Overview

Auto-renewable subscriptions provide access to content or services on a recurring basis:

Subscription Groups - Collections of subscriptions with different durations and features
Subscriptions - Individual subscription products (weekly, monthly, yearly, etc.)
Pricing - Territory-specific pricing with tier and custom price support
Offers - Introductory offers, promotional offers, and offer codes

Subscription Groups

Subscription groups contain one or more subscription products that provide access to the same level of service.

List Groups

List all subscription groups for an app.

asc subscriptions groups list --app "APP_ID"

Optional Flags:

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

Create Group

Create a new subscription group.

asc subscriptions groups create \
  --app "APP_ID" \
  --reference-name "Premium"

Required Flags:

--app - App ID (or ASC_APP_ID env)
--reference-name - Internal reference name

Get Group Details

asc subscriptions groups view --id "GROUP_ID"

Update Group

asc subscriptions groups update \
  --id "GROUP_ID" \
  --reference-name "Premium Plus"

Delete Group

asc subscriptions groups delete \
  --id "GROUP_ID" \
  --confirm

Warning: Cannot delete groups with active subscriptions.

Group Localizations

Manage group display names for different locales.

# Create localization
asc subscriptions groups localizations create \
  --group-id "GROUP_ID" \
  --locale "en-US" \
  --name "Premium Subscription" \
  --custom-app-name "Premium App"

# List localizations
asc subscriptions groups localizations list \
  --group-id "GROUP_ID"

# Update localization
asc subscriptions groups localizations update \
  --id "LOCALIZATION_ID" \
  --name "Premium Plus Subscription"

# Delete localization
asc subscriptions groups localizations delete \
  --id "LOCALIZATION_ID" \
  --confirm

Subscriptions

List Subscriptions

List all subscriptions in a group.

asc subscriptions list --group-id "GROUP_ID"

Optional Flags:

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

Create Subscription

Create a new subscription product.

asc subscriptions create \
  --group-id "GROUP_ID" \
  --reference-name "Monthly" \
  --product-id "com.example.sub.monthly" \
  --subscription-period ONE_MONTH

Required Flags:

--group - Subscription group ID
--ref-name - Reference name
--product-id - Product ID (must match bundle ID prefix)

Optional Flags:

--subscription-period - Duration:
- ONE_WEEK
- ONE_MONTH
- TWO_MONTHS
- THREE_MONTHS
- SIX_MONTHS
- ONE_YEAR
--family-sharable - Enable Family Sharing (cannot be undone)

Examples:

# Create monthly subscription
asc subscriptions create \
  --group-id "GROUP_ID" \
  --reference-name "Monthly Premium" \
  --product-id "com.example.app.monthly"

# Create yearly subscription with Family Sharing
asc subscriptions create \
  --group-id "GROUP_ID" \
  --reference-name "Yearly Premium" \
  --product-id "com.example.app.yearly" \
  --subscription-period ONE_YEAR \
  --family-sharable

Get Subscription

asc subscriptions view --id "SUB_ID"

Update Subscription

asc subscriptions update \
  --id "SUB_ID" \
  --reference-name "Monthly Premium Plus"

Optional Flags:

--ref-name - New reference name
--subscription-period - New duration
--family-sharable - Enable Family Sharing

Delete Subscription

asc subscriptions delete --id "SUB_ID" --confirm

Pricing

View Pricing Overview

View pricing for all subscriptions in an app.

asc subscriptions pricing summary --app "APP_ID"

Optional Flags:

--territory - Filter by territory (e.g., USA)
--output - Output format: json, table, markdown

Example:

# View pricing as table
asc subscriptions pricing summary \
  --app "APP_ID" \
  --output table

# View USA pricing only
asc subscriptions pricing summary \
  --app "APP_ID" \
  --territory "USA" \
  --output table

List Prices

List current prices for a subscription.

asc subscriptions pricing prices list --subscription-id "SUB_ID"

Optional Flags:

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

Set Price

Add or change pricing for a subscription.

asc subscriptions pricing prices set \
  --subscription-id "SUB_ID" \
  --price-point "PRICE_POINT_ID"

Required Flags:

--subscription-id - Subscription ID

Price Selection (choose one):

--price-point - Specific price point ID
--tier - Pricing tier number (requires --territory)
--price - Customer price (requires --territory)

Optional Flags:

--territory - Territory ID (e.g., USA) - required for --tier or --price
--start-date - Price change start date (YYYY-MM-DD)
--preserved - Preserve existing customer pricing
--refresh - Force refresh of tier cache

Examples:

# Set price using price point ID
asc subscriptions pricing prices set \
  --subscription-id "SUB_ID" \
  --price-point "abc-123-def"

# Set price using tier
asc subscriptions pricing prices set \
  --subscription-id "SUB_ID" \
  --tier 5 \
  --territory "USA"

# Set price using exact customer price
asc subscriptions pricing prices set \
  --subscription-id "SUB_ID" \
  --price "4.99" \
  --territory "USA"

# Schedule future price change
asc subscriptions pricing prices set \
  --subscription-id "SUB_ID" \
  --tier 8 \
  --territory "USA" \
  --start-date "2026-06-01" \
  --preserved

Initial vs. Change Pricing:

First price: Uses PATCH /subscriptions/{id} with inline price resources
Price changes: Uses POST /subscriptionPrices for existing subscriptions

The CLI automatically detects which method to use.

Import Prices

Import prices for multiple territories from a CSV file.

asc subscriptions pricing prices import \
  --subscription-id "SUB_ID" \
  --input "./prices.csv"

CSV Format:

territory,price
USA,4.99
CAN,6.99
GBR,3.99
AUS,7.99

Optional Flags:

--start-date - Price change start date
--preserved - Preserve existing customer pricing

Delete Price

asc subscriptions pricing prices delete \
  --price-id "PRICE_ID" \
  --confirm

Price Points

Work with subscription price points and tiers.

# List price points for territory
asc subscriptions pricing price-points list \
  --subscription-id "SUB_ID"

# Get price point details
asc subscriptions pricing price-points view \
  --price-point-id "PRICE_POINT_ID"

Availability

Control which territories can purchase your subscriptions.

Get Availability

asc subscriptions pricing availability view --availability-id "AVAILABILITY_ID"
# or
asc subscriptions pricing availability view --subscription-id "SUB_ID"

Set Availability

asc subscriptions pricing availability edit \
  --subscription-id "SUB_ID" \
  --territories "USA,CAN,GBR"

Optional Flags:

--available-in-new-territories - Automatically include new App Store territories

List Available Territories

asc subscriptions pricing availability available-territories \
  --availability-id "AVAILABILITY_ID" \
  --paginate

Localizations

Manage subscription display names and descriptions.

# Create localization
asc subscriptions localizations create \
  --subscription-id "SUB_ID" \
  --locale "en-US" \
  --name "Monthly Premium" \
  --description "Get unlimited access to all premium features"

# List localizations
asc subscriptions localizations list \
  --subscription-id "SUB_ID"

# Update localization
asc subscriptions localizations update \
  --id "LOCALIZATION_ID" \
  --name "Monthly Premium Plus"

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

Promotional Images

Upload promotional images for subscriptions.

# Upload image
asc subscriptions images create \
  --subscription-id "SUB_ID" \
  --file "./promo.png"

# List images
asc subscriptions images list --subscription-id "SUB_ID"

# Delete image
asc subscriptions images delete --id "IMAGE_ID" --confirm

Image Requirements:

Format: PNG or JPG
Size: 1024 x 1024 pixels
Color space: RGB
Maximum file size: 4MB

Introductory Offers

Offer discounted pricing to new subscribers.

# Create introductory offer
asc subscriptions offers introductory create \
  --subscription-id "SUB_ID" \
  --offer-duration ONE_MONTH \
  --offer-mode FREE_TRIAL \
  --number-of-periods 1

# Import introductory offers from CSV
asc subscriptions offers introductory import \
  --subscription-id "SUB_ID" \
  --input "./offers.csv" \
  --offer-duration ONE_WEEK \
  --offer-mode FREE_TRIAL \
  --number-of-periods 1

# Update offer
asc subscriptions offers introductory update \
  --id "OFFER_ID" \
  --end-date "2026-02-01"

# Delete offer
asc subscriptions offers introductory delete \
  --id "OFFER_ID" \
  --confirm

CSV format:

Required column: territory
Optional columns: offer_mode, offer_duration, number_of_periods, start_date, end_date, price_point_id
Header alias: price_point -> price_point_id
Territory values may be 3-letter ASC IDs, 2-letter country codes, or English territory names
Row values override command-level defaults, so a territory-only CSV can inherit a shared offer shape from flags

Offer Types:

FREE_TRIAL - Free access for specified duration
PAY_AS_YOU_GO - Discounted price per period
PAY_UP_FRONT - Single upfront payment for multiple periods

Promotional Offers

Create targeted offers for existing or lapsed subscribers.

# Create promotional offer
asc subscriptions offers promotional create \
  --subscription-id "SUB_ID" \
  --name "Win-Back Spring 2024" \
  --offer-code "SPRING2024"

# List promotional offers
asc subscriptions offers promotional list \
  --subscription-id "SUB_ID"

# Delete promotional offer
asc subscriptions offers promotional delete \
  --id "OFFER_ID" \
  --confirm

Offer Codes

Generate subscription offer codes for marketing campaigns.

# Create offer code
asc subscriptions offers offer-codes create \
  --subscription-id "SUB_ID" \
  --name "LAUNCH50" \
  --offer-eligibility STACK_WITH_INTRO_OFFERS \
  --customer-eligibilities NEW \
  --offer-duration ONE_MONTH \
  --offer-mode FREE_TRIAL \
  --number-of-periods 1 \
  --prices "USA:PRICE_POINT_ID"

# List offer codes
asc subscriptions offers offer-codes list \
  --subscription-id "SUB_ID"

App Store Review

Manage review screenshots for subscription approval.

# Upload review screenshot
asc subscriptions review screenshots create \
  --subscription-id "SUB_ID" \
  --file "./screenshot.png"

# View App Store review screenshot
asc subscriptions review app-store-screenshot view \
  --subscription-id "SUB_ID" \

Grace Periods

Configure billing grace periods for failed payment recovery.

# Set grace period
asc subscriptions grace-periods update \
  --id "GRACE_PERIOD_ID" \
  --duration SIXTEEN_DAYS \
  --opt-in true \
  --sandbox-opt-in true

# View grace period settings
asc subscriptions grace-periods view \
  --id "GRACE_PERIOD_ID"

Promoted Subscriptions

Promote subscriptions on your App Store product page.

# List promoted subscriptions
asc subscriptions promoted-purchases list \
  --app "APP_ID"

# View promoted subscription
asc subscriptions promoted-purchases view \
  --promoted-purchase-id "PROMO_ID"

# Create promoted subscription
asc subscriptions promoted-purchases create \
  --app "APP_ID" \
  --product-id "SUB_ID" \
  --visible-for-all-users true

# Link promoted subscription to the app
asc subscriptions promoted-purchases link \
  --app "APP_ID" \
  --promoted-purchase-id "PROMO_ID"

Submission

Submit subscription groups or individual subscriptions for review.

# Submit subscription group
asc subscriptions review submit-group \
  --group-id "GROUP_ID" \
  --confirm

# Submit individual subscription
asc subscriptions review submit \
  --subscription-id "SUB_ID" \
  --confirm

Common Workflows

Create Complete Subscription Tier

#!/bin/bash
# Create a full subscription tier (monthly, yearly)

APP_ID="123456789"
BUNDLE_ID="com.example.app"

# 1. Create subscription group
GROUP_RESPONSE=$(asc subscriptions groups create \
  --app "$APP_ID" \
  --reference-name "Premium" \
  --output json)

GROUP_ID=$(echo "$GROUP_RESPONSE" | jq -r '.data.id')

# 2. Create monthly subscription
MONTHLY_RESPONSE=$(asc subscriptions create \
  --group-id "$GROUP_ID" \
  --reference-name "Monthly Premium" \
  --product-id "${BUNDLE_ID}.monthly" \
  --subscription-period ONE_MONTH \
  --output json)

MONTHLY_ID=$(echo "$MONTHLY_RESPONSE" | jq -r '.data.id')

# 3. Create yearly subscription
YEARLY_RESPONSE=$(asc subscriptions create \
  --group-id "$GROUP_ID" \
  --reference-name "Yearly Premium" \
  --product-id "${BUNDLE_ID}.yearly" \
  --subscription-period ONE_YEAR \
  --output json)

YEARLY_ID=$(echo "$YEARLY_RESPONSE" | jq -r '.data.id')

# 4. Set pricing
asc subscriptions pricing prices set \
  --subscription-id "$MONTHLY_ID" \
  --tier 5 \
  --territory "USA"

asc subscriptions pricing prices set \
  --subscription-id "$YEARLY_ID" \
  --tier 40 \
  --territory "USA"

echo "Created subscription group: $GROUP_ID"
echo "Monthly subscription: $MONTHLY_ID"
echo "Yearly subscription: $YEARLY_ID"

Bulk Price Update

#!/bin/bash
# Update pricing across all subscriptions

GROUP_ID="abc-123-def"
NEW_TIER=8
START_DATE="2026-06-01"

# Get all subscriptions in group
SUBS=$(asc subscriptions list \
  --group-id "$GROUP_ID" \
  --paginate \
  --output json | jq -r '.data[].id')

# Update each subscription
for SUB_ID in $SUBS; do
  echo "Updating $SUB_ID"
  asc subscriptions pricing prices set \
    --subscription-id "$SUB_ID" \
    --tier "$NEW_TIER" \
    --territory "USA" \
    --start-date "$START_DATE" \
    --preserved
done

Export Subscription Catalog

# Export all subscription groups and subscriptions
asc subscriptions groups list \
  --app "$APP_ID" \
  --paginate \
  --output json \
  > subscription-groups.json

# Format for review
jq '[.data[] | {id: .id, name: .attributes.referenceName}]' subscription-groups.json

Best Practices

Subscription Structure

Group subscriptions that provide similar access levels
Offer at least two durations (e.g., monthly and yearly)
Provide value incentive for longer commitments (e.g., yearly at 20% discount)
Limit to 1-2 subscription groups per app

Pricing Strategy

Research competitor pricing in key markets
Consider regional price adjustments for purchasing power parity
Use preserved pricing when raising prices to retain existing subscribers
Test introductory offers to improve conversion

Offer Strategy

Use free trials to reduce friction for new subscribers
Target win-back offers to lapsed subscribers
Limit offer code distribution to avoid devaluing your subscription
A/B test offer durations and discount levels

Metadata

Localize all subscription metadata for supported languages
Clearly communicate what subscribers get
Use promotional images to showcase value
Update screenshots to reflect current features

In-App Purchases - One-time and consumable purchases
Apps - App metadata and settings
Pricing - Territory pricing and tiers

Overview

App Management

TestFlight & Builds

Monetization & Analytics

Signing

Review & Release

Team & Access

Automation & Utilities

Documentation Index

​Subscriptions

​Overview

​Subscription Groups

​List Groups

​Create Group

​Get Group Details

​Update Group

​Delete Group

​Group Localizations

​Subscriptions

​List Subscriptions

​Create Subscription

​Get Subscription

​Update Subscription

​Delete Subscription

​Pricing

​View Pricing Overview

​List Prices

​Set Price

​Import Prices

​Delete Price

​Price Points

​Availability

​Get Availability

​Set Availability

​List Available Territories

​Localizations

​Promotional Images

​Introductory Offers

​Promotional Offers

​Offer Codes

​App Store Review

​Grace Periods

​Promoted Subscriptions

​Submission

​Common Workflows

​Create Complete Subscription Tier

​Bulk Price Update

​Export Subscription Catalog

​Best Practices

​Subscription Structure

​Pricing Strategy

​Offer Strategy

​Metadata

​Related Commands

​API Reference

Subscriptions

Overview

Subscription Groups

List Groups

Create Group

Get Group Details

Update Group

Delete Group

Group Localizations

Subscriptions

List Subscriptions

Create Subscription

Get Subscription

Update Subscription

Delete Subscription

Pricing

View Pricing Overview

List Prices

Set Price

Import Prices

Delete Price

Price Points

Availability

Get Availability

Set Availability

List Available Territories

Localizations

Promotional Images

Introductory Offers

Promotional Offers

Offer Codes

App Store Review

Grace Periods

Promoted Subscriptions

Submission

Common Workflows

Create Complete Subscription Tier

Bulk Price Update

Export Subscription Catalog

Best Practices

Subscription Structure

Pricing Strategy

Offer Strategy

Metadata

Related Commands

API Reference