Skip to main content

YAML Schema Reference

Complete reference for YAML configuration files used with asc bulk commands.

Quick Start​

Generate a template:

asc bulk init --output subscriptions.yaml

Full Example​

# subscriptions.yaml
# Configuration for asc-cli bulk operations

# Required: Your app's bundle identifier
app_bundle_id: live.yooz.whisper

# Optional: Preview mode (default: false)
dry_run: false

# Optional: Continue on errors (default: false)
continue_on_error: false

# Optional: Verbose output (default: false)
verbose: false

# Required: List of subscription configurations
subscriptions:
  # Pro Monthly subscription
  - product_id: live.yooz.whisper.pro.monthly
    name: Pro Monthly
    description: Monthly Pro subscription
    price_usd: 2.99
    territories: all
    equalize: true
    offers:
      # Free trial
      - type: free-trial
        duration: 2w
        territories: all

      # Promotional pricing
      - type: pay-as-you-go
        duration: 3m
        price_usd: 1.99
        territories: all

  # Pro Yearly subscription
  - product_id: live.yooz.whisper.pro.yearly
    name: Pro Yearly
    description: Yearly Pro subscription with savings
    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:
      - USA
      - CAN
      - GBR
      - AUS
    offers:
      - type: free-trial
        duration: 2w

Root Configuration​

FieldTypeRequiredDefaultDescription
app_bundle_idstringYes-App bundle identifier
subscriptionsarrayYes-List of subscription configs
dry_runbooleanNofalsePreview without applying
continue_on_errorbooleanNofalseContinue if one subscription fails
verbosebooleanNofalseShow detailed output

Example​

app_bundle_id: com.example.app
dry_run: true
continue_on_error: true
verbose: true
subscriptions:
  - # ...

Subscription Configuration​

FieldTypeRequiredDefaultDescription
product_idstringYes-App Store product ID
namestringNo-Display name (informational)
descriptionstringNo-Description (informational)
price_usdnumberYes-Base price in USD
territoriesstring/arrayNo"all"Target territories
equalizebooleanNotrueUse Apple price equalization
offersarrayNo[]Introductory offers

Example​

subscriptions:
  - product_id: com.example.pro.monthly
    name: Pro Monthly
    description: Full access, billed monthly
    price_usd: 4.99
    territories: all
    equalize: true
    offers:
      - # ...

Territories​

All Territories​

Apply to all 175 App Store territories:

territories: all

Specific Territories​

List of ISO 3166-1 alpha-3 codes:

territories:
  - USA
  - CAN
  - GBR
  - DEU
  - FRA
  - AUS
  - JPN

Common Territory Codes​

CodeCountry
USAUnited States
CANCanada
GBRUnited Kingdom
DEUGermany
FRAFrance
ITAItaly
ESPSpain
NLDNetherlands
AUSAustralia
JPNJapan
CHNChina
KORSouth Korea
BRABrazil
MEXMexico
INDIndia

Get full list:

asc subscriptions pricing territories

Introductory Offers​

FieldTypeRequiredDefaultDescription
typestringYes-Offer type
durationstringYes-Offer duration
price_usdnumberConditional-Price (required for paid offers)
territoriesstring/arrayNoInheritsTarget territories

Offer Types​

TypeDescriptionRequires Price
free-trialFree access for durationNo
pay-as-you-goDiscounted price per periodYes
pay-up-frontOne-time payment for durationYes

Duration Format​

FormatDescription
3d3 days
1w1 week
2w2 weeks
1m1 month
2m2 months
3m3 months
6m6 months
1y1 year

Free Trial Example​

offers:
  - type: free-trial
    duration: 2w
    territories: all

Pay-As-You-Go Example​

offers:
  - type: pay-as-you-go
    duration: 3m
    price_usd: 1.99
    territories: all

Pay-Up-Front Example​

offers:
  - type: pay-up-front
    duration: 6m
    price_usd: 9.99
    territories: all

Multiple Offers​

offers:
  # Free trial for new users
  - type: free-trial
    duration: 2w
    territories: all

  # Discounted rate after trial
  - type: pay-as-you-go
    duration: 3m
    price_usd: 0.99
    territories: all

Price Configuration​

subscriptions:
  - product_id: app.pro.monthly
    price_usd: 2.99
    equalize: true
    territories: all

Apple calculates equivalent prices for all territories.

Without Equalization​

For custom per-territory pricing:

subscriptions:
  - product_id: app.pro.monthly
    price_usd: 2.99
    equalize: false
    territories:
      - USA

Then set other territories separately via CLI.

Valid Price Points​

USD prices must match Apple price points:

USDTier
$0.9910
$1.9930
$2.9960
$3.9970
$4.9980
$5.9990
$6.99100
$7.99110
$8.99120
$9.99130
$14.99160
$19.99180
$29.99200
$49.99250
$99.99350

Get full list: asc subscriptions pricing points

Validation​

Validate Configuration​

asc bulk validate subscriptions.yaml

Common Validation Errors​

Missing required field:

Error: 'product_id' is required for subscription at index 0

Invalid price:

Error: price_usd 2.50 does not match any Apple price point
Nearest: 2.49 or 2.99

Invalid territory:

Error: Unknown territory code: UK
Did you mean: GBR (United Kingdom)?

Invalid duration:

Error: Duration '5d' not valid for free-trial
Valid options: 3d, 1w, 2w, 1m, 2m, 3m, 6m, 1y

IDE Integration​

JSON Schema​

Export for editor autocomplete:

asc bulk schema --output .vscode/subscriptions.schema.json

VS Code Setup​

Add to your YAML file:

# yaml-language-server: $schema=.vscode/subscriptions.schema.json
app_bundle_id: live.yooz.whisper
subscriptions:
  - # Autocomplete available here

Or configure in .vscode/settings.json:

{
  "yaml.schemas": {
    ".vscode/subscriptions.schema.json": "subscriptions.yaml"
  }
}

Complete Examples​

Simple App (One Subscription)​

app_bundle_id: com.indie.app
subscriptions:
  - product_id: com.indie.app.premium
    price_usd: 1.99
    territories: all
    offers:
      - type: free-trial
        duration: 1w

Standard App (Monthly + Yearly)​

app_bundle_id: com.company.app
subscriptions:
  - product_id: com.company.app.pro.monthly
    price_usd: 4.99
    territories: all
    offers:
      - type: free-trial
        duration: 2w

  - product_id: com.company.app.pro.yearly
    price_usd: 39.99
    territories: all
    offers:
      - type: free-trial
        duration: 1w

Complex App (Multiple Tiers)​

app_bundle_id: com.enterprise.app
subscriptions:
  # Basic tier
  - product_id: com.enterprise.app.basic.monthly
    price_usd: 2.99
    territories: all
    offers:
      - type: free-trial
        duration: 1w

  # Pro tier
  - product_id: com.enterprise.app.pro.monthly
    price_usd: 9.99
    territories: all
    offers:
      - type: free-trial
        duration: 2w
      - type: pay-as-you-go
        duration: 3m
        price_usd: 4.99

  - product_id: com.enterprise.app.pro.yearly
    price_usd: 79.99
    territories: all
    offers:
      - type: free-trial
        duration: 1w

  # Team tier
  - product_id: com.enterprise.app.team.monthly
    price_usd: 29.99
    territories:
      - USA
      - CAN
      - GBR
      - DEU
      - FRA

Learn More​