跳到主要内容

订阅

订阅用于管理客户的定期付款计划。订阅 API 允许您创建、检索、更新、取消和管理这些定期计费安排的生命周期。

要管理订阅中的单个项目，请参阅 订阅项目 API。

检索订阅

通过唯一标识符获取现有订阅的详细信息。

参数

NameTypeDescription
idstring要检索的订阅的 ID。

返回

如果提供了有效的 ID，则返回一个订阅对象。TSubscriptionExpanded 对象包含以下属性：

NameTypeDescription
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您可以附加到对象上的一组键值对。

示例

Retrieving a subscription

javascript
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);
  }
}

// 示例用法：
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": { /* ... customer details ... */ },
  "paymentCurrency": { /* ... currency details ... */ },
  "paymentMethod": { /* ... method details ... */ },
  "metadata": {}
}

更新订阅

通过设置传入参数的值来更新现有订阅。

参数

NameTypeDescription
idstring要更新的订阅的 ID。
dataobject包含要更新字段的对象。详见下文。

数据对象属性

NameTypeDescription
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 对象属性

NameTypeDescription
idstring要更新或删除的现有订阅项目的 ID。
price_idstring新订阅项目价格的 ID。
quantitynumber订阅项目的数量。
deletedboolean设置为 true 以删除此订阅项目。
clear_usageboolean对于计量计费，指示是否在删除时清除使用量。

返回

返回更新后的订阅对象。

示例

Updating a subscription's metadata

javascript
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);
  }
}

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

示例响应

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

列出订阅

返回订阅的分页列表。您可以根据各种条件筛选列表。

参数

NameTypeDescription
statusstring按状态筛选订阅（例如，'active'、'trialing'）。多个值用逗号分隔。
customer_idstring按特定客户 ID 筛选订阅。
customer_didstring按特定客户 DID 筛选订阅。
metadata.{key}string按自定义元数据字段筛选。
orderstring | string[]排序顺序（例如，'created_at:DESC'）。
activeFirstboolean如果为 true，则活动和试用中的订阅会排在最前面。
pagenumber分页的页码（默认为 1）。
pageSizenumber每页的项目数（默认为 20）。

返回

返回订阅对象的分页列表。

NameTypeDescription
listTSubscriptionExpanded[]当前页的订阅对象数组。
countnumber与查询匹配的订阅总数。
pagingobject包含分页详细信息（page, pageSize）的对象。

示例

Listing all active subscriptions

javascript
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);
  }
}

// 示例用法：
listActiveSubscriptions();

示例响应

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

搜索订阅

根据查询字符串搜索订阅。

参数

NameTypeDescription
querystring用于匹配订阅字段的搜索字符串。
pagenumber分页的页码（默认为 1）。
pageSizenumber每页的项目数（默认为 20）。

返回

返回与搜索查询匹配的订阅对象的分页列表。

示例

Searching for a subscription

javascript
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);
  }
}

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

取消订阅

取消客户的订阅。订阅可以立即取消，也可以在当前计费周期结束时取消。

参数

NameTypeDescription
idstring要取消的订阅的 ID。
bodyobject包含取消详细信息的对象。

Body 对象属性

NameTypeDescription
atstring取消时间。可以是 'now'、'current_period_end' 或 'custom'。默认为 'current_period_end'。
timenumber | string如果 at 是 'custom'，则此项为必需。一个未来的 Unix 时间戳，用于指定取消时间。
refundstring指定是否应退款。可以是 'none'、'proration' 或 'last'。
feedbackstring客户对取消的反馈。
commentstring关于取消的内部评论。
reasonstring取消原因（例如，'cancellation_requested'）。

返回

返回包含取消详情的更新后订阅对象。

示例

Canceling a subscription at period end

javascript
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);
  }
}

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

恢复订阅

重新激活已计划取消但尚未取消的订阅。

参数

NameTypeDescription
idstring要恢复的订阅的 ID。

返回

返回更新后的活动订阅对象。

示例

Recovering a canceled subscription

javascript
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);
  }
}

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

暂停订阅

暂停订阅的付款收款。

参数

NameTypeDescription
idstring要暂停的订阅的 ID。
bodyobject包含暂停详细信息的对象。

Body 对象属性

NameTypeDescription
behaviorstring暂停期间创建的发票的行为。可以是 'keep_as_draft'、'mark_uncollectible' 或 'void'。
resumes_atnumber订阅应自动恢复的 Unix 时间戳。

返回

返回状态为 paused 的更新后订阅对象。

示例

Pausing a subscription

javascript
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);
  }
}

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

恢复订阅

恢复已暂停订阅的付款收款。

参数

NameTypeDescription
idstring要恢复的订阅的 ID。

返回

返回更新后的活动订阅对象。

示例

Resuming a subscription

javascript
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);
  }
}

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

删除订阅

永久删除订阅及其所有相关数据。此操作不可逆，且仅应在非生产环境中使用。

参数

NameTypeDescription
idstring要删除的订阅的 ID。

返回

返回已删除的订阅对象。

示例

Deleting a subscription

javascript
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);
  }
}

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

列出逾期发票

检索特定订阅的逾期（无法收取）发票列表，以及应付金额的摘要。

参数

NameTypeDescription
idstring订阅的 ID。

返回

返回一个包含订阅、逾期发票列表以及每种货币总欠款摘要的对象。

NameTypeDescription
subscriptionTSubscription订阅对象。
invoicesTInvoice[]逾期发票对象数组。
summaryobject一个对象，总结了每种货币的总逾期金额。

示例

Fetching overdue invoices

javascript
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);
  }
}

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

返还质押

启动返还与已取消的、使用 ArcBlock 支付方式的订阅相关的质押资金的流程。

参数

NameTypeDescription
idstring已取消订阅的 ID。

返回

返回一个对象，指示安排返还质押任务是否成功。

NameTypeDescription
successboolean如果返还质押任务已成功调度，则为 true。
subscriptionIdstring正在返还质押的订阅的 ID。

示例

Returning a stake

javascript
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);
  }
}

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