paddle-catalog-setup

Paddle の商品と価格を作成する

このスキルを使用するタイミング

ユーザーが Paddle の連携を開始しており、他の Paddle スキル（checkout-web、pricing-pages、sandbox-testing、webhooks）で必要となる商品と価格が、アカウントにまだ登録されていない場合に、このスキルを使用して作成します。

通常、プロジェクトごとに一度だけ行うセットアップです。カタログを作成した後は、ユーザーが新しい商品や価格の追加を希望する場合を除き、このスキルを再度使用する必要はありません。

作成内容 — まずユーザーに確認すること

作成を始める前に、以下の内容についてユーザーと合意します。推測してはいけません。

• 商品と価格の違い。
  • 商品は販売するものです（「Pro プラン」、「永久ライセンス」など）。
  • 価格は請求方法です（月額 $10、年額 $96、買い切り $999 など）。
  • 1 つの商品に複数の価格を設定できます。通常は請求間隔ごとに 1 つです。
  • 市場ごとに価格を上書きすることもできます。
• 税区分（商品ごと）。以下の表から選択します。Software as a Service の場合は saas、ダウンロード可能なソフトウェアの場合は standard をデフォルトとし、作成後にその選択をユーザーに提示して確認します。その他の区分には事前承認が必要です。詳細は以下を参照してください。
• 請求モデル（価格ごと）。定期請求（サブスクリプション）では請求サイクル（例：month / year）が必要です。MCP の本文パラメーターでは billing_cycle、SDK では billingCycle を指定します。買い切り価格では省略します。トライアル期間を設定できるのはサブスクリプションのみです。買い切り価格に設定すると API が拒否します。
• トライアルの種類（定期請求の価格のみ）。トライアルが無料、有料、カード不要のいずれかを確認します。無効なトライアル設定を指定すると、該当するフィールドが errors に含まれた 400 bad_request が返されます。
  • 無料 — trial_period: { interval, frequency }。顧客はチェックアウト時に支払い方法を追加し、トライアル終了まで支払いは発生しません。
  • 有料 — トライアル料金を設定するには trial_period.unit_price（{ amount, currency_code }）を追加します。通貨は基本価格と一致させる必要があります。価格に unit_price_overrides がある場合は、すべての項目に同じ country_codes を指定した trial_period.unit_price_overrides エントリーを追加します。MCP（方法 1）または API を直接使用してください。Node SDK はまだトライアル価格に対応していません。
  • カード不要 — trial_period.requires_payment_method: false を指定すると、顧客は支払い方法なしで開始できます。カード不要のトライアルは早期アクセス段階です。アクセス権がない場合、API は 400 bad_request を返します。有料とカード不要を同時に設定することはできません。
• 価格名と数量。 description は必須の内部向け項目で、顧客には表示されません。name（任意、1～150 文字）はチェックアウト時と請求書に顧客向けに表示されます（例：「月額」）。quantity はこの価格で購入できる数量を制限し、デフォルトでは 1～100 です。座席数などで別の範囲が必要な場合は、quantity: { minimum, maximum } を設定します。
• 通貨と金額。 単価の金額（MCP では unit_price.amount、SDK では unitPrice.amount）は、通貨の最小単位で表す文字列です。USD／EUR／GBP ではセント単位です（"1000" = $10.00）。小数点以下の桁数がゼロの通貨 — JPY、KRW、VND、CLP — では整数単位を指定します（"1200" = ¥1,200／₩1,200／CLP$1,200 であり、¥12 などではありません）。通貨の小数点以下の桁数を確認するには、client.currencies.list()（MCP。単純な配列を返します）または公開されている GET /currencies エンドポイントから decimal_places を読み取ります。
• 環境。 開発時は sandbox をデフォルトにします。Sandbox と本番環境は完全に分離されているため、一方の pro_... および pri_... ID は、もう一方の環境には存在しません。本番環境を対象にする前に、ユーザーに確認します。

ID は pro_01h...（商品）および pri_01h...（価格）のような形式です。ユーザーのアプリに組み込むには価格 ID が必要なので、作成後に記録してください。

