Skip to main content

Subscription Setup Guide

Complete walkthrough for setting up auto-renewable subscriptions using asc-cli.

Prerequisites​

Before starting:

  1. App exists in App Store Connect
  2. API credentials configured (Authentication)
  3. Subscription groups created in App Store Connect (required via web UI)
Subscription Groups

Subscription groups must be created in App Store Connect web UI. The CLI cannot create groups directly, but can manage subscriptions within existing groups.

Step 1: Understand Your App​

List Your Apps​

asc apps list
Bundle ID                    Name             SKU
live.yooz.whisper           Yooz Whisper     YOOZWHISPER

Get App Details​

asc apps info live.yooz.whisper

Step 2: View Existing Subscriptions​

List Subscription Groups​

asc subscriptions list live.yooz.whisper
Group: Premium Features (ID: 123456)
  └── live.yooz.whisper.pro.monthly (READY_TO_SUBMIT)
  └── live.yooz.whisper.pro.yearly (READY_TO_SUBMIT)

Group: Family Plan (ID: 123457)
  └── live.yooz.whisper.family.monthly (READY_TO_SUBMIT)

Step 3: Set Up Pricing​

Check Current Pricing​

asc subscriptions pricing list live.yooz.whisper.pro.monthly

Set Monthly Pricing​

# Preview first
asc subscriptions pricing set live.yooz.whisper.pro.monthly \
  --price 2.99 \
  --dry-run

# Apply
asc subscriptions pricing set live.yooz.whisper.pro.monthly \
  --price 2.99

Set Yearly Pricing​

Typically 10-20% discount vs monthly:

# $2.99/month = $35.88/year
# $29.99/year = ~17% discount

asc subscriptions pricing set live.yooz.whisper.pro.yearly \
  --price 29.99

Verify Pricing​

asc subscriptions pricing list live.yooz.whisper.pro.monthly
asc subscriptions pricing list live.yooz.whisper.pro.yearly

Step 4: Add Introductory Offers​

Add Free Trial to Monthly​

asc subscriptions offers create live.yooz.whisper.pro.monthly \
  --type free-trial \
  --duration 2w \
  --all

Add Free Trial to Yearly​

Shorter trial for higher-value subscription:

asc subscriptions offers create live.yooz.whisper.pro.yearly \
  --type free-trial \
  --duration 1w \
  --all

Add Promotional Pricing (Optional)​

For users who've already used a trial:

asc subscriptions offers create live.yooz.whisper.pro.monthly \
  --type pay-as-you-go \
  --duration 3m \
  --price 1.99 \
  --all

Verify Offers​

asc subscriptions offers list live.yooz.whisper.pro.monthly
asc subscriptions offers list live.yooz.whisper.pro.yearly

Step 5: Complete Setup with YAML​

For reproducible configuration, use YAML:

Generate Template​

asc bulk init --output subscriptions.yaml

Configure YAML​

# subscriptions.yaml
app_bundle_id: live.yooz.whisper

subscriptions:
  # Pro Monthly
  - product_id: live.yooz.whisper.pro.monthly
    name: Pro Monthly
    price_usd: 2.99
    territories: all
    equalize: true
    offers:
      - type: free-trial
        duration: 2w
        territories: all
      - type: pay-as-you-go
        duration: 3m
        price_usd: 1.99
        territories: all

  # Pro Yearly
  - product_id: live.yooz.whisper.pro.yearly
    name: Pro Yearly
    price_usd: 29.99
    territories: all
    equalize: true
    offers:
      - type: free-trial
        duration: 1w
        territories: all

  # Family Monthly
  - product_id: live.yooz.whisper.family.monthly
    name: Family Monthly
    price_usd: 6.99
    territories: all
    offers:
      - type: free-trial
        duration: 2w
        territories: all

Validate Configuration​

asc bulk validate subscriptions.yaml

Apply Configuration​

# Preview
asc bulk apply subscriptions.yaml --dry-run

# Apply
asc bulk apply subscriptions.yaml

Step 6: Verify Complete Setup​

Check All Subscriptions​

asc subscriptions list live.yooz.whisper --verbose

Export Current Configuration​

asc subscriptions export live.yooz.whisper --output current-config.yaml

Compare with your YAML to verify everything matches.

Common Subscription Patterns​

Basic Tier (Monthly Only)​

subscriptions:
  - product_id: app.basic.monthly
    price_usd: 1.99
    offers:
      - type: free-trial
        duration: 1w

Standard Tier (Monthly + Yearly)​

subscriptions:
  - product_id: app.pro.monthly
    price_usd: 4.99
    offers:
      - type: free-trial
        duration: 2w

  - product_id: app.pro.yearly
    price_usd: 39.99  # ~33% savings
    offers:
      - type: free-trial
        duration: 1w

Premium Tier with Aggressive Offers​

subscriptions:
  - product_id: app.premium.monthly
    price_usd: 9.99
    offers:
      - type: free-trial
        duration: 1m
      - type: pay-as-you-go
        duration: 3m
        price_usd: 4.99

  - product_id: app.premium.yearly
    price_usd: 79.99  # ~33% savings
    offers:
      - type: free-trial
        duration: 2w
      - type: pay-up-front
        duration: 1y
        price_usd: 49.99

Troubleshooting​

Pricing Not Applying​

Error: Cannot set pricing - subscription not in valid state

Solution: Subscription must be in READY_TO_SUBMIT or higher state. Check subscription status in App Store Connect.

Offer Already Exists​

Error: A free-trial offer already exists for this subscription

Solution: Delete existing offer first:

asc subscriptions offers list SUB_ID
asc subscriptions offers delete OFFER_ID --force

Territory Issues​

Error: Territory XYZ not valid for this subscription

Solution: Some territories may have restrictions. Try without that territory:

asc subscriptions pricing set SUB_ID --price 2.99 --all --exclude XYZ

Version Control​

Keep your subscription YAML in version control:

# .gitignore
# Don't ignore - this should be versioned
!subscriptions.yaml

# Do ignore credentials
.asc-credentials
*.p8

Create commit after setup:

git add subscriptions.yaml
git commit -m "Configure subscription pricing and offers"

CI/CD Integration​

Automate subscription updates:

# .github/workflows/subscriptions.yml
name: Update Subscriptions
on:
  push:
    paths:
      - 'subscriptions.yaml'
    branches:
      - main

jobs:
  apply:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install asc-cli
        run: pip install asc-cli

      - name: Apply subscriptions
        env:
          ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
          ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
          ASC_PRIVATE_KEY: ${{ secrets.ASC_PRIVATE_KEY }}
        run: asc bulk apply subscriptions.yaml

Next Steps​