| name | asc-subscriptions |
| description | Manage auto-renewable subscriptions using the `asc` CLI tool.
Use this skill when:
(1) Subscription groups: "asc subscription-groups list|create|update|delete"
(2) Subscription group localizations (custom-app-name per locale): "asc subscription-group-localizations list|create|update|delete"
(3) Subscriptions: "asc subscriptions list|create|update|delete|submit|unsubmit"
(4) Subscription pricing: "asc subscriptions price-points list", "asc subscriptions prices set" (per-territory, with proceedsYear2)
(5) Subscription localizations: "asc subscription-localizations list|create|update|delete"
(6) Introductory offers: "asc subscription-offers list|create|delete" (FREE_TRIAL, PAY_AS_YOU_GO, PAY_UP_FRONT)
(7) Promotional offers (in-app, with per-territory pricing): "asc subscription-promotional-offers list|create|delete", "asc subscription-promotional-offers prices list"
(8) Win-back offers (lapsed subscribers): "asc win-back-offers list|create|update|delete", "asc win-back-offers prices list"
(9) Offer codes (3 levels): "asc subscription-offer-codes list/create/update", "asc subscription-offer-codes prices list", custom codes, one-time codes (incl. `values` for redemption CSV)
(10) Subscription review screenshot: "asc subscription-review-screenshot get|upload|delete"
(11) User says "subscription group", "subscription tier", "promotional offer", "win-back offer", "lapsed subscriber", "subscription offer code", "custom code", "one-time codes", "free trial", "promo code", "review screenshot", "Custom App Name"
|
asc Subscriptions
Manage auto-renewable subscription groups, tiers, localizations, pricing, offers, and review assets via the asc CLI.
Subscription Groups
asc subscription-groups list --app-id <APP_ID>
asc subscription-groups create --app-id <APP_ID> --reference-name "Premium Plans"
asc subscription-groups update --group-id <GROUP_ID> --reference-name "Premium"
asc subscription-groups delete --group-id <GROUP_ID>
Group Localizations (display name + Custom App Name per locale)
asc subscription-group-localizations list --group-id <GROUP_ID>
asc subscription-group-localizations create --group-id <GROUP_ID> --locale en-US --name "Premium Plans" [--custom-app-name "Premium App"]
asc subscription-group-localizations update --localization-id <LOC> [--name "..."] [--custom-app-name "..."]
asc subscription-group-localizations delete --localization-id <LOC>
Subscriptions (lifecycle)
asc subscriptions list --group-id <GROUP_ID>
asc subscriptions create --group-id <GROUP_ID> --name "Monthly Premium" \
--product-id "com.app.monthly" --period ONE_MONTH \
[--family-sharable] [--group-level 1]
asc subscriptions update --subscription-id <SUB_ID> \
[--name "..."] [--family-sharable | --not-family-sharable] [--group-level <n>] [--review-note "..."]
asc subscriptions delete --subscription-id <SUB_ID>
asc subscriptions submit --subscription-id <SUB_ID>
asc subscriptions unsubmit --submission-id <SUBMISSION_ID>
--period ∈ ONE_WEEK, ONE_MONTH, TWO_MONTHS, THREE_MONTHS, SIX_MONTHS, ONE_YEAR.
Subscription Pricing (per-territory, with proceedsYear2)
asc subscriptions price-points list --subscription-id <SUB_ID> [--territory USA]
asc subscriptions prices set \
--subscription-id <SUB_ID> \
--territory USA \
--price-point-id <PP> \
[--start-date 2026-06-01] \
[--preserve-current-price]
Subscriptions price per-territory (no base territory). Each price point includes customerPrice, proceeds, and proceedsYear2.
Subscription Localizations
asc subscription-localizations list --subscription-id <SUB_ID>
asc subscription-localizations create --subscription-id <SUB_ID> --locale en-US --name "Monthly Premium" [--description "..."]
asc subscription-localizations update --localization-id <LOC> [--name "..."] [--description "..."]
asc subscription-localizations delete --localization-id <LOC>
Introductory Offers
asc subscription-offers list --subscription-id <SUB_ID>
asc subscription-offers create --subscription-id <SUB_ID> \
--duration ONE_MONTH --mode FREE_TRIAL --periods 1
asc subscription-offers create --subscription-id <SUB_ID> \
--duration THREE_MONTHS --mode PAY_AS_YOU_GO --periods 3 \
--territory USA --price-point-id <PP>
asc subscription-offers delete --offer-id <OFFER_ID>
--duration ∈ THREE_DAYS, ONE_WEEK, TWO_WEEKS, ONE_MONTH, TWO_MONTHS, THREE_MONTHS, SIX_MONTHS, ONE_YEAR. --mode ∈ FREE_TRIAL, PAY_AS_YOU_GO, PAY_UP_FRONT.
Promotional Offers (in-app, with per-territory pricing)
asc subscription-promotional-offers list --subscription-id <SUB_ID>
asc subscription-promotional-offers create --subscription-id <SUB_ID> \
--name "Loyalty25" --offer-code loyalty25 \
--duration THREE_MONTHS --mode PAY_AS_YOU_GO --periods 3 \
--price USA=spp-1 --price GBR=spp-2
asc subscription-promotional-offers delete --offer-id <OFFER_ID>
asc subscription-promotional-offers prices list --offer-id <OFFER_ID>
--price is encoded inline using ${newPromoOfferPrice-N} 1-based local IDs (matches the ASC web UI shape).
Win-Back Offers (lapsed subscribers)
asc win-back-offers list --subscription-id <SUB_ID>
asc win-back-offers create --subscription-id <SUB_ID> \
--reference-name "Lapsed Q4" --offer-id lapsedQ4 \
--duration ONE_MONTH --mode FREE_TRIAL --periods 1 \
--paid-months 3 --since-min 1 --since-max 6 --wait-months 2 \
--start-date 2026-04-01 --end-date 2026-12-31 \
--priority HIGH --promotion-intent USE_AUTO_GENERATED_ASSETS \
[--price USA=spp-1 ...]
asc win-back-offers update --offer-id <OFFER_ID> \
[--start-date YYYY-MM-DD] [--end-date YYYY-MM-DD] \
[--priority HIGH|NORMAL] [--promotion-intent NOT_PROMOTED|USE_AUTO_GENERATED_ASSETS] \
[--paid-months <n>] [--since-min <n>] [--since-max <n>] [--wait-months <n>]
asc win-back-offers delete --offer-id <OFFER_ID>
asc win-back-offers prices list --offer-id <OFFER_ID>
Eligibility model: --paid-months (months as paid subscriber required), --since-min..--since-max (months since last subscribed range), --wait-months (gap between offers shown to the same customer). The win-back create body is encoded by hand because the generated SDK's WinBackOfferPriceInlineCreate is missing territory + subscriptionPricePoint relationships.
Subscription Offer Codes (3-level hierarchy)
Level 1 — offer code
asc subscription-offer-codes list --subscription-id <SUB_ID>
asc subscription-offer-codes create --subscription-id <SUB_ID> \
--name "SUMMER2026" \
--duration ONE_MONTH --mode FREE_TRIAL --periods 1 \
--eligibility NEW --eligibility LAPSED \
--offer-eligibility STACKABLE \
--price USA=spp-usa --price JPN=spp-jpn \
--free-territory BRA \
[--auto-renew true|false]
asc subscription-offer-codes update --offer-code-id <OC> --active false
asc subscription-offer-codes prices list --offer-code-id <OC>
Pricing is set once, at creation (prices is read-only after — see the IAP skill's note for details). Use --auto-renew false to create a non-renewing one-time offer; ASC only accepts --mode FREE_TRIAL in that case.
--eligibility (repeatable) ∈ NEW, LAPSED, WIN_BACK, PAID_SUBSCRIBER. --offer-eligibility ∈ STACKABLE, INTRODUCTORY, SUBSCRIPTION_OFFER.
Level 2 — custom redeemable codes
asc subscription-offer-code-custom-codes list --offer-code-id <OC>
asc subscription-offer-code-custom-codes create --offer-code-id <OC> \
--custom-code "SUMMER2026" --number-of-codes 1000 [--expiration-date 2026-12-31]
asc subscription-offer-code-custom-codes update --custom-code-id <CC> --active false
Level 3 — one-time use code batches
asc subscription-offer-code-one-time-codes list --offer-code-id <OC>
asc subscription-offer-code-one-time-codes create --offer-code-id <OC> \
--number-of-codes 5000 --expiration-date 2026-12-31 [--environment production|sandbox]
asc subscription-offer-code-one-time-codes update --one-time-code-id <OTC> --active false
asc subscription-offer-code-one-time-codes values --one-time-code-id <OTC>
--environment defaults to production. Sandbox batches redeem against sandbox tester accounts (≈10,000/quarter ceiling); production batches against live accounts (≈150,000/quarter ceiling). Each SubscriptionOfferCode reports usage against both via productionCodeCount / sandboxCodeCount, and each one-time-use row carries its environment for filtering.
REST equivalents:
GET /api/v1/subscription-offer-codes/{offerCodeId}/one-time-codes
POST /api/v1/subscription-offer-codes/{offerCodeId}/one-time-codes
PATCH /api/v1/subscription-offer-code-one-time-codes/{oneTimeCodeId}
Subscription Review Screenshot (singleton)
asc subscription-review-screenshot get --subscription-id <SUB_ID>
asc subscription-review-screenshot upload --subscription-id <SUB_ID> --file ./review.png
asc subscription-review-screenshot delete --screenshot-id <RS>
Upload uses ASC's reserve → upload chunks → commit-with-MD5 protocol.
CAEOAS Affordances
SubscriptionGroup advertises:
{
"affordances": {
"createLocalization": "asc subscription-group-localizations create --group-id <ID> --locale en-US --name <name>",
"createSubscription": "asc subscriptions create --group-id <ID> --name <name> --product-id <id> --period ONE_MONTH",
"delete": "asc subscription-groups delete --group-id <ID>",
"listLocalizations": "asc subscription-group-localizations list --group-id <ID>",
"listSubscriptions": "asc subscriptions list --group-id <ID>",
"update": "asc subscription-groups update --group-id <ID> --reference-name <name>"
}
}
Subscription advertises (in addition to existing keys):
{
"createPromotionalOffer": "asc subscription-promotional-offers create --subscription-id <ID> ...",
"delete": "asc subscriptions delete --subscription-id <ID>",
"getReviewScreenshot": "asc subscription-review-screenshot get --subscription-id <ID>",
"listPromotionalOffers": "asc subscription-promotional-offers list --subscription-id <ID>",
"listWinBackOffers": "asc win-back-offers list --subscription-id <ID>",
"update": "asc subscriptions update --subscription-id <ID> --name <name>"
}
submit only when state == READY_TO_SUBMIT. SubscriptionSubmission advertises unsubmit. SubscriptionLocalization advertises update + delete. SubscriptionGroupLocalization advertises update + delete. SubscriptionPricePoint advertises setPrice only when territory != nil. SubscriptionPromotionalOffer advertises delete + listPrices. WinBackOffer advertises update + delete + listPrices. SubscriptionReviewScreenshot advertises delete only once assetState.isComplete || hasFailed. *OfferCode* custom & one-time codes advertise deactivate only when isActive == true.
Resolve App ID
See project-context.md — check .asc/project.json before asking the user or running asc apps list.
Typical Workflow
APP_ID=$(cat .asc/project.json 2>/dev/null | jq -r '.appId // empty')
GROUP_ID=$(asc subscription-groups create --app-id "$APP_ID" --reference-name "Premium" \
| jq -r '.data[0].id')
asc subscription-group-localizations create --group-id "$GROUP_ID" --locale en-US \
--name "Premium Plans" --custom-app-name "Premium App"
SUB_ID=$(asc subscriptions create --group-id "$GROUP_ID" --name "Monthly Premium" \
--product-id "com.app.monthly" --period ONE_MONTH | jq -r '.data[0].id')
asc subscription-localizations create --subscription-id "$SUB_ID" --locale en-US \
--name "Monthly Premium" --description "Unlock everything"
USA_PP=$(asc subscriptions price-points list --subscription-id "$SUB_ID" --territory USA \
| jq -r '.data[] | select(.customerPrice == "9.99") | .id')
asc subscriptions prices set --subscription-id "$SUB_ID" --territory USA --price-point-id "$USA_PP"
asc subscription-review-screenshot upload --subscription-id "$SUB_ID" --file ./review.png
asc subscriptions submit --subscription-id "$SUB_ID"
asc subscription-promotional-offers create --subscription-id "$SUB_ID" \
--name "Loyalty25" --offer-code loyalty25 \
--duration THREE_MONTHS --mode PAY_AS_YOU_GO --periods 3 \
--price USA=$USA_PP
asc win-back-offers create --subscription-id "$SUB_ID" \
--reference-name "Lapsed Q4" --offer-id lapsedQ4 \
--duration ONE_MONTH --mode FREE_TRIAL --periods 1 \
--paid-months 3 --since-min 1 --since-max 6 --wait-months 2 \
--start-date 2026-04-01 --end-date 2026-12-31 \
--priority HIGH --promotion-intent USE_AUTO_GENERATED_ASSETS
OC_ID=$(asc subscription-offer-codes create --subscription-id "$SUB_ID" \
--name "SUMMER2026" --duration ONE_MONTH --mode FREE_TRIAL --periods 1 \
--eligibility NEW --eligibility LAPSED --offer-eligibility STACKABLE \
| jq -r '.data[0].id')
asc subscription-offer-code-one-time-codes create --offer-code-id "$OC_ID" \
--number-of-codes 5000 --expiration-date 2026-12-31
asc subscription-offer-code-one-time-codes values --one-time-code-id <OTC_ID> > codes.csv
State Semantics
SubscriptionState exposes semantic booleans:
| Boolean | True when state is |
|---|
isEditable | MISSING_METADATA, REJECTED, DEVELOPER_ACTION_NEEDED |
isPendingReview | WAITING_FOR_REVIEW, IN_REVIEW |
isApproved / isLive | APPROVED |
SubscriptionCustomerEligibility ∈ NEW, LAPSED, WIN_BACK, PAID_SUBSCRIBER.
SubscriptionOfferEligibility ∈ STACKABLE, INTRODUCTORY, SUBSCRIPTION_OFFER.
WinBackOfferPriority ∈ HIGH, NORMAL. WinBackOfferPromotionIntent ∈ NOT_PROMOTED, USE_AUTO_GENERATED_ASSETS.
SubscriptionReviewScreenshot.AssetState exposes isComplete and hasFailed.
Nil optional fields are omitted from JSON output. PATCH responses (update commands) return the resource with the parent id as "" because ASC's PATCH responses don't include parent ids — refetch via list if you need the parent.
Reference
For full domain-model and REST detail see docs/features/iap-subscriptions.md and the iap-subscriptions/ subdocs (lifecycle, pricing, offer-codes, group-localizations, promotional-offers, win-back-offers, review-assets).
