gpc-monetization

gpc-monetization

使用 GPC 管理订阅、应用内商品、购买和定价。

适用场景

• 创建、更新或删除订阅和基础方案
• 管理订阅优惠（首次订阅、升级、挽回）
• 创建、更新或同步应用内商品（一次性购买）
• 在服务器端验证、确认或消耗购买
• 取消、延期或撤销订阅
• 处理退款和已作废的购买
• 查看订阅分析数据（活跃、试用、流失、转化）
• 将订阅用户迁移到新的价格档位
• 在不同地区和货币之间转换价格

所需输入

• 已通过身份验证的 GPC — gpc auth status 必须显示有效凭据
• 应用软件包名称 — 通过 --app 或 gpc config set app 设置
• 商品 JSON 文件 — 用于创建或更新操作（订阅或 IAP 定义）
• 购买令牌 — 用于验证、确认和消耗购买
• 开发者账号 ID — 用于部分购买操作（--developer-id）

操作步骤

0. 验证设置

gpc auth status
gpc config get app

确认身份验证有效且已设置默认应用。如果没有，请Read: gpc-setup 技能。

1. 订阅

A. 列出并检查订阅

# List all subscriptions
gpc subscriptions list

# Get details for a specific subscription
gpc subscriptions get <product-id>

# Paginated listing
gpc subscriptions list --limit 50

B. 创建订阅

创建定义订阅的 JSON 文件，然后运行：

# Preview first
gpc subscriptions create --file subscription.json --dry-run

# Create
gpc subscriptions create --file subscription.json

# Specify a regions version (defaults to 2022/02)
gpc subscriptions create --file subscription.json --regions-version "2022/02"

在 v0.9.84 中修复： --regions-version 现在会在订阅和一次性商品的创建、更新及优惠命令中实际发送到 Google Play API。在 v0.9.77-v0.9.83 中，GPC 虽然接受了该参数，但会静默忽略。若未指定，默认值为 2022/02。IAP 和订阅的 list --json 现在也使用统一的 { <key>, nextPageToken, meta.count } 封装（GPC v0.9.83）。

请Read: references/subscription-schema.md，查看 JSON 结构和字段参考。

C. 更新订阅

# Update specific fields
gpc subscriptions update <product-id> --file updated.json --update-mask "listings"

# Preview changes
gpc subscriptions update <product-id> --file updated.json --dry-run

# Upsert: create the subscription if it does not already exist
gpc subscriptions update <product-id> --file updated.json --allow-missing

# Control propagation speed (default: LATENCY_SENSITIVE)
gpc subscriptions update <product-id> --file updated.json --latency-tolerance LATENCY_TOLERANT

--update-mask 标志用于控制要更新的字段。省略此标志会替换整个订阅。

--allow-missing 标志会启用 upsert 行为：如果订阅不存在，则创建订阅，而不是返回错误。

--latency-tolerance 标志用于控制更改的传播速度。使用 LATENCY_SENSITIVE（默认值）可立即传播；如果批量操作时可以接受延迟以换取更高吞吐量，则使用 LATENCY_TOLERANT。

D. 批量操作

# Batch-get multiple subscriptions at once
gpc subscriptions batch-get <id1> <id2> <id3>

# Batch-update multiple subscriptions from JSON
gpc subscriptions batch-update --file batch-updates.json --dry-run
gpc subscriptions batch-update --file batch-updates.json

E. 删除订阅

gpc subscriptions delete <product-id> --dry-run
gpc subscriptions delete <product-id>

2. 基础方案

基础方案定义订阅的计费周期和价格。

# Activate a base plan (makes it available for purchase)
gpc subscriptions base-plans activate <product-id> <base-plan-id>

# Deactivate a base plan (stops new purchases, existing subscribers unaffected)
gpc subscriptions base-plans deactivate <product-id> <base-plan-id>

# Delete a base plan
gpc subscriptions base-plans delete <product-id> <base-plan-id>

# Migrate prices for a base plan
gpc subscriptions base-plans migrate-prices <product-id> <base-plan-id> --file prices.json

所有基础方案命令都支持 --dry-run。

3. 订阅优惠

优惠用于定义促销价格（首次订阅、升级、挽回）。

