信用额度授予

信用额度授予对象用于向您的客户发放信用额度，这些信用额度可用于抵扣未来的账单，尤其适用于基于用量或基于信用额度的计费模型。每次授予都会跟踪总金额、剩余余额、状态以及任何特定的适用性规则。

要更全面地了解如何实施完整的基于信用额度的系统，请参阅我们的基于信用额度的计费指南。

信用额度授予对象#

CreditGrant 对象包含向客户授予特定信用额度的所有详细信息。

信用额度授予对象

{
  "id": "crdg_1B2c3D4e5F6g7H8i9J0k1L2m",
  "object": "credit_grant",
  "amount": "5000",
  "currency_id": "curr_usd",
  "customer_id": "cus_a1b2c3d4e5f6g7h8",
  "name": "Promotional Onboarding Credit",
  "category": "promotional",
  "priority": 50,
  "status": "granted",
  "effective_at": 1672531200,
  "expires_at": 1704067199,
  "granted_at": 1672531200,
  "remaining_amount": "3500",
  "applicability_config": {
    "scope": {
      "price_type": "metered"
    }
  },
  "metadata": {
    "campaign_id": "promo_q1_2024"
  },
  "livemode": true,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-15T10:30:00.000Z",

See all 13 lines

创建信用额度授予#

向客户授予新的信用额度。如果指定的客户不存在，将根据提供的 customer_id (DID) 自动创建一个新客户。

创建信用额度授予

import payment from '@blocklet/payment-js';

async function createCreditGrant() {
  try {
    const creditGrant = await payment.creditGrants.create({
      amount: '100.00',
      currency_id: 'curr_usd', // 替换为有效的货币 ID
      customer_id: 'cus_a1b2c3d4e5f6g7h8', // 或用户 DID
      name: 'Initial sign-up bonus',
      category: 'promotional',
      priority: 50,
      expires_at: Math.floor(new Date('2024-12-31').getTime() / 1000),
      metadata: {
        source: 'marketing_campaign_fall_2024'
      }
    });
    console.log('Credit grant created:', creditGrant);
  } catch (error) {
    console.error('Error creating credit grant:', error.message);
  }
}

createCreditGrant();

参数

名称

类型

描述

amount

string

必需。 要授予的信用额度金额，以数字的字符串形式表示。

currency_id

string

必需。 本次授予所用货币的 ID。

customer_id

string

必需。 接收信用额度的客户的 ID 或 DID。

name

string

信用额度授予的可选名称，供内部参考。

category

'paid' | 'promotional'

必需。 授予的类别。paid 通常由客户购买，而 promotional 则是赠送的。

priority

number

可选。一个介于 0 和 100 之间的数字，用于确定应用顺序。数字越小越先应用。默认为 50。

effective_at

number

可选。一个 Unix 时间戳，表示授予何时生效。如果未提供，则立即生效。

expires_at

number

可选。一个 Unix 时间戳，表示授予何时过期。

applicability_config

object

可选。定义此信用额度可应用于何处的规则。详见下文。如果未设置，则默认为所有计量价格。

metadata

object

可选。可附加到对象上的一组键值对。用于存储附加信息。

applicability_config 对象属性

名称

类型

描述

scope

object

定义信用额度授予适用的价格范围。

scope 对象属性

名称

类型

描述

prices

string[]

价格 ID 数组。如果指定，信用额度授予将仅适用于这些价格。

price_type

string

可设置为 'metered'。如果指定，信用额度授予将适用于此类型的所有价格。

返回

如果调用成功，则返回一个 TCreditGrantExpanded 对象。

检索信用额度授予#

通过唯一标识符检索现有信用额度授予的详细信息。

检索信用额度授予

import payment from '@blocklet/payment-js';

async function getCreditGrant(grantId) {
  try {
    const creditGrant = await payment.creditGrants.retrieve(grantId);
    console.log('Retrieved credit grant:', creditGrant);
  } catch (error) {
    console.error(`Error retrieving credit grant ${grantId}:`, error.message);
  }
}

getCreditGrant('crdg_1B2c3D4e5F6g7H8i9J0k1L2m'); // 替换为有效的信用额度授予 ID

参数

名称

类型

描述

id

string

必需。 要检索的信用额度授予的唯一标识符。

返回

一个 TCreditGrantExpanded 对象，如果设置了 applicability_config.scope.prices，则该对象会额外包含一个 items 属性，其中包含一个扩展的价格对象数组。

更新信用额度授予#

通过设置或取消设置 metadata 属性来更新指定的信用额度授予。其他属性无法更新。

更新信用额度授予

import payment from '@blocklet/payment-js';

async function updateCreditGrantMetadata(grantId) {
  try {
    const result = await payment.creditGrants.update(grantId, {
      metadata: {
        source: 'marketing_campaign_fall_2024',
        updated_by: 'admin_user_xyz'
      }
    });
    console.log('Update successful:', result.success);
  } catch (error) {
    console.error(`Error updating credit grant ${grantId}:`, error.message);
  }
}

updateCreditGrantMetadata('crdg_1B2c3D4e5F6g7H8i9J0k1L2m'); // 替换为有效的信用额度授予 ID

参数

名称

类型

描述

id

string

必需。 要更新的信用额度授予的 ID。

metadata

object

一组存储在对象上的键值对。要移除某个键，请将其值设置为 null。

返回

一个包含布尔值 success 的对象。

响应

{
  "success": true
}

列出信用额度授予#

返回一个分页的信用额度授予列表。您可以根据各种参数筛选列表。

列出信用额度授予

import payment from '@blocklet/payment-js';

async function listCustomerCreditGrants() {
  try {
    const grants = await payment.creditGrants.list({
      customer_id: 'cus_a1b2c3d4e5f6g7h8', // 替换为有效的客户 ID
      status: 'granted,pending',
      pageSize: 10
    });
    console.log(`Found ${grants.count} grants.`);
    grants.list.forEach(grant => {
      console.log(`- ${grant.id} (${grant.status})`);
    });
  } catch (error) {
    console.error('Error listing credit grants:', error.message);
  }
}

listCustomerCreditGrants();

参数

名称

类型

描述

customer_id

string

可选。按特定客户 ID 或 DID 筛选授予。

currency_id

string

可选。按货币 ID 筛选授予。

status

string

可选。一个逗号分隔的状态字符串，用于筛选（例如 'granted,pending,depleted'）。

livemode

boolean

可选。按生产模式筛选。

q

string

可选。一个通用的搜索查询字符串。

page

number

可选。用于分页的页码。默认为 1。

pageSize

number

可选。每页的项目数。默认为 20。

返回

一个分页对象，其中包含一个 TCreditGrantExpanded 对象列表 list 和记录总数 count。

获取信用额度摘要#

检索客户有效信用额度余额的摘要，按货币分组。这对于显示客户可用的总信用额度非常有用。

获取信用额度摘要

import payment from '@blocklet/payment-js';

async function getCustomerCreditSummary(customerId) {
  try {
    const summary = await payment.creditGrants.summary({ customer_id: customerId });
    console.log('Customer Credit Summary:', summary);
  } catch (error) {
    console.error(`Error fetching credit summary for ${customerId}:`, error.message);
  }
}

getCustomerCreditSummary('cus_a1b2c3d4e5f6g7h8'); // 替换为有效的客户 ID

参数

名称

类型

描述

customer_id

string

必需。 您想要检索其信用额度摘要的客户的 ID 或 DID。

subscription_id

string

可选。如果提供，摘要将仅包含适用于此特定订阅中价格的信用额度。

返回

返回一个 CreditSummary 对象。这是一个映射表，其中每个键都是一个货币 ID。值是一个对象，包含该货币的总信用额度和剩余信用额度，以及有效授予的数量。

响应

{
  "curr_usd": {
    "paymentCurrency": {
      "id": "curr_usd",
      "name": "United States Dollar",
      "symbol": "$",
      "decimal": 2
    },
    "totalAmount": "15000",
    "remainingAmount": "8500",
    "grantCount": 2
  },
  "curr_eur": {
    "paymentCurrency": {
      "id": "curr_eur",
      "name": "Euro",
      "symbol": "€",
      "decimal": 2
    },
    "totalAmount": "2000",
    "remainingAmount": "2000",
    "grantCount": 1
  }
}

接下来，您可以通过查看信用额度交易 API 来了解信用额度消费是如何被记录的。

优惠券
信用交易