通い放題プラン・回数券API の使い方

予約そのものの操作は 予約管理API をご覧ください。

必要なスコープ

予約の store.reservations.* とは別のスコープです。これらは「誰にいくら課金しているか」を読み取り、継続課金を止めることもできるため、予約台帳の参照より重い権限として分けています。

通い放題プランのエンドポイント

プランの作成

POST /api/v1/reservations/memberships/plans
Authorization: Bearer {token}
Content-Type: application/json

{
  "storeId": "store-001",
  "name": "通い放題プラン",
  "price": 12000,
  "currency": "JPY",
  "interval": "month"
}

membershipPlanId を省略すると新規作成、指定すると更新です。price は通貨の主単位で指定します（12,000円のプランなら 12000）。interval は month または year です。

料金を変更しても、すでにご加入中の方の請求額は変わりません。決済サービス側では加入時の金額で継続課金されます。

ご加入者の取得

GET /api/v1/reservations/memberships/members?storeId= は、その店舗で加入したことのある方をすべて返します。解約済みの方も含まれるのは、「この方に課金したことがあるか」を後から確認できるようにするためです。請求についてのお問い合わせは、たいていその形で来ます。

いまご利用中の方だけが必要な場合は currentOnly=true を付けてください。

{
  "count": 2,
  "members": [
    {
      "membershipId": "mem-001",
      "customerId": "crm-abc",
      "planName": "通い放題プラン",
      "status": "Active",
      "currentPeriodEnd": "2026-09-15T00:00:00Z",
      "cancelAtPeriodEnd": false
    }
  ]
}

customerId はCRMの顧客IDで、予約が紐付く顧客と同じIDです。ご加入者の予約履歴を突き合わせるときはこのIDを使ってください。

cancelAtPeriodEnd が true の方は解約手続き済みですが、お支払い済みの期間が終わるまではご利用いただけます。status はまだ Active のままである点にご注意ください。決済サービス側でも期間終了までは有効な購読として扱われます。

解約

POST /api/v1/reservations/memberships/members/{membershipId}/cancel
  ?storeId=store-001&customerId=crm-abc
Authorization: Bearer {token}

次回以降の請求を停止します。即時停止ではありません。お支払い済みの期間中はご利用いただけます。レスポンスの periodEnd がご利用いただける最終日です。

ご加入者は顧客ごとに保存されているため、membershipId だけでは特定できません。customerId を必ず付けてください。

一度も課金されていない加入には 409 を返します（停止すべき購読が存在しないため）。決済サービスに接続できない場合は 503 で、いずれの場合も加入の状態は変わりません。

回数券のエンドポイント

回数券商品を編集しても、すでに販売済みの回数券は変わりません。名称・料金・回数は購入時に回数券側へ複写されるため、あとからの編集で履歴が書き換わることはありません。

残回数の取得

GET /api/v1/reservations/passes/holders?storeId= は、その店舗で販売した回数券をすべて返します。usableOnly=true を付けると、残回数があり有効期限内のものだけになります。

status は次のいずれかです。

• Pending（お支払い手続き中。まだご利用いただけません）
• Active（ご利用中）
• Exhausted（回数を使い切り）
• Expired（有効期限切れ）
• Cancelled（取消）

他システムからの回数券の取り込み

他の予約システムから移行する場合は、CSVで回数券をまとめて取り込めます。列は name, nameKana, phone, email, passName, remainingCredits, totalCredits, expiresAt（yyyy-MM-dd）です。

取り込みの前に POST /api/v1/reservations/passes/import/preview を実行してください。何も書き込まずに、各行がどう扱われるかを行番号付きで返します。

取り込みはお客様を電話番号とメールアドレスで照合します。列の対応を取り違えたまま実行すると、ファイル内の全員について新しい顧客レコードが作られてしまいます。事前確認はそれを防ぐためのものです。

使えない行はスキップし、ファイル全体を失敗させることはありません。1行の不備で残り200行が無駄にならないようにするためです。実行後は errorCount をご確認ください。

OpenAPI定義

リクエスト・レスポンスの詳細は APIリファレンス と /openapi/v1.json をご覧ください。

関連ガイド

• 予約管理API（Reservations API）の使い方
• 定期予約・出欠・キャンセル待ちAPI の使い方
• OAuthスコープ一覧と利用可否