revenuecat-store-state

管理产品商店状态

商店状态是价格、可用性、本地化内容和优惠的事实来源。读取会立即返回。写入通过产品商店状态计划进行：创建草稿，计算可供审核的差异，然后应用。在应用计划之前，任何内容都不会写入商店。

MCP 和 rc CLI（请参阅 revenuecat-cli 技能）使用相同的计划／应用模式。优先使用可用的方式。有关准确参数，请参阅 MCP 工具的架构（或运行 rc commands --schemas --json）。

每个项目最多只能有一个活动计划（非终态）。创建新计划前先列出计划；如果创建失败，原因是已有计划正在进行，请获取该计划，说明待处理的内容，并与用户确认是继续还是丢弃。

读取

始终使用 get-product-store-state（CLI：rc products show <product-id> --store-state）。切勿根据 get-product、list-products 或权益数据推断商店价格、可用性或试用期——这些属于 RevenueCat 目录，而非商店状态。展示响应中的 warnings。

如果 store_status.status 为 could_not_check，表示 RevenueCat 无法读取商店：pricing、availability 或 localizations 为空意味着读取失败，而非未配置任何内容。应说明无法从商店读取该产品，不要猜测原因——切勿说该产品没有商店价格。

前提条件

写入商店状态需要将商店凭据连接到 RevenueCat 项目（App Store Connect API 密钥，或拥有 Manage store presence 权限的 Google Play 服务账号），并且 RevenueCat 登录账号需拥有该项目的写入权限。如果写入因凭据或权限错误而失败，请说明缺少什么以及如何解决（在控制面板的应用设置中配置商店凭据），不要重试。

应用前确认

应用操作会写入生产商店，并可能改变实际客户看到和支付的内容。在展示计划中的差异并获得用户明确确认之前，绝不要调用 apply。

计划成功后：

1. 用通俗语言总结 summary 和每个 plan_items[*].diff（逐字段说明变更前 → 变更后）。
2. 原样报告所有警告（severity、field、message），包括 warnings 和 plan_items[*].warnings 中的警告。绝不要降低阻塞级别，也不要辩称验证器不适用于该商店（不要说“地区限制有阻塞项，但不适用于 Play——正在应用”）。如果任何 plan_items[*].warnings 的 severity 为 blocker，绝不要应用计划。修正目标状态、更新计划并重新规划，直到没有项目级阻塞项。
3. 分享每个所述计划的控制面板审核 URL——包括规划失败的计划（页面会显示错误）以及阻止新计划创建的现有计划： https://app.revenuecat.com/projects/{project_id}/product-catalog/product-editor/review-changes?plan_id={plan_id} draft 尚无审核页面；应改为说明其内容。
4. 等待用户明确同意。逐一确认每个产品的变更，或将其作为一批清晰列出的变更统一确认——绝不要把无关变更合并为一次确认。
5. 只有在 actions 包含 apply 时，才调用 apply。

读取无需确认。将产品提交给 Apple 审核属于另一项需要单独确认的写入操作（submit-products-to-store）。

推荐的写入流程（MCP）