# List offers for a base plan
gpc subscriptions offers list <product-id> <base-plan-id>

# Get offer details
gpc subscriptions offers get <product-id> <base-plan-id> <offer-id>

# Create an offer
gpc subscriptions offers create <product-id> <base-plan-id> --file offer.json --dry-run
gpc subscriptions offers create <product-id> <base-plan-id> --file offer.json

# Update an offer
gpc subscriptions offers update <product-id> <base-plan-id> <offer-id> --file offer.json

# Upsert: create the offer if it does not already exist
gpc subscriptions offers update <product-id> <base-plan-id> <offer-id> --file offer.json --allow-missing

# Control propagation speed for bulk offer updates
gpc subscriptions offers update <product-id> <base-plan-id> <offer-id> --file offer.json --latency-tolerance LATENCY_TOLERANT

# Activate / deactivate an offer
gpc subscriptions offers activate <product-id> <base-plan-id> <offer-id>
gpc subscriptions offers deactivate <product-id> <base-plan-id> <offer-id>

# Delete an offer
gpc subscriptions offers delete <product-id> <base-plan-id> <offer-id>

4. 应用内商品（IAP）

一次性购买——消耗型商品、非消耗型商品、权益。

A. 列出并检查

gpc iap list

# Paginated listing (useful for apps with many products)
gpc iap list --page-size 50
gpc iap list --page-size 50 --next-page <page-token>

gpc iap get <sku>

v0.9.51 新增： gpc iap list（别名为 gpc one-time-products list）现在支持 --page-size 和 --next-page，用于获取分页结果。如果还有更多结果，响应中会包含 nextPageToken 字段。

B. 创建和更新

# Create from JSON
gpc iap create --file product.json --dry-run
gpc iap create --file product.json

# Specify a regions version on create (defaults to 2022/02)
gpc iap create --file product.json --regions-version "2022/02"

# Update
gpc iap update <sku> --file updated.json --dry-run
gpc iap update <sku> --file updated.json

# Upsert: create the product if it does not already exist
gpc iap update <sku> --file updated.json --allow-missing

# Control propagation speed
gpc iap update <sku> --file updated.json --latency-tolerance LATENCY_TOLERANT

# Delete
gpc iap delete <sku>

请Read: references/iap-schema.md，查看 JSON 结构和字段参考。

C. 批量删除

# Delete multiple IAP products at once
gpc iap batch-delete <sku1> <sku2> <sku3> --dry-run
gpc iap batch-delete <sku1> <sku2> <sku3>

D. 从目录同步

从包含 JSON 文件的目录批量管理 IAP 商品：

# Preview what would change
gpc iap sync --dir products/ --dry-run

# Apply changes
gpc iap sync --dir products/

目录中的每个 JSON 文件代表一个商品。GPC 会将本地文件与 Play 商店进行比较，并根据需要创建、更新或删除商品。

一次性商品优惠——单个优惠命令（v0.9.96）

Google Play 仅发布一次性商品优惠的批量端点，因此，otp offers get、create、update 和 delete 会作为单项批量请求发送，并且必须指定 --purchase-option。省略此参数会立即报缺少选项错误，不会调用 API。通配符 - 仅适用于 offers list——如果不知道某个优惠属于哪个购买选项，请先运行该命令。

# Find the purchase option an offer belongs to
gpc otp offers list premium_upgrade

gpc otp offers get premium_upgrade launch_discount --purchase-option buy_once
gpc otp offers create premium_upgrade --file offer.json --purchase-option buy_once
gpc otp offers update premium_upgrade launch_discount --file offer-update.json --purchase-option buy_once
gpc otp offers delete premium_upgrade launch_discount --purchase-option buy_once

offers create 会先检查优惠 ID 是否已存在；若已存在，则返回 API_ALREADY_EXISTS（409），而不是覆盖现有优惠——底层批量端点采用 upsert 操作。要更改现有优惠，请使用 offers update。

已在 v0.9.96 中修复：gpc one-time-products create / update 以及上述四个单个优惠命令之前会因路由未找到错误而失败（Play 的写入路由拼写与读取路由不同）。需要 v0.9.96+。

