跳到主要內容

訂閱

訂閱用於管理客戶的定期付款計畫。訂閱 API 允許您建立、擷取、更新、取消和管理這些定期計費安排的生命週期。

若要管理訂閱中的個別項目，請參閱 訂閱項目 API。

擷取訂閱

透過其唯一識別碼取得現有訂閱的詳細資訊。

參數

名稱類型描述
idstring要擷取的訂閱 ID。

傳回值

如果提供了有效的 ID，則傳回一個訂閱物件。TSubscriptionExpanded 物件包含以下屬性：

名稱類型描述
idstring訂閱的唯一識別碼。
statusstring訂閱的狀態（例如，active、trialing、past_due、canceled）。
customer_idstring與此訂閱關聯的客戶 ID。
currency_idstring此訂閱使用的貨幣 ID。
current_period_startnumber目前計費週期的開始時間，以 Unix 時間戳表示。
current_period_endnumber目前計費週期的結束時間，以 Unix 時間戳表示。
itemsTSubscriptionItem[]與此訂閱關聯的訂閱項目陣列。
customerTCustomer展開的客戶物件。
paymentCurrencyTPaymentCurrency展開的付款貨幣物件。
paymentMethodTPaymentMethod展開的付款方式物件。
metadataobject一組您可以附加到物件上的鍵值對。

範例

擷取訂閱

