asc-iap

asc 应用内购买

通过 asc CLI 管理 IAP。

生命周期

列出

asc iap list --app-id <APP_ID> [--limit N] [--pretty]

创建

asc iap create \
  --app-id <APP_ID> \
  --reference-name "Gold Coins" \
  --product-id "com.app.goldcoins" \
  --type consumable

--type ∈ consumable、non-consumable、non-renewing-subscription。

更新

asc iap update --iap-id <ID> \
  [--reference-name "New Name"] \
  [--review-note "Notes for App Review"] \
  [--family-sharable | --not-family-sharable]

删除

asc iap delete --iap-id <ID>

提交 / 取消提交

asc iap submit --iap-id <ID>          # state must be READY_TO_SUBMIT (affordance gates this)
asc iap unsubmit --submission-id <ID> # withdraw from review; manual Request<Void>
asc iap versions list --iap-id <ID>   # review versions + state; submittable ones offer addToSubmission

首次创建 IAP？ Apple 只会将其与应用版本一并审核，因此 asc iap submit 会失败。请将其与应用一并提交：asc versions submit --version-id <VERSION_ID> --with-products（先使用 --dry-run 运行）。完整工作流请参阅 submit-with-products.md。

IAP 定价

asc iap price-points list --iap-id <ID> [--territory USA]

asc iap prices set \
  --iap-id <ID> \
  --base-territory USA \
  --price-point-id <PP>

Apple 会根据基准价格自动均衡其他地区的价格。

IAP 本地化

asc iap-localizations list   --iap-id <ID>
asc iap-localizations create --iap-id <ID> --locale en-US --name "Gold Coins" [--description "In-game currency"]
asc iap-localizations update --localization-id <LOC> [--name "New"] [--description "..."]
asc iap-localizations delete --localization-id <LOC>

IAP 优惠码（3 层层级）

第 1 层 — 优惠码

asc iap-offer-codes list   --iap-id <ID>
asc iap-offer-codes create --iap-id <ID> --name "FREEGEMS" \
  --eligibility NON_SPENDER --eligibility CHURNED_SPENDER \
  --price USA=pp-usa --price JPN=pp-jpn \
  --free-territory BRA --free-territory IND
asc iap-offer-codes update --offer-code-id <OC> --active false
asc iap-offer-codes prices list --offer-code-id <OC>   # per-territory pricing (read-only)

价格仅在创建时设置一次。 优惠码创建后，ASC 的 prices 关系为只读，因此请通过 --price（付费）或 --free-territory 指定要覆盖的所有地区。若不使用这些标志，创建的优惠码将没有任何按地区设置的价格，之后也无法补设。

--eligibility（可重复）∈ NON_SPENDER、ACTIVE_SPENDER、CHURNED_SPENDER。

第 2 层 — 自定义兑换码

asc iap-offer-code-custom-codes list   --offer-code-id <OC>
asc iap-offer-code-custom-codes create --offer-code-id <OC> \
  --custom-code "FREEGEMS100" --number-of-codes 500 [--expiration-date 2026-12-31]
asc iap-offer-code-custom-codes update --custom-code-id <CC> --active false

第 3 层 — 一次性使用代码批次

asc iap-offer-code-one-time-codes list   --offer-code-id <OC>
asc iap-offer-code-one-time-codes create --offer-code-id <OC> \
  --number-of-codes 3000 --expiration-date 2026-06-30 [--environment production|sandbox]
asc iap-offer-code-one-time-codes update --one-time-code-id <OTC> --active false

# Download the CSV of redemption codes (raw String — not JSON):
asc iap-offer-code-one-time-codes values --one-time-code-id <OTC>

--environment 默认为 production。Sandbox 批次使用 Sandbox 测试账户兑换（每季度上限约为 10,000 个）；production 批次使用 App Store 正式账户兑换（每季度上限约为 150,000 个）。每个 InAppPurchaseOfferCode 都会通过 productionCodeCount / sandboxCodeCount 显示已使用数量在两个上限中的情况，每条一次性使用代码记录都带有 environment，因此可以筛选：

asc iap-offer-code-one-time-codes list --offer-code-id <OC> \
  | jq '.data[] | select(.environment == "SANDBOX")'

REST 等效操作：

GET    /api/v1/iap-offer-codes/{offerCodeId}/one-time-codes
POST   /api/v1/iap-offer-codes/{offerCodeId}/one-time-codes   # body: {numberOfCodes, expirationDate, environment?}
PATCH  /api/v1/iap-offer-code-one-time-codes/{oneTimeCodeId}  # body: {isActive: false}

IAP 审核素材

审核截图（单例 — 每个 IAP 一个）

