Subscriptions

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 get --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

List Subscriptions

List all subscriptions in a group.

asc subscriptions list --group "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 "GROUP_ID" \
  --ref-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 "GROUP_ID" \
  --ref-name "Monthly Premium" \
  --product-id "com.example.app.monthly"

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

Get Subscription

asc subscriptions get --id "SUB_ID"

Update Subscription

asc subscriptions update \
  --id "SUB_ID" \
  --ref-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 --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 \
  --app "APP_ID" \
  --output table

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

List Prices

List current prices for a subscription.

asc subscriptions prices list --id "SUB_ID"

Optional Flags:

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

Add Price

Add or change pricing for a subscription.

asc subscriptions prices add \
  --id "SUB_ID" \
  --price-point "PRICE_POINT_ID"

Required Flags:

--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:

# Add price using price point ID
asc subscriptions prices add \
  --id "SUB_ID" \
  --price-point "abc-123-def"

# Add price using tier
asc subscriptions prices add \
  --id "SUB_ID" \
  --tier 5 \
  --territory "USA"

# Add price using exact customer price
asc subscriptions prices add \
  --id "SUB_ID" \
  --price "4.99" \
  --territory "USA"

# Schedule future price change
asc subscriptions prices add \
  --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 prices import \
  --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 prices delete \
  --price-id "PRICE_ID" \
  --confirm

Price Points

Work with subscription price points and tiers.

# List price points for territory
asc subscriptions price-points list \
  --territory "USA"

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

Availability

Control which territories can purchase your subscriptions.

Get Availability

asc subscriptions availability get --id "AVAILABILITY_ID"
# or
asc subscriptions availability get --subscription-id "SUB_ID"

Set Availability

asc subscriptions availability set \
  --id "SUB_ID" \
  --territory "USA,CAN,GBR"

Optional Flags:

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

List Available Territories

asc subscriptions availability available-territories \
  --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 introductory-offers create \
  --subscription-id "SUB_ID" \
  --duration ONE_MONTH \
  --offer-type FREE_TRIAL \
  --number-of-periods 1

# Update offer
asc subscriptions introductory-offers update \
  --id "OFFER_ID" \
  --duration ONE_WEEK

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

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 promotional-offers create \
  --subscription-id "SUB_ID" \
  --name "Win-Back Spring 2024" \
  --offer-code "SPRING2024"

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

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

Offer Codes

Generate subscription offer codes for marketing campaigns.

# Create offer code
asc subscriptions offer-codes create \
  --subscription-id "SUB_ID" \
  --name "LAUNCH50" \
  --customer-eligibility NEW_AND_EXISTING \
  --number-of-codes 500

# List offer codes
asc subscriptions 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"

# Alternative command (same functionality)
asc subscriptions app-store-review-screenshot create \
  --subscription-id "SUB_ID" \
  --file "./screenshot.png"

Grace Periods

Configure billing grace periods for failed payment recovery.

# Set grace period
asc subscriptions grace-periods set \
  --subscription-id "SUB_ID" \
  --opt-in true \
  --sandbox-opt-in true

# Get grace period settings
asc subscriptions grace-periods get \
  --subscription-id "SUB_ID"

Promoted Subscriptions

Promote subscriptions on your App Store product page.

# Get promoted subscription
asc subscriptions promoted-purchase get \
  --subscription-id "SUB_ID"

# Create promoted subscription
asc subscriptions promoted-purchase create \
  --app "APP_ID" \
  --subscription-id "SUB_ID" \
  --visibility SHOW

# Update promotion order
asc subscriptions promoted-purchase update-order \
  --app "APP_ID" \
  --subscription-ids "SUB1,SUB2,SUB3"

Submission

Submit subscription groups or individual subscriptions for review.

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

# Submit individual subscription
asc subscriptions submit \
  --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 "$GROUP_ID" \
  --ref-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 "$GROUP_ID" \
  --ref-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 prices add \
  --id "$MONTHLY_ID" \
  --tier 5 \
  --territory "USA"

asc subscriptions prices add \
  --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 "$GROUP_ID" \
  --paginate \
  --output json | jq -r '.data[].id')

# Update each subscription
for SUB_ID in $SUBS; do
  echo "Updating $SUB_ID"
  asc subscriptions prices add \
    --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

Authentication

App Management

TestFlight & Builds

Review & Release

Media

Code Signing

Analytics & Reports

Monetization

Automation

Additional Commands

​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

​Add 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

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

Add 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