javascript
async function getSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.retrieve(subscriptionId);
    console.log('已擷取訂閱：', subscription);
    return subscription;
  } catch (error) {
    console.error('擷取訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
getProductDetails('sub_xxxxxxxxxxxxxx');

範例回應

json
{
  "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": { /* ... 客戶詳細資訊 ... */ },
  "paymentCurrency": { /* ... 貨幣詳細資訊 ... */ },
  "paymentMethod": { /* ... 付款方式詳細資訊 ... */ },
  "metadata": {}
}

更新訂閱

透過設定傳入參數的值來更新現有訂閱。

參數

名稱類型描述
idstring要更新的訂閱 ID。
dataobject包含要更新欄位的物件。詳情請見下方。

資料物件屬性

名稱類型描述
descriptionstring訂閱的可選描述。
metadataobject一組與訂閱一起儲存的鍵值對。
payment_behaviorstring決定如何處理付款。可以是 allow_incomplete、error_if_incomplete 或 pending_if_incomplete。
proration_behaviorstring決定如何處理按比例分配。可以是 always_invoice、create_prorations 或 none。
trial_endnumber | string表示試用期結束的 Unix 時間戳。也可以是 'now'。
itemsSubscriptionUpdateItem[]要在訂閱上更新的項目陣列。詳情請見下方。

SubscriptionUpdateItem 物件屬性

名稱類型描述
idstring要更新或刪除的現有訂閱項目 ID。
price_idstring新訂閱項目的價格 ID。
quantitynumber訂閱項目的數量。
deletedboolean設定為 true 以刪除此訂閱項目。
clear_usageboolean對於計量計費，表示是否在刪除時清除用量。

傳回值

傳回更新後的訂閱物件。

範例

更新訂閱的元資料

javascript
async function updateSubscriptionMetadata(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.update(subscriptionId, {
      metadata: {
        order_id: 'order_12345'
      }
    });
    console.log('已更新訂閱：', subscription);
    return subscription;
  } catch (error) {
    console.error('更新訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
updateSubscriptionMetadata('sub_xxxxxxxxxxxxxx');

範例回應

json
{
  "id": "sub_xxxxxxxxxxxxxx",
  "status": "active",
  "metadata": {
    "order_id": "order_12345"
  }
  // ... 其他訂閱屬性
}

列出訂閱

傳回分頁的訂閱列表。您可以根據各種條件篩選列表。

參數

名稱類型描述
statusstring按狀態篩選訂閱（例如 'active'、'trialing'）。多個值以逗號分隔。
customer_idstring按特定客戶 ID 篩選訂閱。
customer_didstring按特定客戶 DID 篩選訂閱。
metadata.{key}string按自訂元資料欄位篩選。
orderstring | string[]排序順序（例如 'created_at:DESC'）。
activeFirstboolean如果為 true，則優先列出有效和試用中的訂閱。
pagenumber分頁的頁碼（預設為 1）。
pageSizenumber每頁的項目數（預設為 20）。

傳回值

傳回分頁的訂閱物件列表。

名稱類型描述
listTSubscriptionExpanded[]目前頁面的訂閱物件陣列。
countnumber符合查詢條件的訂閱總數。
pagingobject包含分頁詳細資訊（page、pageSize）的物件。

範例

列出所有有效訂閱

javascript
async function listActiveSubscriptions() {
  try {
    const response = await payment.subscriptions.list({
      status: 'active',
      pageSize: 10
    });
    console.log(`找到 ${response.count} 個有效訂閱。`);
    console.log('第一頁：', response.list);
    return response;
  } catch (error) {
    console.error('列出訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
listActiveSubscriptions();

範例回應

json
{
  "count": 50,
  "list": [
    {
      "id": "sub_xxxxxxxxxxxxxx",
      "status": "active"
      // ... 其他訂閱屬性
    }
    // ... 更多訂閱
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

搜尋訂閱

根據查詢字串執行訂閱搜尋。

參數

名稱類型描述
querystring要與訂閱欄位匹配的搜尋字串。
pagenumber分頁的頁碼（預設為 1）。
pageSizenumber每頁的項目數（預設為 20）。

傳回值

傳回符合搜尋查詢的分頁訂閱物件列表。

範例

搜尋訂閱

javascript
async function searchForSubscription(query) {
  try {
    const response = await payment.subscriptions.search({ query });
    console.log(`"${query}" 的搜尋結果：`, response.list);
    return response;
  } catch (error) {
    console.error('搜尋訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
searchForSubscription('some_customer_did');

取消訂閱

取消客戶的訂閱。訂閱可以立即取消，也可以在目前計費週期結束時取消。

參數

名稱類型描述
idstring要取消的訂閱 ID。
bodyobject包含取消詳細資訊的物件。

Body 物件屬性

名稱類型描述
atstring取消時間。可以是 'now'、'current_period_end' 或 'custom'。預設為 'current_period_end'。
timenumber | string如果 at 為 'custom' 則為必填。一個未來的 Unix 時間戳，用於取消。
refundstring指定是否應發放退款。可以是 'none'、'proration' 或 'last'。
feedbackstring客戶對取消的回饋。
commentstring關於取消的內部評論。
reasonstring取消原因（例如 'cancellation_requested'）。

傳回值

傳回包含取消詳細資訊的更新後訂閱物件。

範例

在週期結束時取消訂閱

javascript
async function cancelSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.cancel(subscriptionId, {
      at: 'current_period_end',
      reason: 'cancellation_requested'
    });
    console.log('訂閱已排程取消：', subscription);
    return subscription;
  } catch (error) {
    console.error('取消訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
cancelSubscription('sub_xxxxxxxxxxxxxx');

恢復訂閱

重新啟用已排程取消但尚未被取消的訂閱。

參數

名稱類型描述
idstring要恢復的訂閱 ID。

傳回值

傳回更新後的有效訂閱物件。

範例

恢復已取消的訂閱

javascript
async function recoverSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.recover(subscriptionId);
    console.log('訂閱已恢復：', subscription);
    return subscription;
  } catch (error) {
    console.error('恢復訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
recoverSubscription('sub_xxxxxxxxxxxxxx');

暫停訂閱

暫停訂閱的付款收取。

參數

名稱類型描述
idstring要暫停的訂閱 ID。
bodyobject包含暫停詳細資訊的物件。

Body 物件屬性

名稱類型描述
behaviorstring暫停期間建立的發票行為。可以是 'keep_as_draft'、'mark_uncollectible' 或 'void'。
resumes_atnumber訂閱應自動恢復的 Unix 時間戳。

傳回值

傳回具有 paused 狀態的更新後訂閱物件。

範例

暫停訂閱

javascript
async function pauseSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.pause(subscriptionId, {
      behavior: 'keep_as_draft'
    });
    console.log('訂閱已暫停：', subscription);
    return subscription;
  } catch (error) {
    console.error('暫停訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
pauseSubscription('sub_xxxxxxxxxxxxxx');

繼續訂閱

繼續已暫停訂閱的付款收取。

參數

名稱類型描述
idstring要繼續的訂閱 ID。

傳回值

傳回更新後的有效訂閱物件。

範例

繼續訂閱

javascript
async function resumeSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.resume(subscriptionId);
    console.log('訂閱已繼續：', subscription);
    return subscription;
  } catch (error) {
    console.error('繼續訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
resumeSubscription('sub_xxxxxxxxxxxxxx');

刪除訂閱

永久刪除訂閱及其所有相關資料。此操作不可逆，且只應在非生產環境中使用。

參數

名稱類型描述
idstring要刪除的訂閱 ID。

傳回值

傳回已刪除的訂閱物件。

範例

刪除訂閱

javascript
async function deleteSubscription(subscriptionId) {
  try {
    const subscription = await payment.subscriptions.del(subscriptionId);
    console.log('訂閱已刪除：', subscription);
    return subscription;
  } catch (error) {
    console.error('刪除訂閱時發生錯誤：', error.message);
  }
}

// 範例用法：
deleteSubscription('sub_xxxxxxxxxxxxxx');

列出逾期發票

擷取特定訂閱的逾期（無法收取）發票列表，以及應付金額的摘要。

參數

名稱類型描述
idstring訂閱的 ID。

傳回值

傳回一個包含訂閱、逾期發票列表以及每種貨幣所欠總金額摘要的物件。

名稱類型描述
subscriptionTSubscription訂閱物件。
invoicesTInvoice[]逾期發票物件的陣列。
summaryobject一個摘要每種貨幣總逾期金額的物件。

範例

擷取逾期發票

javascript
async function getOverdueInvoices(subscriptionId) {
  try {
    const result = await payment.subscriptions.overdueInvoices(subscriptionId);
    console.log('逾期發票摘要：', result.summary);
    console.log('發票：', result.invoices);
    return result;
  } catch (error) {
    console.error('擷取逾期發票時發生錯誤：', error.message);
  }
}

// 範例用法：
getOverdueInvoices('sub_xxxxxxxxxxxxxx');

返還質押

啟動返還與已取消且使用 ArcBlock 付款方式的訂閱相關的質押資金的流程。

參數

名稱類型描述
idstring已取消訂閱的 ID。

傳回值

傳回一個表示成功排程返還質押工作的物件。

名稱類型描述
successboolean如果成功排程返還質押工作，則為 true。
subscriptionIdstring正在返還質押的訂閱 ID。

範例

返還質押

javascript
async function returnSubscriptionStake(subscriptionId) {
  try {
    const result = await payment.subscriptions.returnStake(subscriptionId);
    console.log('已啟動返還質押：', result);
    return result;
  } catch (error) {
    console.error('返還質押時發生錯誤：', error.message);
  }
}

// 範例用法：
returnSubscriptionStake('sub_xxxxxxxxxxxxxx');