Next.jsやFirebaseを用いたアプリ開発において、Square決済のサブスクリプション実装は強力な選択肢です。しかし、いざ実装を始めると「API経由で決済するために必要な各種IDがどこにあるかわからない」という壁にぶつかることが少なくありません。
特にサンドボックス環境では、ダッシュボード上の表示とAPIで扱うIDが異なるため、正確な紐付けが不可欠です。
本記事では、Square API Explorerを活用して、カタログ商品（Item）、バリエーション、そしてサブスクリプションプランのIDを確実に特定する手順を解説しています。
また、テストをスムーズに進めるための商品作成のコツも併せてご紹介しています。
Square Developer Consoleでアプリケーションを作成する
サンドボックス環境で開発を行うために、Square Developer Consoleにログインします。
＞ https://developer.squareup.com/console/en/apps
左メニューの「Applications」を選択し、アプリケーションを作成します。
OAuthへの登録とアクセストークンの発行
作成したアプリケーションのAPI通信を行うために、OAuthに登録します。
先ほど作成したアプリに入り、左メニューの「OAuth」をクリックします。
「Authorize test account」をクリックします。
プルダウンから先ほど作成したアプリを選択し、「Save」をクリックします。Permissionsは全て✓が入った状態（デフォルトのまま）でOKです。
追加された「Access token」をAPI通信で使用します。
サンドボックスのSquareデータを作成する
続いて、商品登録をするために、サンドボックスのSquareデータを作成します。
Sqaure Developer Cosleに戻り、左メニューの「Sandbox test accounts」でサンドボックスを作成します。
追加すると「Square Dashboard」へのリンクが追加されます。
商品の作成（Catalog Item ID,Item Variation ID）
商品（Catalog Item）の作成
サンドボックスのSqaureダッシュボードに入り「商品とサービス ＞ 商品 ＞ 商品ライブラリ」に進みます。
「商品を登録」をクリックし、名前、フリガナ、商品説明などを入力します。
店舗も選択します。
この状態で保存します。
ここで登録した商品に「Item Id」が付きます。これが商品そのものです。
バリエーション（Item Variation）の作成
続いて、バリエーションを追加します。このバリエーションがプランの種類となり、各々金額を設定します。
例えば、1つの商品に、3つのプランを作成する場合は以下のようになります。
ここで登録した各バリエーション毎に「Item Variation ID」が付きます。これが各商品の金額そのものです。
単発決済を行う場合は、ここまででOKです。
サブスクリプションの作成と紐づけ（Subscription Plan IDとSubscription Plan Variation ID）
月額課金などのサブスクリプションにしたい場合は、サブスクリプションの作成と商品との紐づけをする必要があります。
サブスクリプションの作成（Subscription Plan ID）
「商品とサービス」の一番したにある「サブスクリプション」をクリックします。
「プランを作成」をクリックして「頻度オプションを追加」します。
頻度を選択して「追加」すれば、月額のサブスクの設定ができます。
ここで登録した月額のサブスク自体が月額課金ルールそのものとなり、「Subscription Plan ID」が付与されます。
サブスクリプションを商品に紐づける（Subscription Plan Variation ID）
サブスクリプションのプランの作成画面で「商品を割り当てる」をクリックして、先ほど作成した商品を選択します。
こうすることで、指定した商品の中にある各バリエーションとサブスクリプションのルール（ここでは月額課金）が紐づきます。
商品のバリエーションに「Subscription Plan ID」が紐づきます。
ブラウザ（API Explorer)で各IDを確認する
作成した「Catalog Item」「Catalog Variation」「Subscription Plan」「Subscription Plan Variation」の各idを確認するには、Squareが提供している「Square API Explorer」を使います。
＞ https://developer.squareup.com/explorer/square
上部メニューで「Catalog」「Search catalog objects」を選択します。
「Select token」に先ほどOAuthで作成したトークンを貼り付けます。
「Select」をクリックすると登録したアプリのトークンが表示されますが、これはSquare Developerに登録したアプリ（Application）自体のAPIトークンであり、アクセスしたいロケーションのものではありません。
必ず、Squareデータから対象のアプリを選択し「OAuth > Test account authorizaitons > Access token」のトークンをコピーして貼り付けてください。
検索クエリとなるBodyの条件を設定します。
- 「begin_time」を空にする。
- 「include_deleted_objects」をFalseにする。
- 「include_related_objects」をTrueにする。
この状態で、上部の「Run Request」ボタンをクリックします。
すると登録した商品のデータがResponseに返ってきます。
// cache-control: max-age=0, private, must-revalidate
// content-encoding: gzip
// content-type: application/json
// date: Sat, 09 May 2026 21:48:00 GMT
// square-version: 2026-01-22
{
"objects": [
{
"type": "ITEM",
"id": "N3DEFNUYXZSJ7S4XQ3OTAR4Q",
"updated_at": "2026-05-09T21:45:25.508Z",
"created_at": "2026-05-09T10:13:14.179Z",
"version": 1778363125508,
"is_deleted": false,
"present_at_all_locations": true,
"absent_at_location_ids": [
"L38G6A0ZAXFWM"
],
"item_data": {
"name": "XXX",
"description": "YYY",
"label_color": "19802A",
"is_taxable": true,
"variations": [
{
"type": "ITEM_VARIATION",
"id": "442VRXFVSC3OIY2GRTC22AUK",
"updated_at": "2026-05-09T21:45:25.508Z",
"created_at": "2026-05-09T10:13:14.179Z",
"version": 1778363125508,
"is_deleted": false,
"present_at_all_locations": true,
"absent_at_location_ids": [
"L38G6A0ZAXFWM"
],
"item_variation_data": {
"item_id": "N3DEFNUYXZSJ7S4XQ3OTAR4Q",
"name": "ZZZ",
"sku": "ZZZ",
"ordinal": 1,
"pricing_type": "FIXED_PRICING",
"price_money": {
"amount": 4400,
"currency": "JPY"
},
"location_overrides": [
{
"location_id": "L38G6A0ZAXFWM",
"track_inventory": false
}
],
"track_inventory": false,
"sellable": true,
"stockable": true,
"subscription_plan_ids": [
"PHZY2PGNF6VBB2NLKBOVCXC4"
]
}
},
・・・
{
"type": "SUBSCRIPTION_PLAN",
"id": "PHZY2PGNF6VBB2NLKBOVCXC4",
"updated_at": "2026-05-09T19:52:46.598Z",
"created_at": "2026-05-09T10:13:49.439Z",
"version": 1778356366598,
"is_deleted": false,
"present_at_all_locations": true,
"subscription_plan_data": {
"name": "AAA",
"subscription_plan_variations": [
{
"type": "SUBSCRIPTION_PLAN_VARIATION",
"id": "3PQOHI2ET4PDDVUR5RE5T373",
"updated_at": "2026-05-09T19:52:46.598Z",
"created_at": "2026-05-09T10:13:49.439Z",
"version": 1778356366598,
"is_deleted": false,
"present_at_all_locations": true,
"subscription_plan_variation_data": {
"name": "BBB",
"phases": [
{
"uid": "ZELDRKVLDKMUSA23JH255QTU",
"cadence": "MONTHLY",
"ordinal": 0,
"pricing": {
"type": "RELATIVE"
}
}
],
"subscription_plan_id": "PHZY2PGNF6VBB2NLKBOVCXC4"
}
}
],
この中の「”type”: “ITEM_VARIATION”」の「id」がItem Variation Idです。
"variations": [
{
"type": "ITEM_VARIATION",
"id": "442VRXFVSC3OIY2GRTC22AUK",★重要：「Item Variation Id」が〇〇円という金額そのものです。
この中の「subscription_plan_ids」がSubscription Plan Idです。
"subscription_plan_ids": [
"PHZY2PGNF6VBB2NLKBOVCXC4"この中の「”type”: “SUBSCRIPTION_PLAN_VARIATION”」の「id」がSubscription Plan Variation Idです。
"type": "SUBSCRIPTION_PLAN_VARIATION",
"id": "3PQOHI2ET4PDDVUR5RE5T373",★重要：「Subscription Plan Variation Id」が課金サイクルです。
