サブスクリプションの課金サイクルの終了

Owned by DiceK Mikami (Unlicensed)
Last updated: 2020 Apr 02 by 二宮力也
1 min read

ユーザーのサブスクリプションの課金サイクルが終了した際に発行されるWebHookについて説明します。

サービス定義の使用実績のプランを含むサブスクリプションでは、このWebHookに対してレスポンスを返却する必要があります。


概要

ユーザーのサブスクリプションに紐づく課金サイクルが終了した際にpayments/change_billing_period WebHookが発行されます。

課金サイクル更新のWebHookは、バージョン2のみ送信されます。

課金サイクルの終了は、ユーザーに対して利用料金が請求される際のことになります。
このWebHookは、サブスクリプションが月額課金の場合は毎月料金の請求日に発行され、年額課金の場合は毎年料金の請求日に発行されます。

このWebHookに含まれる期間は、次回の利用期間と同じになります。　

リクエストボディ

以下のJSONフォーマットでCloudGearからCloudGearアプリケーションにHTTPリクエストが送信されます。

event="payments", type="change_billing_period"
{
  "id": "91018c24-4182-4e20-8509-501471b6304f", // UUID
  "event": "payments",
  "type": "change-billing-period",
  "created_at": 1576200980964, // 作成日時
  "version": 2, // WebHookのバージョン
  "data": {
    "subscription_id": "sub_1234567890", // サブスクリプションID
    "service_id": 1, // サービスID
    "square_id"： "service-square-id", // サービススクエアID
    "period_start": 123456789, // 次回のサブスクリプションの適用開始日時（秒）
    "period_end": 987654321 // 次回のサブスクリプションの適用終了日時（秒）
  }
}

サービス定義の使用実績のプランを含むサブスクリプションの場合

「サービス定義の使用実績」のプランを含むサブスクリプションでは、発行されるWebHookに対してレスポンスを返していただく必要があります。

課金サイクルが変わる前に請求期間内の使用量の最終値を送っていただきます。
その後、サービス側で使用量のリセットをしていただく必要があります。

レスポンスボディ

以下のJSONフォーマットでCloudGearアプリケーションからCloudGearにHTTPリクエストを返してください。

{
  [{
    "subscription_id": "sub_1234567890", // サブスクリプションID
    "plan_id": "plan_1", // プランID
    "quantity": 100L, // 使用量の最新値
    "timestamp": 123456789, //使用量報告日時（秒)
    "service_id": 1 // サービスID
  },{
    "subscription_id": "sub_1234567890", // サブスクリプションID
    "plan_id": "plan_2", // プランID
    "quantity": 200L, // 使用量の最新値
    "timestamp": 123456789, //使用量報告日時（秒)
    "service_id": 1 // サービスID
  }]
}