asc iap-review-screenshot get    --iap-id <ID>          # returns empty data:[] when none uploaded
asc iap-review-screenshot upload --iap-id <ID> --file ./review.png
asc iap-review-screenshot delete --screenshot-id <RS>   # suppressed while assetState == AWAITING_UPLOAD

上传使用 ASC 标准的预留 → 分块上传 → 使用 MD5 提交协议。

宣传图片（1024×1024，每个 IAP 可有多个）

asc iap-images list   --iap-id <ID>
asc iap-images upload --iap-id <ID> --file ./promo-1024.png
asc iap-images delete --image-id <IMG>                  # suppressed while state.isPendingReview

CAEOAS 便捷功能

每个 IAP 响应都会嵌入可直接运行的后续命令：

{
  "affordances": {
    "createLocalization":  "asc iap-localizations create --iap-id <ID> --locale en-US --name <name>",
    "delete":              "asc iap delete --iap-id <ID>",
    "getReviewScreenshot": "asc iap-review-screenshot get --iap-id <ID>",
    "listImages":          "asc iap-images list --iap-id <ID>",
    "listLocalizations":   "asc iap-localizations list --iap-id <ID>",
    "listOfferCodes":      "asc iap-offer-codes list --iap-id <ID>",
    "listPricePoints":     "asc iap price-points list --iap-id <ID>",
    "listVersions":        "asc iap versions list --iap-id <ID>",
    "submit":              "asc iap submit --iap-id <ID>",
    "update":              "asc iap update --iap-id <ID> --reference-name <name>"
  }
}

仅当 state == READY_TO_SUBMIT 时才会出现 submit。只有在已知地区时，每个价格点才会包含 setPrice。

InAppPurchaseSubmission 会提供 unsubmit。InAppPurchaseLocalization 会提供 update + delete。仅当 !state.isPendingReview 时，InAppPurchasePromotionalImage 才会提供 delete。仅当 assetState.isComplete || hasFailed 时，InAppPurchaseReviewScreenshot 才会提供 delete。

解析 App ID

请参阅 project-context.md — 在询问用户或运行 asc apps list 前，先检查 .asc/project.json。

典型工作流

APP_ID=$(cat .asc/project.json 2>/dev/null | jq -r '.appId // empty')

# 1. Create + localize
IAP_ID=$(asc iap create --app-id "$APP_ID" --reference-name "Gold Coins" \
  --product-id "com.app.goldcoins" --type consumable | jq -r '.data[0].id')
asc iap-localizations create --iap-id "$IAP_ID" --locale en-US --name "Gold Coins" --description "In-game currency"
asc iap-localizations create --iap-id "$IAP_ID" --locale zh-Hans --name "金币"

# 2. Set price (Tier 1 USA, Apple auto-equalizes)
PRICE_ID=$(asc iap price-points list --iap-id "$IAP_ID" --territory USA \
  | jq -r '.data[] | select(.customerPrice == "0.99") | .id')
asc iap prices set --iap-id "$IAP_ID" --base-territory USA --price-point-id "$PRICE_ID"

# 3. Add review screenshot + promo image
asc iap-review-screenshot upload --iap-id "$IAP_ID" --file ./review.png
asc iap-images upload --iap-id "$IAP_ID" --file ./promo-1024.png

# 4. Submit
asc iap submit --iap-id "$IAP_ID"

# 5. Optional: offer code + redemption batch
OC_ID=$(asc iap-offer-codes create --iap-id "$IAP_ID" --name "LAUNCH_PROMO" \
  --eligibility NON_SPENDER --eligibility CHURNED_SPENDER | jq -r '.data[0].id')
asc iap-offer-code-one-time-codes create --offer-code-id "$OC_ID" \
  --number-of-codes 5000 --expiration-date 2026-12-31
# Download the CSV for distribution:
asc iap-offer-code-one-time-codes values --one-time-code-id <OTC_ID> > codes.csv

状态语义

InAppPurchaseState 提供语义布尔值：

布尔值	状态为以下值时为 True
isEditable	MISSING_METADATA、REJECTED、DEVELOPER_ACTION_NEEDED
isPendingReview	WAITING_FOR_REVIEW、IN_REVIEW
isApproved / isLive	APPROVED

IAPCustomerEligibility ∈ NON_SPENDER、ACTIVE_SPENDER、CHURNED_SPENDER。

InAppPurchaseReviewScreenshot.AssetState 提供 isComplete（uploadComplete 或 complete）和 hasFailed。InAppPurchasePromotionalImage.ImageState 提供 isApproved 和 isPendingReview。

JSON 输出中会省略值为 Nil 的可选字段。

参考

完整的领域模型和 REST 详情，请参阅 docs/features/iap-subscriptions.md 和 iap-subscriptions/ 子文档。