サブスクリプション

サブスクリプションは、顧客の定期支払いプランを管理するために使用されます。サブスクリプション API を使用すると、これらの定期的な請求契約の作成、取得、更新、キャンセル、およびライフサイクルの管理ができます。

サブスクリプション内の個々のアイテムを管理するには、サブスクリプションアイテム API を参照してください。

サブスクリプションの取得

一意の識別子によって既存のサブスクリプションの詳細を取得します。

パラメータ

Name	Type	Description
`id`	string	取得するサブスクリプションの ID。

戻り値

有効な ID が指定された場合、サブスクリプションオブジェクトを返します。TSubscriptionExpanded オブジェクトには、次のプロパティが含まれます。

Name	Type	Description
`id`	`string`	サブスクリプションの一意の識別子。
`status`	`string`	サブスクリプションのステータス (例: `active`、`trialing`、`past_due`、`canceled`)。
`customer_id`	`string`	このサブスクリプションに関連付けられている顧客の ID。
`currency_id`	`string`	このサブスクリプションで使用される通貨の ID。
`current_period_start`	`number`	現在の請求期間の開始を Unix タイムスタンプで示します。
`current_period_end`	`number`	現在の請求期間の終了を Unix タイムスタンプで示します。
`items`	`TSubscriptionItem[]`	このサブスクリプションに関連付けられているサブスクリプションアイテムの配列。
`customer`	`TCustomer`	展開された顧客オブジェクト。
`paymentCurrency`	`TPaymentCurrency`	展開された支払い通貨オブジェクト。
`paymentMethod`	`TPaymentMethod`	展開された支払い方法オブジェクト。
`metadata`	`object`	オブジェクトに添付できるキーと値のペアのセット。

例

Retrieving a subscription

async function getSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.retrieve(subscriptionId);
    console.log('Subscription retrieved:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error retrieving subscription:', error.message);
  }
}

// Example usage:
getProductDetails('sub_xxxxxxxxxxxxxx');

レスポンス例

{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "customer_id": "cus_xxxxxxxxxxxxxx",
  "currency_id": "curr_xxxxxxxxxxxxxx",
  "current_period_start": 1672531200,
  "current_period_end": 1675209600,
  "items": [
    {
      "id": "si_xxxxxxxxxxxxxx",
      "price_id": "price_xxxxxxxxxxxxxx",
      "quantity": 1
    }
  ],
  "customer": { /* ... customer details ... */ },
  "paymentCurrency": { /* ... currency details ... */ },
  "paymentMethod": { /* ... method details ... */ },
  "metadata": {}
}

サブスクリプションの更新

渡されたパラメータの値を設定して、既存のサブスクリプションを更新します。

パラメータ

Name	Type	Description
`id`	`string`	更新するサブスクリプションの ID。
`data`	`object`	更新するフィールドを含むオブジェクト。詳細は下記を参照してください。

Data オブジェクトのプロパティ

Name	Type	Description
`description`	`string`	サブスクリプションの任意の説明。
`metadata`	`object`	サブスクリプションと共に保存するキーと値のペアのセット。
`payment_behavior`	`string`	支払いの処理方法を決定します。`allow_incomplete`、`error_if_incomplete`、または `pending_if_incomplete` に設定できます。
`proration_behavior`	`string`	日割り計算の処理方法を決定します。`always_invoice`、`create_prorations`、または `none` に設定できます。
`trial_end`	`number` \| `string`	トライアル期間の終了を示す Unix タイムスタンプ。`'now'` も指定できます。
`items`	`SubscriptionUpdateItem[]`	サブスクリプションで更新するアイテムの配列。詳細は下記を参照してください。

SubscriptionUpdateItem オブジェクトのプロパティ

Name	Type	Description
`id`	`string`	更新または削除する既存のサブスクリプションアイテムの ID。
`price_id`	`string`	新しいサブスクリプションアイテムの価格の ID。
`quantity`	`number`	サブスクリプションアイテムの数量。
`deleted`	`boolean`	このサブスクリプションアイテムを削除するには `true` に設定します。
`clear_usage`	`boolean`	従量制課金の場合、削除時に使用量をクリアするかどうかを示します。

戻り値

更新されたサブスクリプションオブジェクトを返します。

例

Updating a subscription's metadata

async function updateSubscriptionMetadata(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.update(subscriptionId, {
      metadata: {
        order_id: 'order_12345'
      }
    });
    console.log('Subscription updated:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error updating subscription:', error.message);
  }
}

// Example usage:
updateSubscriptionMetadata('sub_xxxxxxxxxxxxxx');

レスポンス例