税区分

カテゴリー	用途	承認が必要ですか？
saas	ユーザーがインターネット経由でオンラインまたはクラウドベースのアプリケーションに接続して利用できる製品です。	いいえ
standard	あらかじめ作成され、ローカルデバイスにダウンロードしてインストールできるソフトウェア製品です。	いいえ
digital-goods	前払いで購入し、物理的な製品の配送なしでアクセスできる、カスタマイズ不可のデジタルファイルまたはメディア（ソフトウェアを除く）です。	はい
ebooks	顧客が永続的に利用できる権利付きで販売されるデジタル書籍および教育資料です。	はい
implementation-services	顧客に代わって行う、ソフトウェアのリモート設定、セットアップ、統合です。	はい
professional-services	ソフトウェア製品に関する専門知識や特化した知識を活用するサービスです。	はい
software-programming-services	ソフトウェア製品のカスタマイズやホワイトラベル化に利用できるサービスです。	はい
training-services	ソフトウェア製品に関連するトレーニングおよび教育サービスです。	はい
website-hosting	個人または法人の情報、資産、知的財産を保存するクラウドストレージサービスです。	はい

承認なしで利用できるのは saas と standard のみです。その他のカテゴリーを利用する場合は、ライブアカウントで Paddle > My account > Settings > Taxable categories から申請してください。未承認のカテゴリーで商品を作成すると、product_tax_category_not_approved が返されます。

方法を選択する

利用できる方法のうち、最も優先順位の高いものを選択してください。

1. Paddle MCP サーバー — ツールセットに paddle-sandbox（または paddle-live）MCP サーバーの search ツールと execute ツールがある場合は、それらを使用してください。最も迅速で、ユーザー側でコードを実行する必要がなく、結果もすぐに得られます。必ずこれを優先してください。
2. Node SDK シードスクリプト — MCP を利用できないものの、ユーザーが PADDLE_API_KEY を持っている（または生成できる）場合は、ユーザーが実行するシードスクリプトを作成してください。繰り返し実行でき、バージョン管理も可能です。
3. ダッシュボード（手動） — どちらの方法も利用できない場合は、ユーザーが実行できるように、クリックする場所を順番に案内してください。

方法の途中で失敗した場合（例：API キーに必要な権限がなく、SDK 呼び出しが forbidden を返す場合）は、再試行せずに次の方法に切り替えてください。

ユーザーが Paddle MCP サーバーをインストールしていない場合は、選択肢として提示し、Paddle MCP サーバーのインストールガイドを案内してください。

方法 1：Paddle MCP サーバー

paddle-sandbox（または paddle-live）の search ツールと execute ツールを利用できるか確認してください。利用できる場合は、それらを使用してください。

Paddle MCP は、サーバーごとに 3 つのツール（search、execute、report_missing_tool）を公開します。ワークフロー：search を呼び出して、正確なメソッド名とパラメーターの形式を確認し、次に client.<resource>.<operation>(...) を呼び出す非同期関数を指定して execute を呼び出します。メソッドパスは camelCase です（client.clientTokens.create、client.pricingPreview.preview）。本文のパラメーターとレスポンスフィールドは snake_case です（tax_category、product_id、unit_price、currency_code）。リストメソッドは data ではなく、{ pagination: { hasMore, estimatedTotal }, <resource>: [...] } を返します。配列のキーはリソースの API パスセグメントであり、メソッドパスが camelCase の場合は kebab-case になります。例：(await client.products.list()).products、(await client.clientTokens.list())["client-tokens"]。pagination.hasMore が true の間は、.next() ではなく { after: "<last_id>" } を使ってページを取得します。client.currencies.list() のようなページネーションのないリストは、プレーンな配列を返します。単一エンティティを返すメソッドは、そのエンティティを返します。複数ステップのワークフローは 1 回の execute 内で連結してください。呼び出し間で変数は保持されません。上限：execute あたり API 呼び出し 50 回、タイムアウト 30 秒、コード 32,000 文字です。

ユーザーがライブ環境を明示的に指定していない限り、デフォルトでは paddle-sandbox を使用してください。

