信用额度授予
信用额度授予 (Credit Grants) 是表示授予客户信用额度的对象。这些信用额度可用于抵消未来发票的费用。通过此 API，您可以为客户创建、检索、更新、列出和汇总信用额度授予。
若需更高级的基于信用的系统实施指南，请参阅 信用计费指南。要查看信用额度使用历史，请参考 信用交易 API。
信用额度授予对象#
信用额度授予对象 (Credit Grant object) 包含授予客户的信用额度的全部详情，包括金额、状态和适用性等信息。
属性 | 类型 | 描述 |
|---|---|---|
| string | 信用额度授予的唯一标识符。 |
| string | 对象类型，始终为 |
| string | 信用额度授予的总额，以最小货币单位计。 |
| string | 剩余信用额度。 |
| string | 信用额度所用货币的 ID。 |
| string | 收到信用额度授予的客户 ID。 |
| string | 授予的类别。可以是 |
| string | 授予的当前状态。可以是 |
| string | 信用额度授予的可选内部名称。 |
| number | 一个介于 1 和 99999 之间的正整数，用于决定信用额度的应用顺序。数值越小，优先级越高。 |
| number | Unix 时间戳，表示授予生效的时间。 |
| number | Unix 时间戳，表示授予到期的时间。 |
| object | 用于指定此信用额度授予适用范围的规则。 |
| boolean | 如果对象存在于生产模式，则为 |
| object | 可附加到对象上的一组键值对。 |
创建信用额度授予#
向客户授予一笔新的信用额度。
参数
名称 | 类型 | 描述 |
|---|---|---|
| string | 必需。 信用额度授予的金额，以最小货币单位指定。 |
| string | 必需。 授予所用的三字母 ISO 货币代码（或自定义货币 ID）。 |
| string | 必需。 接收信用额度的客户 ID。 |
| 'paid' | 'promotional' | 必需。 指定信用额度是来自付费来源还是促销活动。 |
| string | 此信用额度授予的可选内部名称。 |
| number | 一个正整数（1-99999），表示应用优先级。数值越小，越先应用。 |
| number | 一个 Unix 时间戳，表示信用额度授予生效的时间。如果未提供，则立即生效。 |
| number | 一个 Unix 时间戳，表示信用额度授予到期的时间。 |
| object | 一个定义信用额度适用范围的对象。包含一个 |
| object | 用于存储附加信息的一组键值对。 |
示例
async function createCreditGrant() {
try {
const creditGrant = await payment.creditGrants.create({
customer_id: 'cust_xxxxxxxxxxxxxx',
amount: '5000',
currency_id: 'usd',
category: 'promotional',
name: 'New User Welcome Bonus',
expires_at: Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60) // 从现在起 30 天
});
console.log('信用额度授予已创建：', creditGrant);
} catch (error) {
console.error('创建信用额度授予时出错：', error.message);
}
}
createCreditGrant();响应示例
{
"id": "cgrant_1A2b3C4d5E6f7G8h",
"object": "credit_grant",
"amount": "5000",
"currency_id": "usd",
"applicability_config": null,
"category": "promotional",
"customer_id": "cust_xxxxxxxxxxxxxx",
"effective_at": 1672531200,
"expires_at": 1675123200,
"livemode": false,
"metadata": {},
"name": "New User Welcome Bonus",
"priority": 50000,
"status": "granted",
"remaining_amount": "5000",
"created_via": "api",
"created_at": "2023-01-01T00:00:00.000Z",
"updated_at": "2023-01-01T00:00:00.000Z"
}检索信用额度授予#
根据 ID 获取特定信用额度授予的详情。
参数
名称 | 类型 | 描述 |
|---|---|---|
| string | 必需。 要检索的信用额度授予的唯一标识符。 |
示例
async function retrieveCreditGrant(grantId) {
try {
const creditGrant = await payment.creditGrants.retrieve(grantId);
console.log('已检索到的信用额度授予：', creditGrant);
} catch (error) {
console.error('检索信用额度授予时出错：', error.message);
}
}
retrieveCreditGrant('cgrant_1A2b3C4d5E6f7G8h');响应示例
{
"id": "cgrant_1A2b3C4d5E6f7G8h",
"object": "credit_grant",
"amount": "5000",
"currency_id": "usd",
"category": "promotional",
"customer_id": "cust_xxxxxxxxxxxxxx",
"status": "granted",
"remaining_amount": "5000",
// ... 其他属性
}更新信用额度授予#
通过设置 metadata 参数来更新指定的信用额度授予。信用额度授予的其他属性无法更新。
参数
名称 | 类型 | 描述 |
|---|---|---|
| string | 必需。 要更新的信用额度授予的标识符。 |
| object | 要随信用额度授予一起存储的一组键值对。 |
示例
async function updateCreditGrant(grantId) {
try {
const result = await payment.creditGrants.update(grantId, {
metadata: {
internal_ref: 'promo-campaign-fall2023'
}
});
console.log('更新成功：', result.success);
} catch (error) {
console.error('更新信用额度授予时出错：', error.message);
}
}
updateCreditGrant('cgrant_1A2b3C4d5E6f7G8h');响应示例
{
"success": true
}列出所有信用额度授予#
返回一个分页的信用额度授予列表。您可以根据各种参数筛选列表。
参数
名称 | 类型 | 描述 |
|---|---|---|
| string | 将列表筛选为特定客户的授予。 |
| string | 按货币筛选列表。 |
| string | 按状态筛选列表（例如 |
| boolean | 按生产模式或测试模式筛选。 |
| string | 一个跨多个字段进行搜索的查询字符串。 |
| number | 用于分页的页码。 |
| number | 每页的项目数。默认为 |
| string | string[] | 结果的排序顺序。 |
示例
async function listCustomerCredits() {
try {
const creditGrants = await payment.creditGrants.list({
customer_id: 'cust_xxxxxxxxxxxxxx',
status: 'granted',
pageSize: 5
});
console.log(`找到 ${creditGrants.count} 个已授予客户的信用额度。`);
creditGrants.list.forEach(grant => {
console.log(`- 授予 ${grant.id}：${grant.remaining_amount} ${grant.currency_id}`);
});
} catch (error) {
console.error('列出信用额度授予时出错：', error.message);
}
}
listCustomerCredits();响应示例
{
"count": 1,
"list": [
{
"id": "cgrant_1A2b3C4d5E6f7G8h",
"object": "credit_grant",
"amount": "5000",
"currency_id": "usd",
"category": "promotional",
"customer_id": "cust_xxxxxxxxxxxxxx",
"status": "granted",
"remaining_amount": "5000",
// ... 其他属性
}
]
}检索信用额度摘要#
提供按货币分组的客户信用余额摘要。
参数
名称 | 类型 | 描述 |
|---|---|---|
| string | 必需。 要检索其摘要的客户 ID。 |
| string | 一个可选的订阅 ID，为信用额度摘要提供上下文，这可能会影响返回哪些适用的信用额度。 |
示例
async function getCreditSummary(customerId) {
try {
const summary = await payment.creditGrants.summary({ customer_id: customerId });
console.log('客户信用额度摘要：', summary);
} catch (error) {
console.error('检索信用额度摘要时出错：', error.message);
}
}
getCreditSummary('cust_xxxxxxxxxxxxxx');响应示例
{
"customer_id": "cust_xxxxxxxxxxxxxx",
"total_balance": {
"usd": {
"currency_id": "usd",
"total_amount": "15000",
"available_amount": "7500",
"pending_amount": "0",
"currency": {
"id": "usd",
"symbol": "$",
"decimal": 2
}
},
"eur": {
"currency_id": "eur",
"total_amount": "10000",
"available_amount": "10000",
"pending_amount": "0",
"currency": {
"id": "eur",
"symbol": "€",
"decimal": 2
}
}
}
}本节详细介绍了如何通过编程方式管理信用额度授予。授予信用额度后，您需要跟踪其如何应用于发票。请继续阅读 信用交易 API 以了解更多信息。