促销代码

促销代码是客户在结账时可以输入的特定、面向用户的代码，用于获得折扣。每个促销代码都链接到一个父级 优惠券，该优惠券定义了实际的折扣（例如，八折优惠、10 美元折扣）。这种两级结构允许您创建多个指向同一基础折扣的唯一代码，从而可以轻松跟踪不同的营销活动或分发渠道。

此 API 允许您创建、管理和跟踪促销代码的使用情况。

促销代码对象#

促销代码对象包含有关特定代码的所有信息，包括其父级优惠券、使用限制和约束条件。

id
string
促销代码的唯一标识符。
coupon_id
string
此促销代码关联的优惠券的 ID。
code
string
客户输入的用于应用折扣的面向用户的代码。
description
string
促销代码的内部描述。
active
boolean
促销代码当前是否有效且可以使用。
max_redemptions
number
此促销代码可兑换的最大次数。
times_redeemed
number
此促销代码已被兑换的次数。
expires_at
number
一个 Unix 时间戳，表示促销代码的过期时间。
verification_type
string
用于验证折扣资格的方法。可以是 'code'、'nft'、'vc' 或 'user_restricted'。
nft_config
object
用于基于 NFT 验证的配置。
vc_config
object
用于基于可验证凭证验证的配置。
customer_dids
string[]
有资格使用此代码的客户 DID 数组。
restrictions
object
适用于此促销代码的一组限制。
metadata
object
可以附加到对象的一组键值对。
coupon
object
与此促销代码关联的扩展优惠券对象。
livemode
boolean
指示对象是存在于生产模式还是测试模式。
created_at
string
对象创建时的时间戳。
updated_at
string
对象最后更新时的时间戳。

创建促销代码#

创建一个新的促销代码对象。

参数#

coupon_id
string
required

要与此促销代码关联的优惠券的 ID。

code
string

面向用户的代码。如果未提供，将生成一个随机代码。最多 16 个字符。

description
string

代码的可选内部描述。最多 250 个字符。

active
boolean
default:true

促销代码是否有效。默认为 true。

max_redemptions
number

促销代码可兑换的最大次数。

expires_at
number

一个 Unix 时间戳，在此时间之后促销代码不再有效。

verification_type
string
default:code

指定验证方法。可以是 code、nft、vc 或 user_restricted。

nft_config
object

用于基于 NFT 验证的配置。如果 verification_type 是 nft，则为必需。

5 subfields
vc_config
object

用于基于可验证凭证验证的配置。如果 verification_type 是 vc，则为必需。

2 subfields
customer_dids
string[]

允许使用此促销代码的客户 DID 列表。如果 verification_type 是 user_restricted，则为必需。

restrictions
object

定义应用促销代码的条件。

2 subfields
metadata
object

用于存储有关对象的附加信息的一组键值对。

返回值#

返回创建的促销代码对象。

创建促销代码

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

async function createPromotionCode() {
  try {
    const promotionCode = await payment.promotionCodes.create({
      coupon_id: 'coupon_xxxxxxxxxxxxxx', // 替换为有效的优惠券 ID
      code: 'SUMMER25',
      description: '夏季促销 25% 折扣',
      max_redemptions: 100,
      expires_at: Math.floor(new Date('2024-09-01').getTime() / 1000),
      active: true,
    });
    console.log('促销代码已创建：', promotionCode);
  } catch (error) {
    console.error('创建促销代码时出错：', error.message);
  }
}

createPromotionCode();

响应示例#

{
  "id": "pc_xxxxxxxxxxxxxx",
  "coupon_id": "coupon_xxxxxxxxxxxxxx",
  "code": "SUMMER25",
  "description": "夏季促销 25% 折扣",
  "active": true,
  "max_redemptions": 100,
  "times_redeemed": 0,
  "expires_at": 1725148800,
  "verification_type": "code",
  "nft_config": null,
  "vc_config": null,
  "customer_dids": null,
  "restrictions": {},
  "metadata": {},
  "livemode": false,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "coupon": {
    "id": "coupon_xxxxxxxxxxxxxx",
    "name": "夏季促销",
    "percent_off": 25,
    // ... 其他优惠券详情
  }
}

检索促销代码#

检索现有促销代码的详细信息。

参数#

id
string
required

要检索的促销代码的唯一标识符。

返回值#

返回促销代码对象。

检索促销代码

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

async function getPromotionCode(promotionCodeId) {
  try {
    const promotionCode = await payment.promotionCodes.retrieve(promotionCodeId);
    console.log('已检索的促销代码：', promotionCode);
  } catch (error) {
    console.error('检索促销代码时出错：', error.message);
  }
}

getPromotionCode('pc_xxxxxxxxxxxxxx'); // 替换为有效的促销代码 ID

更新促销代码#

通过设置传入参数的值来更新指定的促销代码。任何未提供的参数将保持不变。请注意，一旦促销代码被使用，只有其 metadata 可以被更新。

参数#

id
string
required

要更新的促销代码的唯一标识符。

description
string

代码的可选内部描述。最多 250 个字符。

active
boolean

促销代码是否有效。

max_redemptions
number

促销代码可兑换的最大次数。

expires_at
number

一个 Unix 时间戳，在此时间之后促销代码不再有效。

restrictions
object

定义应用促销代码的条件。