{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "metadata": {
    "order_id": "order_12345"
  }
  // ... other subscription properties
}

サブスクリプションの一覧表示

サブスクリプションのページ分割されたリストを返します。さまざまな基準に基づいてリストをフィルタリングできます。

パラメータ

Name	Type	Description
`status`	`string`	ステータスでサブスクリプションをフィルタリングします (例: `'active'`、`'trialing'`)。複数の値はカンマ区切りで指定します。
`customer_id`	`string`	特定の顧客 ID でサブスクリプションをフィルタリングします。
`customer_did`	`string`	特定の顧客 DID でサブスクリプションをフィルタリングします。
`metadata.{key}`	`string`	カスタムメタデータフィールドでフィルタリングします。
`order`	`string` \| `string[]`	ソート順 (例: `'created_at:DESC'`)。
`activeFirst`	`boolean`	`true` の場合、アクティブおよびトライアル中のサブスクリプションが最初にリストされます。
`page`	`number`	ページネーションのページ番号 (デフォルト: `1`)。
`pageSize`	`number`	1 ページあたりのアイテム数 (デフォルト: `20`)。

戻り値

ページ分割されたサブスクリプションオブジェクトのリストを返します。

Name	Type	Description
`list`	`TSubscriptionExpanded[]`	現在のページのサブスクリプションオブジェクトの配列。
`count`	`number`	クエリに一致するサブスクリプションの総数。
`paging`	`object`	ページネーションの詳細 ( `page`、`pageSize` ) を含むオブジェクト。

例

Listing all active subscriptions

async function listActiveSubscriptions() {
  try {
    const response = await payment.subscriptions.list({
      status: 'active',
      pageSize: 10
    });
    console.log(`Found ${response.count} active subscriptions.`);
    console.log('First page:', response.list);
    return response;
  } catch (error) {
    console.error('Error listing subscriptions:', error.message);
  }
}

// Example usage:
listActiveSubscriptions();

レスポンス例

{
  "count": 50,
  "list": [
    {
      "id": "sub_xxxxxxxxxxxxxx",
      "status": "active"
      // ... other subscription properties
    }
    // ... more subscriptions
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

サブスクリプションの検索

クエリ文字列に基づいてサブスクリプションの検索を実行します。

パラメータ

Name	Type	Description
`query`	`string`	サブスクリプションのフィールドと照合する検索文字列。
`page`	`number`	ページネーションのページ番号 (デフォルト: `1`)。
`pageSize`	`number`	1 ページあたりのアイテム数 (デフォルト: `20`)。

戻り値

検索クエリに一致するサブスクリプションオブジェクトのページ分割されたリストを返します。

例

Searching for a subscription

async function searchForSubscription(query) {
  try {
    const response = await payment.subscriptions.search({ query });
    console.log(`Search results for "${query}":`, response.list);
    return response;
  } catch (error) {
    console.error('Error searching subscriptions:', error.message);
  }
}

// Example usage:
searchForSubscription('some_customer_did');

サブスクリプションのキャンセル

顧客のサブスクリプションをキャンセルします。サブスクリプションは即時、または現在の請求期間の終了時にキャンセルできます。

パラメータ

Name	Type	Description
`id`	`string`	キャンセルするサブスクリプションの ID。
`body`	`object`	キャンセルの詳細を含むオブジェクト。

Body オブジェクトのプロパティ

Name	Type	Description
`at`	`string`	いつキャンセルするか。`'now'`、`'current_period_end'`、または `'custom'` を指定できます。デフォルトは `'current_period_end'` です。
`time`	`number` \| `string`	`at` が `'custom'` の場合に必須です。キャンセルのための将来の Unix タイムスタンプ。
`refund`	`string`	返金を行うかどうかを指定します。`'none'`、`'proration'`、または `'last'` を指定できます。
`feedback`	`string`	キャンセルに関する顧客からのフィードバック。
`comment`	`string`	キャンセルに関する内部コメント。
`reason`	`string`	キャンセルの理由 (例: `'cancellation_requested'`)。

戻り値

キャンセルの詳細を含む、更新されたサブスクリプションオブジェクトを返します。

例

Canceling a subscription at period end

async function cancelSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.cancel(subscriptionId, {
      at: 'current_period_end',
      reason: 'cancellation_requested'
    });
    console.log('Subscription scheduled for cancellation:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error canceling subscription:', error.message);
  }
}

// Example usage:
cancelSubscription('sub_xxxxxxxxxxxxxx');

サブスクリプションの回復

キャンセルがスケジュールされているが、まだキャンセルされていないサブスクリプションを再アクティブ化します。