1. 先检查。 在决定所需变更之前，对现有产品调用 get-product-store-state。
2. 创建草稿计划。 调用 create-product-store-state-plan，每个产品对应一个 desired_states 条目。
   • 将现有 RevenueCat 产品作为目标，提供 product_id；或传入 create_revenuecat_product（app_id、store_identifier、type、display_name 和 title——如果用户只提供了一个名称，则两个字段都使用该名称）。
   • 将 store 设为 app_store、play_store、rc_billing 或 test_store，并填写匹配的 store_state。
   • 在所需状态中填写价格、可用性、本地化内容，以及用户提供的审核截图。不要调用 create-product-prices、upload-product-store-state-screenshot 或 equalize-subscription-prices。
   • App Store 订阅：将要保留的价格传入 territory_prices，并加入 common.pricing.equalize_missing_subscription_prices，设置 base_territory，以便在应用时填充缺失的 Apple 区域。App Store 一次性产品不要传入该字段。
   • App Store 审核截图：除非用户提供了图片，否则省略截图，以便应用时上传空白占位图。
   • RC Billing / Test Store：价格应填写在 common.pricing.currency_prices 中（仅用于创建；更新现有币种会被拒绝）。这里不支持价格均衡，因此每种币种的价格都必须由用户提供。
   • Play Store 订阅：设置 store_state.base_plans[<id>].other_regions_config.usd_price（如果涉及欧元区，也设置 eur_price），以便 Google 自动填充未列出的区域；仅对用户要覆盖的区域使用 regional_configs[<region>].price。
   • 切勿臆造区域或币种价格，也不要使用汇率进行换算。如果用户没有提供某个区域的价格，请询问是否要通过上述商店机制以另一种币种的价格填充。所有价格均使用 amount_micros（1 个单位 = 1,000,000 微单位）。
   • 已批准的 App Store 订阅（通过 get-product-store-state 检查）：Apple 不会立即应用价格或首购优惠变更。对每个要更改的 territory_prices[<territory>] 条目，以及要新增的任何首购／试用优惠，都设置未来的 start_date（次日即可），否则 Apple 会拒绝变更，应用流程也会在该区域停止。对未设价格的区域，继续使用 equalize_missing_subscription_prices；它会将基准区域的 start_date 带入这些区域。告知用户变更生效时间，并在同一轮中创建计划；不要仅因为日期而在规划前征求确认。
   • 所需状态是补丁：省略的字段保持不变，映射值为 null 会删除该条目，territories: false 会移除可用性。
3. 规划。 调用 plan-product-store-state-plan，然后轮询 get-product-store-state-plan，直到状态为 planned、planned_and_finished 或 plan_errored。
4. 与用户审核。 遵循应用前确认。如果规划失败，报告 error_message／各项错误和审核 URL；不要应用。
5. 应用。 调用 apply-product-store-state-plan。然后轮询 get-product-store-state-plan，直到状态为 applied 或 apply_errored。分享进度 URL：https://app.revenuecat.com/projects/{project_id}/product-catalog/product-editor/commit-to-store?plan_id={plan_id}。如果应用预计需要超过约 10 分钟，请停止轮询，告知预计完成时间，并引导用户访问该页面（或稍后再来询问）。报告每个产品的 apply_status 和任何 apply_error_message。应用会在首个失败项处停止，之前已处理的项会保留；重试时只会重新执行未应用的项。如果应用失败是因为商店在规划后发生了变化，请告知用户，并基于最新状态创建新计划。
6. 准备就绪后提交审核。 仅适用于 App Store：应用成功后，变更已进入 App Store Connect，但尚未提交给 Apple。可为刚刚应用的产品调用 submit-products-to-store（确认写入）。只提交用户要求提交的产品，或刚刚应用的产品（apply_status: applied，或出现在 get-product-store-state 中的产品）；绝不要提交所有看似准备就绪的产品。报告各产品的结果，包括跳过的产品；如果提交失败，说明原因并停止。Play Store、RC Billing 和 Test Store 跳过此步骤。 要放弃草稿或已规划的计划，请使用 discard-product-store-state-plan。要更改草稿，请先使用 update-product-store-state-plan，然后重新规划。

注意事项

• App Store 本地化：名称不得超过 30 个字符，描述不得超过 45 个字符。API 会接受更长的值，但 Apple 会在应用时拒绝这些值。
• 无法删除商店产品。要停用某个产品，请将其销售地区设为 false（并将 Play 基础方案移出 ACTIVE），然后使用 archive-product，以便该产品也不再显示在 RevenueCat 中。

CLI 对应命令

有关安装、身份验证和架构发现，请参阅 revenuecat-cli 技能。对应关系如下：

• 读取：rc products show <product-id> --store-state
• 创建并计算差异：rc products store plan <app-id> --file <csv|json>
• 重新显示已保存的计划：rc products store show <plan-id>
• 应用 / 放弃：rc products store apply <plan-id> / rc products store discard <plan-id>

CLI 的 apply 会等待操作完成（无需单独轮询）。仍需先显示计划差异并等待确认，然后再执行 apply。使用 rc commands --schemas --json 确认准确的标志。

请勿使用这些 MCP 工具执行写入操作

这些工具可能仍会显示在 MCP 目录中。它们会直接写入单个产品，且不会提供可预览的计划。请优先使用上述计划工具。

• set-product-store-state
• get-product-store-state-operation
• create-product-prices
• upload-product-store-state-screenshot
• equalize-subscription-prices