1. ユーザーに商品詳細（名前、税カテゴリ、作成する価格）を確認します。
2. "products create" と "prices create" のようなクエリで search を呼び出し、現在のメソッド名とパラメーターの形式を確認します。
3. 商品とすべての価格を 1 回の呼び出しで作成する、1 つの非同期関数を指定して execute を呼び出します。1 回の execute 内で連結すると、往復を避け、関連する操作をアトミックに保てます。
4. 作成したすべての ID をユーザーに伝えます。ユーザーはそれらをアプリに貼り付ける必要があります。

例：商品 1 つ、月額と年額の価格、月額価格にはトライアルを設定する execute ペイロード：

async (client) => {
  const product = await client.products.create({
    name: "Pro",
    tax_category: "saas",
    description: "For scaling teams.",
  });
  const monthly = await client.prices.create({
    product_id: product.id,
    description: "Pro monthly USD",
    name: "Monthly",
    unit_price: { amount: "1000", currency_code: "USD" },
    billing_cycle: { interval: "month", frequency: 1 },
    trial_period: { interval: "day", frequency: 14 },
  });
  const yearly = await client.prices.create({
    product_id: product.id,
    description: "Pro yearly USD",
    name: "Yearly",
    unit_price: { amount: "9600", currency_code: "USD" },
    billing_cycle: { interval: "year", frequency: 1 },
  });
  return { product_id: product.id, monthly_id: monthly.id, yearly_id: yearly.id };
};

一括払いの価格（買い切りライセンスなど）の場合は、billing_cycle と trial_period を削除します。

const lifetime = await client.prices.create({
  product_id: product.id,
  description: "Pro lifetime",
  unit_price: { amount: "29900", currency_code: "USD" },
});

有料トライアルの場合は、trial_period に unit_price を追加します（価格にオーバーライドがある場合は unit_price_overrides も追加します。上記の「トライアルの種類」を参照してください）。

trial_period: {
  interval: "day",
  frequency: 14,
  unit_price: { amount: "100", currency_code: "USD" }, // $1.00 for the 14-day trial
},

地域別価格の場合は、内側のフィールド名を含め、すべて snake_case の unit_price_overrides を追加します。

unit_price_overrides: [
  {
    country_codes: ["DE", "FR", "IT", "ES", "NL"],
    unit_price: { amount: "900", currency_code: "EUR" },
  },
  { country_codes: ["GB"], unit_price: { amount: "800", currency_code: "GBP" } },
  { country_codes: ["JP"], unit_price: { amount: "1200", currency_code: "JPY" } },
];

MCP の search／execute ツールを利用できない場合は、方法 2 に進みます。

方法 2：Node SDK シードスクリプト

ユーザーが @paddle/paddle-node-sdk と PADDLE_API_KEY を持っている（またはインストールできる）場合に使用します。スクリプトを作成し、ユーザーに実行してもらいます。

1. ユーザーの環境に PADDLE_API_KEY が設定されていることを確認します。設定されていない場合は、sandbox dashboard の Paddle > My account > Settings > Authentication に案内し、API keys タブで、少なくとも product.write と price.write の権限を持つキーを作成するよう依頼します。
2. プロジェクトに @paddle/paddle-node-sdk がない場合は追加します（npm install @paddle/paddle-node-sdk）。
3. シードスクリプトを作成し、ユーザーに 1 回実行するよう依頼します。
4. 出力に表示された ID を取得し、ユーザーのアプリ設定を更新するために使用します。

テンプレート：

// scripts/seed-paddle-catalog.ts
import { Environment, Paddle } from "@paddle/paddle-node-sdk";

const paddle = new Paddle(process.env.PADDLE_API_KEY!, {
  environment: Environment.sandbox, // change to .production for live
});