一次性商品优惠载荷（Google 的架构）

优惠文件是 Google Play 的 OneTimeProductOffer：包含 discountedOffer、preOrderOffer 或 gameRewardOffer 之一，以及作为列表的 regionalPricingAndAvailabilityConfigs，其中每项为 { regionCode, availability, relativeDiscount | absoluteDiscount | noOverride }。relativeDiscount 表示用户支付的金额比例（0.7 = 优惠 30%）；价格本身属于购买选项。请勿使用订阅字段（pricingPhases、regionalConfigs 映射、newSubscriberAvailability）——Google 会拒绝这些字段，而且 v0.9.99 之前的 GPC 文档展示了错误的结构。

{
  "offerId": "launch-discount",
  "discountedOffer": { "startTime": "2026-10-01T00:00:00Z", "endTime": "2026-10-31T23:59:59Z", "redemptionLimit": "1000" },
  "regionalPricingAndAvailabilityConfigs": [
    { "regionCode": "US", "availability": "AVAILABLE", "relativeDiscount": 0.7 }
  ]
}

Play Games Rewards（v0.9.99+ 提供类型定义和文档）："gameRewardOffer": { "redemptionLimit": "1" }（"1"-"50"，"0"/未设置 = 无限制）。Google 的指南要求在 Play Console 中创建奖励优惠；GPC 可列出、读取和更新这些优惠。

外部交易（替代计费、美国计划）

gpc ext-txn create --file txn.json --transaction-id order-1001    # body sent as-is
gpc ext-txn get order-1001
gpc ext-txn refund order-1001 --full
gpc ext-txn refund order-1001 --partial-amount 4990000 --currency EUR --refund-id order-1001-r1

• 退款需要 GPC v0.9.99+：较早版本从未发送 Google 要求的 refundTime（以及部分退款所需的 refundId），因此 Google 会拒绝请求。--refund-time <RFC 3339 with zone> 可覆盖“现在”；不允许指定未来时间。无效选项会在发送任何内容前以退出码 2 返回 EXT_TXN_REFUND_INVALID，提示词中会注明金额。
• --partial-amount 的单位是税前微单位（4990000 = 4.99），而不是主要货币单位。
• 从 v1.0.0-rc.1 起，退款操作若未提供终端设备，则必须指定 --yes，否则会以退出码 2 返回 CONFIRMATION_REQUIRED。
• 美国外部内容链接计划：在创建文件中添加 externalContentLinkDetails { linkType: LINK_TO_DIGITAL_CONTENT_OFFER | LINK_TO_APP_DOWNLOAD, installedAppPackage, externalAppCategory: APP | GAME }（与较早的 externalOfferDetails 分开）。Google 要求自 2026 年 10 月 1 日起报告购买情况，并自 2026 年 12 月 1 日起报告应用下载情况。

激活/停用 OTP 优惠（v0.9.57+）

一次性商品优惠支持显式激活/停用：

gpc otp offers activate --app com.example.app --product-id sku_id --offer-id offer_id
gpc otp offers deactivate --app com.example.app --product-id sku_id --offer-id offer_id

与订阅优惠生命周期相匹配。否则，OTP 优惠只能通过批量更新调用来设置状态。

OTP 优惠和购买选项批量操作（v0.9.79+）

对一次性商品优惠和购买选项执行批量操作：

# Retrieve multiple OTP offers in one call
gpc one-time-products offers batch-get --product-id <sku> --offer-ids "offer_a,offer_b"

# Update multiple OTP offers from JSON
gpc one-time-products offers batch-update --file otp-offers.json --dry-run
gpc one-time-products offers batch-update --file otp-offers.json

# Bulk activate or deactivate OTP offers
gpc one-time-products offers batch-update-states --file otp-states.json --dry-run
gpc one-time-products offers batch-update-states --file otp-states.json

# Delete multiple OTP offers at once
gpc one-time-products offers batch-delete --product-id <sku> --offer-ids "offer_a,offer_b" --dry-run
gpc one-time-products offers batch-delete --product-id <sku> --offer-ids "offer_a,offer_b"

# Bulk delete purchase options across products
gpc one-time-products purchase-options batch-delete --file po-delete.json --dry-run
gpc one-time-products purchase-options batch-delete --file po-delete.json

