订阅

订阅用于管理客户的定期付款计划。订阅 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);
  }
}

// 示例用法：
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

包含要更新字段的对象。详见下文。

数据对象属性

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

// 示例用法：
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

每页的项目数（默认为 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);
  }
}

// 示例用法：
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

每页的项目数（默认为 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);
  }
}

// 示例用法：
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);
  }
}

// 示例用法：
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);
  }
}

// 示例用法：
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);
  }
}

// 示例用法：
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);
  }
}

// 示例用法：
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);
  }
}

// 示例用法：
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);
  }
}

// 示例用法：
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);
  }
}

// 示例用法：
returnSubscriptionStake('sub_xxxxxxxxxxxxxx');
订阅项目
Webhook 端点