パラメータ

Name	Type	Description
`id`	`string`	回復するサブスクリプションの ID。

戻り値

更新されたアクティブなサブスクリプションオブジェクトを返します。

例

Recovering a canceled subscription

async function recoverSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.recover(subscriptionId);
    console.log('Subscription recovered:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error recovering subscription:', error.message);
  }
}

// Example usage:
recoverSubscription('sub_xxxxxxxxxxxxxx');

サブスクリプションの一時停止

サブスクリプションの支払い収集を一時停止します。

パラメータ

Name	Type	Description
`id`	`string`	一時停止するサブスクリプションの ID。
`body`	`object`	一時停止の詳細を含むオブジェクト。

Body オブジェクトのプロパティ

Name	Type	Description
`behavior`	`string`	一時停止中に作成された請求書の動作。`'keep_as_draft'`、`'mark_uncollectible'`、または `'void'` を指定できます。
`resumes_at`	`number`	サブスクリプションが自動的に再開される Unix タイムスタンプ。

戻り値

paused ステータスを持つ、更新されたサブスクリプションオブジェクトを返します。

例

Pausing a subscription

async function pauseSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.pause(subscriptionId, {
      behavior: 'keep_as_draft'
    });
    console.log('Subscription paused:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error pausing subscription:', error.message);
  }
}

// Example usage:
pauseSubscription('sub_xxxxxxxxxxxxxx');

サブスクリプションの再開

一時停止されたサブスクリプションの支払い収集を再開します。

パラメータ

Name	Type	Description
`id`	`string`	再開するサブスクリプションの ID。

戻り値

更新されたアクティブなサブスクリプションオブジェクトを返します。

例

Resuming a subscription

async function resumeSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.resume(subscriptionId);
    console.log('Subscription resumed:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error resuming subscription:', error.message);
  }
}

// Example usage:
resumeSubscription('sub_xxxxxxxxxxxxxx');

サブスクリプションの削除

サブスクリプションとその関連データを完全に削除します。この操作は元に戻すことができず、非本番環境でのみ使用してください。

パラメータ

Name	Type	Description
`id`	`string`	削除するサブスクリプションの ID。

戻り値

削除されたサブスクリプションオブジェクトを返します。

例

Deleting a subscription

async function deleteSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.del(subscriptionId);
    console.log('Subscription deleted:', subscription);
    return subscription;
  } catch (error) {
    console.error('Error deleting subscription:', error.message);
  }
}

// Example usage:
deleteSubscription('sub_xxxxxxxxxxxxxx');

延滞請求書の一覧表示

特定のサブスクリプションの延滞 (回収不能) 請求書のリストを、支払期日を過ぎた金額の概要と共に取得します。

パラメータ

Name	Type	Description
`id`	`string`	サブスクリプションの ID。

戻り値

サブスクリプション、延滞請求書のリスト、および通貨ごとの未払い総額の概要を含むオブジェクトを返します。

Name	Type	Description
`subscription`	`TSubscription`	サブスクリプションオブジェクト。
`invoices`	`TInvoice[]`	延滞請求書オブジェクトの配列。
`summary`	`object`	各通貨の延滞総額を要約したオブジェクト。

例

Fetching overdue invoices

async function getOverdueInvoices(subscriptionId) {
  try {
    const result = await payment.subscriptions.overdueInvoices(subscriptionId);
    console.log('Overdue Invoices Summary:', result.summary);
    console.log('Invoices:', result.invoices);
    return result;
  } catch (error) {
    console.error('Error fetching overdue invoices:', error.message);
  }
}

// Example usage:
getOverdueInvoices('sub_xxxxxxxxxxxxxx');

ステークの返還

ArcBlock 支払い方法を使用したキャンセル済みサブスクリプションに関連付けられたステーク資金の返還プロセスを開始します。

パラメータ

Name	Type	Description
`id`	`string`	キャンセルされたサブスクリプションの ID。

戻り値

ステーク返還ジョブのスケジュールが成功したことを示すオブジェクトを返します。

Name	Type	Description
`success`	`boolean`	ステーク返還ジョブが正常にスケジュールされた場合は `true`。
`subscriptionId`	`string`	ステークが返還されるサブスクリプションの ID。

例

Returning a stake

async function returnSubscriptionStake(subscriptionId) {
  try {
    const result = await payment.subscriptions.returnStake(subscriptionId);
    console.log('Stake return initiated:', result);
    return result;
  } catch (error) {
    console.error('Error returning stake:', error.message);
  }
}

// Example usage:
returnSubscriptionStake('sub_xxxxxxxxxxxxxx');