# Bulk update purchase-option states (activate/deactivate)
gpc one-time-products purchase-options batch-update-states --file po-states.json --dry-run
gpc one-time-products purchase-options batch-update-states --file po-states.json

所有批量命令均支持 --dry-run 和 --json。这些操作涵盖 v0.9.79 OTP 批量功能的全部范围：4 个优惠方法（batch-get、batch-update、batch-update-states、batch-delete）和 2 个购买选项方法（batch-delete、batch-update-states）。

5. 购买——验证和生命周期

A. 商品购买

# Verify a purchase
gpc purchases get <product-id> <token>

# Acknowledge (required within 3 days or purchase is refunded)
gpc purchases acknowledge <product-id> <token>
gpc purchases acknowledge <product-id> <token> --payload "order-123"

# Consume (for consumable products — allows re-purchase)
gpc purchases consume <product-id> <token>

B. 订阅购买

# Acknowledge a subscription purchase (v1 — required within 3 days)
gpc purchases subscription acknowledge <subscription-id> <token>
gpc purchases subscription acknowledge <subscription-id> <token> --payload "order-456"

# Get subscription purchase details (v2 API)
# Returns SubscriptionPurchaseV2 with onHoldStateContext, inGracePeriodStateContext (v0.9.76+)
# Both context objects are surfaced in --json output and structured display
gpc purchases subscription get <token>

# Cancel a subscription (v1 — requires subscription-id)
gpc purchases subscription cancel <subscription-id> <token>

# Cancel a subscription (v2 — supports cancellation types)
gpc purchases subscription cancel-v2 <token>
gpc purchases subscription cancel-v2 <token> --type DEVELOPER_CANCELED

# Defer expiry to a later date (v1)
gpc purchases subscription defer <subscription-id> <token> --expiry 2025-06-01T00:00:00Z

# Defer expiry (v2 — supports add-on subscriptions)
gpc purchases subscription defer-v2 <token> --until 2026-07-01T00:00:00Z

# Revoke a subscription (v2 API)
gpc purchases subscription revoke <token>

C. 商品购买（v2 API）

# Get product purchase details (v2 — supports multi-offer OTPs)
gpc purchases product get-v2 <token>

v2 商品购买 API 会返回 ProductPurchaseV2，其中包含行项目、优惠详情和多商品捆绑包支持。

D. 订单

# Get order details
gpc purchases orders get <order-id>

# Batch retrieve orders (up to 1000)
gpc purchases orders batch-get --ids "GPA.1234,GPA.5678"

v0.9.79 新增： 订单现在会公开 OfferPhaseDetails 类型，用来替代扁平的 offerPhase 字段。OfferPhaseDetails 是一个结构化对象，包含更丰富的阶段信息（阶段类型、周期计数和定价详情）。扁平的 offerPhase 字段已弃用；新代码请读取 offerPhaseDetails。

E. 已作废的购买和退款

# List voided purchases (default: in-app only)
gpc purchases voided --start-time 2025-01-01 --end-time 2025-03-01

# Include subscription voids (type=1)
gpc purchases voided --type 1

# Include quantity-based partial refunds
gpc purchases voided --include-partial-refunds

# Refund an order (always a full refund; --revoke also removes the entitlement)
gpc purchases orders refund <order-id> --yes
gpc purchases orders refund <order-id> --revoke --yes

# Partial subscription refunds go through the v2 revoke instead
gpc purchases subscription revoke <token> --refund-type prorated --yes

orders refund 只接受 --revoke：Google 的 orders.refund 会执行全额退款，不支持部分退款或按比例退款。purchases subscription revoke 才能选择退款方式，可通过 --refund-type full|prorated|item 指定（默认值为 prorated）；--refund-type item 还需要 --product-id。

v0.9.47 新增： --type 0（默认值）仅返回应用内购买的作废记录。--type 1 会包含订阅作废记录。--include-partial-refunds 会包含基于数量的部分退款。

所有写入操作都支持 --dry-run。

在 CI 中执行资金相关命令需要 --yes（v1.0.0-rc.1+）