metadata
object

用于存储有关对象的附加信息的一组键值对。

返回值#

返回更新后的促销代码对象。

更新促销代码

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

async function updatePromotionCode(promotionCodeId) {
  try {
    const updatedPromotionCode = await payment.promotionCodes.update(promotionCodeId, {
      description: '更新的夏季促销描述',
      metadata: { campaign_id: 'summer-2024' },
    });
    console.log('促销代码已更新：', updatedPromotionCode);
  } catch (error) {
    console.error('更新促销代码时出错：', error.message);
  }
}

updatePromotionCode('pc_xxxxxxxxxxxxxx'); // 替换为有效的促销代码 ID

列出促销代码#

返回您的促销代码列表。

参数#

page
number
default:1

用于分页的页码。

pageSize
number
default:20

每页的项目数。

coupon_id
string

按关联的优惠券 ID 筛选促销代码。

active
boolean

按其活动状态筛选促销代码。

返回值#

一个分页的促销代码对象列表。

列出促销代码

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

async function listPromotionCodes() {
  try {
    const promotionCodes = await payment.promotionCodes.list({
      active: true,
      pageSize: 5,
    });
    console.log('有效的促销代码：', promotionCodes.list);
  } catch (error) {
    console.error('列出促销代码时出错：', error.message);
  }
}

listPromotionCodes();

响应示例#

{
  "count": 50,
  "list": [
    {
      "id": "pc_xxxxxxxxxxxxxx",
      "code": "SUMMER25",
      // ... 其他促销代码详情
    }
    // ... 更多促销代码
  ],
  "paging": {
    "page": 1,
    "pageSize": 5
  }
}

归档促销代码#

停用一个促销代码，使其不再可兑换。此操作不可逆。

参数#

id
string
required

要归档的促销代码的唯一标识符。

返回值#

返回已归档的促销代码对象，其中 active 设置为 false。

归档促销代码

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

async function archivePromotionCode(promotionCodeId) {
  try {
    const archivedCode = await payment.promotionCodes.archive(promotionCodeId);
    console.log('促销代码已归档：', archivedCode);
  } catch (error) {
    console.error('归档促销代码时出错：', error.message);
  }
}

archivePromotionCode('pc_xxxxxxxxxxxxxx'); // 替换为有效的促销代码 ID

删除促销代码#

删除一个促销代码。此操作仅在促销代码未被兑换时才可能。如果已被使用，它将被锁定且无法删除；您应改为归档它。

参数#

id
string
required

要删除的促销代码的唯一标识符。

返回值#

返回已删除的促销代码对象。

删除促销代码

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

async function deletePromotionCode(promotionCodeId) {
  try {
    const deletedCode = await payment.promotionCodes.del(promotionCodeId);
    console.log('促销代码已删除：', deletedCode);
  } catch (error) {
    console.error('删除促销代码时出错：', error.message);
  }
}

deletePromotionCode('pc_xxxxxxxxxxxxxx'); // 替换为未使用的促销代码 ID

检查是否已使用#

检查促销代码是否至少被兑换过一次。

参数#

id
string
required

要检查的促销代码的唯一标识符。

返回值#

一个包含布尔值 used 属性的对象。

检查促销代码是否已使用

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

async function checkUsage(promotionCodeId) {
  try {
    const result = await payment.promotionCodes.used(promotionCodeId);
    console.log(`促销代码是否已使用？${result.used}`);
  } catch (error) {
    console.error('检查促销代码使用情况时出错：', error.message);
  }
}

checkUsage('pc_xxxxxxxxxxxxxx'); // 替换为有效的促销代码 ID

响应示例#

{
  "used": true
}

按代码检索#

通过其面向用户的代码字符串检索促销代码的详细信息。

参数#

code
string
required

面向用户的代码字符串。

返回值#

返回促销代码对象。

按代码字符串检索促销代码

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

async function getByCode(code) {
  try {
    const promotionCode = await payment.promotionCodes.byCode(code);
    console.log('找到的促销代码：', promotionCode);
  } catch (error) {
    console.error('按代码检索促销代码时出错：', error.message);
  }
}

getByCode('SUMMER25');

列出兑换记录#

检索已兑换特定促销代码的客户和订阅列表。

参数#

id
string
required

促销代码的唯一标识符。

page
number
default:1

用于分页的页码。

pageSize
number
default:20

每页的项目数。

type
'customer' | 'subscription'

要列出的兑换类型。可以是 customer 或 subscription。

返回值#

一个包含兑换数据的对象，包括客户和订阅列表。

列出促销代码的兑换记录

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

async function listRedemptions(promotionCodeId) {
  try {
    const redemptions = await payment.promotionCodes.redemptions({ 
      id: promotionCodeId, 
      type: 'customer', 
      pageSize: 10 
    });
    console.log('兑换记录：', redemptions);
  } catch (error) {
    console.error('列出兑换记录时出错：', error.message);
  }
}

listRedemptions('pc_xxxxxxxxxxxxxx'); // 替换为有效的促销代码 ID

响应示例#

{
  "count": 5,
  "subscriptions": [],
  "customers": [
    {
      "id": "cus_yyyyyyyyyyyyyy",
      "did": "did:abt:z...",
      // ... 其他客户详情
    }
    // ... 更多客户
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}
产品
退款