revenuecat-store-state

商品ストアの状態の管理

ストアは、価格、提供状況、ローカライズ、オファーの信頼できる唯一の情報源です。読み取りは即時に行われます。書き込みは商品ストア状態プランを通じて行います。ドラフトを作成し、確認可能な差分を算出してから適用します。プランが適用されるまで、ストアに変更は反映されません。

MCP と rc CLI（revenuecat-cli スキルを参照）は、同じプラン／適用モデルを使用します。利用可能な方を選んでください。正確なパラメーターについては、MCP ツールのスキーマ（または rc commands --schemas --json）を参照してください。

プロジェクトごとに、アクティブな（終端状態でない）プランは最大 1 件です。新しいプランを作成する前にプランの一覧を確認してください。すでに進行中のプランがあるため作成に失敗した場合は、そのプランを取得して保留中の内容を説明し、続行するか破棄するかをユーザーと相談してください。

読み取り

必ず 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. warnings と plan_items[*].warnings の両方から、すべての警告（severity、field、message）を一字一句そのまま報告します。ブロッカーを軽視したり、そのバリデーターはこのストアには適用されないと主張したりしてはいけません（「territories のブロッカーですが、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. ドラフトプランを作成します。 製品ごとに 1 つの desired_states エントリを指定して create-product-store-state-plan を実行します。
   • product_id で既存の RevenueCat 製品を指定するか、create_revenuecat_product（app_id、store_identifier、type、display_name、title）を渡します。ユーザーが名前を 1 つだけ指定した場合は、両方にその名前を使用します。
   • 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 に指定し、適用時に価格が未設定の Apple の地域を補完するため、base_territory を指定した common.pricing.equalize_missing_subscription_prices を含めます。App Store の買い切り製品では、このフィールドを指定しないでください。
   • App Store の審査用スクリーンショットは、ユーザーが画像を提供していない場合、適用時に空のプレースホルダーをアップロードできるように省略します。
   • RC Billing／Test Store では、価格は common.pricing.currency_prices です（新規作成時のみ使用可能で、既存の通貨の更新は拒否されます）。価格の均等化は行われないため、すべての通貨をユーザーに指定してもらう必要があります。
   • Play Store のサブスクリプションでは、Google がリストにない地域を補完できるように、store_state.base_plans[<id>].other_regions_config.usd_price（ユーロ圏が関係する場合は eur_price も）を設定します。regional_configs[<region>].price は、ユーザーが変更を希望する地域にのみ使用します。
   • 地域または通貨の価格を推測したり、為替レートで換算したりしないでください。ユーザーがある地域の価格を指定していない場合は、上記のストアの仕組みを使って別の通貨から補完するか、ユーザーに確認します。すべての価格は amount_micros で指定します（1 単位 = 1,000,000 micros）。
   • 承認済みの 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 を実行し、ステータスが planned、planned_and_finished、または plan_errored になるまで get-product-store-state-plan をポーリングします。
4. ユーザーと内容を確認します。 適用前の確認 に従います。プラン作成に失敗した場合は、error_message／アイテムごとのエラーとレビュー URL を報告し、適用しないでください。
5. 適用します。 apply-product-store-state-plan を実行します。その後、ステータスが applied または apply_errored になるまで get-product-store-state-plan をポーリングします。進捗 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 以外に変更してから）、RevenueCat にも表示されないようにする場合は archive-product を実行します。

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 カタログに表示される場合がありますが、プレビュー可能なプランを作成せずに商品を 1 つ書き込みます。上記のプランツールを優先してください。

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