purchases orders refund、purchases orders review-refund、purchases subscription revoke 和 external-transactions refund 会转移资金，且无法撤销。在没有终端的环境中（CI、通过管道传入的 stdin、--no-interactive）运行时，除非传入 --yes，现在都会以 CONFIRMATION_REQUIRED（退出码 2）停止。早期版本会自动确认这些操作，因此流水线可能会默认发起退款。--dry-run 不会发送任何内容，不受此限制。在交互式 shell 中，提示保持不变。

Read: references/purchase-verification.md，了解服务端验证模式和最佳实践。

F. 拒付争议 -- purchases orders review-refund（v0.9.96+）

用户向银行对某笔扣款提出争议时，Play 会发送一条 pendingRefundReviewNotification RTDN，其中包含 pendingRefundToken 和有争议的 orderId。你有 24 小时作出答复。最终结果由 Play 决定；你的偏好和证据只是该决定的输入，而不是决定本身。

# 1. Pull the token out of the notification (full token only in JSON output)
TOKEN=$(gpc rtdn decode "<base64-payload>" --output json \
  | jq -r .pendingRefundReviewNotification.pendingRefundToken)

# 2. Answer the dispute
gpc purchases orders review-refund "GPA.1234-5678-9012-34567" \
  --app com.example.app \
  --pending-refund-token "$TOKEN" \
  --preference decline \
  --sample-content-provided \
  --consumption-percent 82 \
  --usage-events-file ./usage-events.json

# Take no side, no evidence
gpc purchases orders review-refund "GPA.1234-5678-9012-34567" \
  --pending-refund-token "$TOKEN" \
  --preference neutral \
  --no-sample-content-provided

标志	必需	说明
--pending-refund-token	是	来自 pendingRefundReviewNotification 的令牌
--preference	是	approve、decline 或 neutral
--sample-content-provided / --no-sample-content-provided	是（必须且只能选择一个）	购买前是否提供了免费样品、试用或功能说明。Google 没有默认值，因此 GPC 会要求你明确说明
--consumption-percent	否	已使用的百分比，范围为 0-100，可带小数（以毫单位发送）
--usage-events-file	否	消费使用事件的 JSON 数组，最多 1,000 项

usage-events.json 使用 RFC 3339 时间戳；只要提供了位置，location.regionCode 就必须是有效的 CLDR 区域代码：

[
  {
    "consumptionTime": "2026-08-30T10:15:00Z",
    "consumptionItemDescription": "Opened chapter 4",
    "obfuscatedAccountId": "user-account-id",
    "ipAddress": "203.0.113.10",
    "location": { "regionCode": "US" }
  }
]

无效输入会在发送任何内容前由本地拒绝，并返回 ORDER_REVIEW_REFUND_INVALID（退出码 2）。空白或仅含空格的 --consumption-percent 会视为未提供，因此输入错误不会替你声称“已使用 0%”。--dry-run 会预览请求。

6. 实时开发者通知（RTDN）

发生订阅和购买事件时，RTDN 会通过 Pub/Sub 发送消息。GPC 可以解码并检查这些通知。

# Check RTDN topic configuration
gpc rtdn status

# Decode a base64-encoded Pub/Sub notification payload
gpc rtdn decode <base64-payload>

# Show setup instructions for RTDN
gpc rtdn test

通知类型包括：SUBSCRIPTION_PURCHASED、SUBSCRIPTION_CANCELED、SUBSCRIPTION_RENEWED、SUBSCRIPTION_REVOKED、SUBSCRIPTION_EXPIRED、ONE_TIME_PRODUCT_PURCHASED、VOIDED_PURCHASE 等。

v0.9.47 新增： RTDN 命令可帮助调试订阅生命周期事件。在 GCP 中设置 Pub/Sub 主题，在 Play Console > Monetization setup 中进行配置，然后使用 gpc rtdn decode 检查负载。

v0.9.96 新增： gpc rtdn decode 现在可识别 pendingRefundReviewNotification（提交给你审核的拒付），并显示其 orderId 和 pendingRefundToken -- 只有使用 --output json 才会打印完整令牌。它也不再会因不完整的拒付通知而崩溃。请在 24 小时内使用 gpc purchases orders review-refund 回复（第 5F 节）。