async function seed() {
  const pro = await paddle.products.create({
    name: "Pro",
    taxCategory: "saas",
    description: "For scaling teams.",
  });

  const monthly = await paddle.prices.create({
    productId: pro.id,
    description: "Pro monthly USD",
    name: "Monthly",
    unitPrice: { amount: "1000", currencyCode: "USD" }, // 1000 cents = $10.00
    billingCycle: { interval: "month", frequency: 1 },
    trialPeriod: { interval: "day", frequency: 14 },
  });

  const yearly = await paddle.prices.create({
    productId: pro.id,
    description: "Pro yearly USD",
    name: "Yearly",
    unitPrice: { amount: "9600", currencyCode: "USD" },
    billingCycle: { interval: "year", frequency: 1 },
  });

  console.log(
    JSON.stringify({ productId: pro.id, monthlyId: monthly.id, yearlyId: yearly.id }, null, 2),
  );
}

seed().catch((e) => {
  console.error(e);
  process.exit(1);
});

実行方法：npx tsx scripts/seed-paddle-catalog.ts。

一括払いの価格（買い切りライセンスなど）— billingCycle と trialPeriod を削除します。

await paddle.prices.create({
  productId: pro.id,
  description: "Pro lifetime",
  unitPrice: { amount: "29900", currencyCode: "USD" },
});

地域別オーバーライド — unitPriceOverrides を追加します。

unitPriceOverrides: [
  { countryCodes: ["DE", "FR", "IT", "ES", "NL"], unitPrice: { amount: "900", currencyCode: "EUR" } },
  { countryCodes: ["GB"], unitPrice: { amount: "800", currencyCode: "GBP" } },
  { countryCodes: ["JP"], unitPrice: { amount: "1200", currencyCode: "JPY" } },
],

有料トライアル — Node SDK の trialPeriod 型にはまだ unitPrice がなく、価格のレスポンスからも値が除外されます。MCP（方法 1）または直接 POST /prices を呼び出して、有料トライアルの価格を作成してください。

スクリプトが forbidden または unauthorized で失敗する場合、API キーに必要な権限スコープがありません。ユーザーに product.write と price.write を指定してキーを再生成するよう依頼してください。SDK をインストールできない、またはインストールしたくないために失敗する場合は、方法 3 に進みます。

方法 3：ダッシュボード（手動）

最後の手段です。MCP と SDK の両方の方法が使えない場合に使用します。ユーザーに実行手順を伝え、ID を共有してもらいます。

ユーザーに次のように伝えます。

1. サンドボックスのダッシュボードにサインインします（本番環境に移行する場合はライブ環境）。
2. Paddle > Catalog > Products に移動し、New product をクリックします。次の項目を入力します。
   • Name — 例：「Pro」（チェックアウトでユーザーに表示される名前です）。
   • Tax category — <the value you agreed on above>.
   • 説明、アイコン — 任意です。
3. 商品を保存します。
4. 新しい商品を開き、New price をクリックします。次の項目を入力します。
   • Description — 内部用ラベル（例：「Pro monthly USD」）。
   • Type — Recurring（サブスクリプション）または One-time。
   • Billing cycle（Recurring の場合のみ）— Monthly、Yearly、Weekly、Daily、または Custom。
   • Trial period（Recurring の場合のみ）— 任意です。
   • Amount — 金額と通貨（例：10.00 USD）。
   • Regional prices — 市場ごとの価格上書き。任意です。
5. 価格を保存します。必要な価格ごとに繰り返します。
6. すべての価格を作成したら、価格の詳細パネルから pri_... ID をコピーし、こちらに貼り付けてもらいます。

ユーザーから ID を共有されたら、アプリの設定（定数ファイル、環境変数、または価格 ID の保存先として決めた場所）を更新します。

確認

このスキルを完了とする前に、どの方法を使用した場合でも、次の点を確認します。

1. 商品と価格が存在することを確認します。 MCP の場合 — client.products.list({ include: ["prices"] }) を 1 回 execute します。SDK の場合：paddle.products.list({ include: ["prices"] })。または、ユーザーにダッシュボードの Paddle > Catalog > Products で確認してもらいます。
2. 報告した ID が一致することを確認します。 MCP の場合：新しい商品ごとに client.products.get(productId, { include: ["prices"] }) を実行します（productId は位置指定のパスパラメーターです）。SDK の場合：paddle.products.get(id, { include: ["prices"] })。名前と税区分を確認します。
3. 次のステップを提案します。 新しい価格 ID のいずれかを使って、次に checkout-web を完了し、カタログがチェックアウトで実際に機能することを確認するよう勧めます。