7. 订阅分析

获取订阅者数量、转化率和流失率的洞察：

# Active subscribers, in-trial counts, trial→paid conversion, churn cohort
gpc subscriptions analytics

# JSON output for dashboards
gpc subscriptions analytics --json

报告：活跃数量、试用中数量、已取消数量、试用转付费转化率、按群组估算的流失率。

8. 基础方案价格迁移

将现有订阅者迁移到新的价格点：

# Migrate all subscribers on a base plan to a new price
gpc subscriptions base-plans migrate-prices <product-id> <base-plan-id> \
  --file prices.json

# Prices file format: regional prices JSON (same as base plan prices)

Google Play 会通知订阅者，他们必须接受或取消。使用 --dry-run 预览迁移。

9. 区域定价

将基础价格转换为 Google Play 支持的所有地区价格：

# Convert USD 4.99 to all regional prices
gpc pricing convert --from USD --amount 4.99

# Output as JSON for scripting
gpc pricing convert --from USD --amount 4.99 --json

转换使用 Google Play 的官方汇率，并四舍五入到符合当地习惯的价格点。

10. 数据安全（v0.9.75+）

通过 API 管理应用的“数据安全”部分声明：

# Get current data safety labels
gpc data-safety get

# Update data safety declarations from CSV
gpc data-safety update --file safety.csv

验证

• gpc subscriptions list 返回你的订阅
• gpc iap list 返回你的应用内商品
• 对有效令牌运行 gpc purchases get <product-id> <token>，会返回 v1 购买详情
• gpc purchases product get-v2 <token> 返回包含明细项的 v2 购买详情
• gpc purchases orders get <order-id> 返回订单详情
• gpc pricing convert --from USD --amount 9.99 --json 返回各地区价格
• 所有 --dry-run 命令都会显示将进行的更改，但不会修改数据
• 所有命令均支持 JSON 输出（--json 标志）

故障模式 / 调试

症状	可能原因	修复方法
PRODUCT_NOT_FOUND	商品 ID 或 SKU 无效	使用 gpc subscriptions list 或 gpc iap list 验证
INVALID_PURCHASE_TOKEN	令牌已过期、已被使用，或应用不匹配	确认令牌与应用和商品相符
PURCHASE_NOT_ACKNOWLEDGED	购买未在 3 天内确认	立即确认；若超过 3 天，购买已自动退款
SUBSCRIPTION_NOT_FOUND	取消 / 延期时使用了错误的订阅 ID	使用 gpc purchases subscription get <token> 查找正确的 ID
创建 / 更新时出现 INVALID_JSON	商品 JSON 文件格式错误	对照架构参考验证 JSON 结构
购买操作出现 PERMISSION_DENIED	服务账号缺少财务权限	在 Play Console 中授予“查看财务数据”和“管理订单”权限
--update-mask 错误	更新掩码中的字段路径无效	查看 API 文档中的有效字段名称；省略此标志可替换所有字段
iap sync 删除了意外的商品	目录中缺少部分商品文件	先使用 --dry-run；同步会删除目录中不存在的商品
otp offers get/create/update/delete 缺少 --purchase-option	v0.9.96 会通过 Play 的批量优惠端点处理这些操作，而该端点需要具体的购买选项	运行 gpc otp offers list <product-id> 查找；- 仅适用于 list
otp offers create 出现 API_ALREADY_EXISTS	该优惠 ID 已存在；批量端点执行的是插入或更新，因此 GPC 会进行探测并拒绝覆盖	改用 gpc otp offers update
ORDER_REVIEW_REFUND_INVALID	未回答 --sample-content-provided、--consumption-percent 超出 0-100，或 --usage-events-file 不是由对象组成的 JSON 数组	传入 --sample-content-provided 或 --no-sample-content-provided，使用普通十进制数，并确保文件内容为数组

相关技能

• gpc-setup — 货币化命令所需的身份验证和配置
• gpc-release-flow — 发布包含新商品或价格更改的应用更新
• gpc-vitals-monitoring — 监控提及账单问题的评价
• gpc-ci-integration — 在 CI/CD 中自动执行 IAP 同步和购买验证