よくある落とし穴

• 誤った環境で作成する。 サンドボックスと本番環境のカタログは完全に分離されています。リモート MCP では、サーバー名によって環境が決まります。サンドボックスには paddle-sandbox、本番環境には paddle-live を使用します。paddle-sandbox は pdl_sdbx_... API キーで認証し、paddle-live はブラウザーでの OAuth（または本番用 API キー）で認可します。SDK では Environment.sandbox と Environment.production を使い分けます。作成する前に、必ず環境を確認してください。
• 金額の単位を取り違える。 unit_price.amount（MCP）／unitPrice.amount（SDK）は、通貨の最小単位を表す文字列です。"1000" は 10.00 ドルであり、1000 ドルではありません。小数点以下の桁がない通貨（JPY、KRW、VND、CLP）は整数単位です。"1200" は 1,200 円／₩1,200／CLP$1,200 であり、12 円などではありません。
• 価格に商品 ID を指定し忘れる。 client.prices.create()（MCP）と paddle.prices.create()（SDK）には、どちらも親商品の ID が必要です。MCP の本文パラメーターでは product_id、SDK では productId を指定します。まず商品を作成し、その id を取得してから、各価格に渡してください。
• 買い切り価格にトライアル期間を設定する。 トライアルを設定できるのはサブスクリプションのみです。API によって拒否されます。請求サイクルがない場合は、trial_period（MCP）／trialPeriod（SDK）を省いてください。
• 請求サイクルのない定期価格を作成する。 billing_cycle（MCP）／billingCycle（SDK）を指定しないと、価格は買い切りとして作成されます。サブスクリプションでは、必ず { interval: "month", frequency: 1 }（または同様の値）を設定してください。
• MCP の execute コードでキャメルケースとスネークケースを混在させる。 メソッドパスはキャメルケース（client.clientTokens.create、client.pricingPreview.preview）ですが、本文パラメーターとレスポンスフィールドはスネークケース（tax_category、product_id、unit_price、currency_code）です。SDK では一貫してキャメルケースを使います。この規則を execute コードに持ち込んだり、逆にスネークケースの規則を SDK コードに持ち込んだりしないでください。
• 依存関係のある呼び出しを複数の execute 呼び出しに分ける。 変数は execute の呼び出し間で保持されないため、ID を渡すには、いったん返してから次の呼び出しに渡す必要があります。依存する操作（商品 → 価格 → 上書き）は、1 つの非同期関数内で連鎖させ、最後に ID を返してください。
• 妥当な基本価格を設定せずに地域別の価格上書きを使う。 上書きを設定していない国の顧客には基本価格が適用されます。ユーザーが Paddle > My account > Settings > Currencies でその通貨を有効にしている場合に限り、現地通貨に換算されます。妥当な代替価格となる基本通貨を選んでください。
• 書き込み権限がない。 リモート MCP は、認証に使用したアカウントの権限を引き継ぎます。paddle-sandbox で client.products.create() が forbidden を返す場合、API キーに product.write／price.write がありません。ユーザーに、Paddle > My account > Settings > Authentication から、これらの権限を追加して API キーを再生成するよう依頼してください。OAuth で接続した paddle-live は読み取り専用で接続を開始するため、ユーザーが Paddle > Connectors > MCPs で書き込み権限を付与するまでは、書き込み時に forbidden が返されるのは想定どおりです。ここで付与できる権限は、ユーザーの Paddle ロールによって制限されます。
• ユーザーに伝えずに、ID をユーザーのコードに貼り付ける。 新しい ID は必ずユーザーに伝え、ユーザー自身（またはユーザーの承認を得たうえであなた）が変更を明示的にコミットできるようにしてください。

関連ドキュメント

• 商品と価格の作成
• 地域別価格の設定
• Products API リファレンス
• Prices API リファレンス
• Paddle MCP サーバーのインストールガイド