优惠券
优惠券是为您的产品和服务提供折扣的强大工具。优惠券对象包含有关特定折扣的信息，例如百分比折扣或固定金额折扣。要使优惠券可兑换，您必须将其与一个或多个促销代码关联。此 API 允许您创建、管理和跟踪优惠券的使用情况。
创建优惠券#
创建一个新的优惠券。您可以选择在同一次请求中创建一个或多个促销代码与此优惠券关联。
参数#
优惠券的名称，旨在向客户显示。例如 SUMMER25。
一个介于 1 和 100 之间的正整数，表示将要折扣的订阅发票小计的百分比。percent_off 或 amount_off 必须提供一个。
一个正小数，表示将应用于发票的折扣金额。percent_off 或 amount_off 必须提供一个。需要设置 currency_id。
amount_off 所用货币的 ID。如果设置了 amount_off，则此项为必填项。
指定折扣的有效期。可以是 once（一次）、repeating（重复）或 forever（永久）。
如果 duration 是 repeating，则为优惠券适用的月数。如果 duration 是 repeating，则此项为必填项。
一个正整数，指定优惠券可以兑换的最大次数。留空将允许优惠券无限次兑换。
Unix 时间戳，指定优惠券可以兑换的最后时间。在此时间之后，优惠券不能再应用于新客户。
一个哈希表，包含此优惠券适用的产品 ID。
当指定 amount_off 时，此哈希表可用于配置每种货币的优惠券金额。如果客户的货币与哈希表中的键匹配，则该键的值将用作折扣金额。
您可以附加到对象上的一组键值对。这对于以结构化格式存储有关对象的附加信息很有用。
要创建并附加到此优惠券的促销代码对象数组。详见下文。
promotion_codes 对象属性
面向客户的代码。如果留空，将生成一个随机代码。
促销代码的可选描述。
此特定促销代码可以兑换的最大次数。
Unix 时间戳，指定促销代码的到期时间。
返回#
返回一个包含新创建的 coupon 和 promotion_codes 数组的对象。
示例#
Create a Coupon
import payment from '@blocklet/payment-js';
async function createCoupon() {
try {
const result = await payment.coupons.create({
name: '20% Off First Month',
percent_off: 20,
duration: 'once',
max_redemptions: 100,
promotion_codes: [
{
code: 'NEWUSER20',
description: 'Discount for new users',
max_redemptions: 50,
expires_at: Math.floor(Date.now() / 1000) + 30 * 24 * 60 * 60, // 从现在起 30 天
},
],
});
console.log('优惠券已创建:', result.coupon);
console.log('促销代码:', result.promotion_codes);
} catch (error) {
console.error('创建优惠券时出错:', error);
}
}
See all 1 lines
示例响应#
{
"coupon": {
"id": "coupon_12345",
"name": "20% Off First Month",
"percent_off": 20,
"amount_off": null,
"currency_id": null,
"duration": "once",
"duration_in_months": null,
"max_redemptions": 100,
"times_redeemed": 0,
"valid": true,
"livemode": false,
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
},
"promotion_codes": [
{
"id": "promo_67890",
"coupon_id": "coupon_12345",
"code": "NEWUSER20",
"description": "Discount for new users",
"active": true,
"max_redemptions": 50,
"times_redeemed": 0,See all 5 lines
检索优惠券#
检索具有给定 ID 的优惠券。响应包括关联的促销代码以及优惠券适用的任何产品。
参数#
返回#
如果提供了有效的 ID，则返回一个优惠券对象。否则返回错误。
示例#
Retrieve a Coupon
import payment from '@blocklet/payment-js';
async function retrieveCoupon(couponId) {
try {
const coupon = await payment.coupons.retrieve(couponId);
console.log('检索到的优惠券:', coupon);
} catch (error) {
console.error('检索优惠券时出错:', error);
}
}
retrieveCoupon('coupon_12345');示例响应#
{
"id": "coupon_12345",
"name": "20% Off First Month",
"percent_off": 20,
"duration": "once",
"valid": true,
"promotion_codes": [
{
"id": "promo_67890",
"code": "NEWUSER20",
"active": true
}
],
"applied_products": []
}更新优惠券#
通过设置传入参数的值来更新指定的优惠券。任何未提供的参数将保持不变。
参数#
优惠券的名称。
优惠券的可选描述。
优惠券可以兑换的最大次数。
Unix 时间戳，指定优惠券可以兑換的最后时间。
优惠券当前是否有效。
更新每种货币的优惠券金额。
要在对象上更新的键值对集合。
返回#
返回更新后的优惠券对象。
示例#
Update a Coupon
import payment from '@blocklet/payment-js';
async function updateCoupon(couponId) {
try {
const updatedCoupon = await payment.coupons.update(couponId, {
name: 'Summer Sale 2024',
metadata: { campaign: 'summer-2024' },
});
console.log('优惠券已更新:', updatedCoupon);
} catch (error) {
console.error('更新优惠券时出错:', error);
}
}
updateCoupon('coupon_12345');示例响应#
{
"id": "coupon_12345",
"name": "Summer Sale 2024",
"percent_off": 20,
"duration": "once",
"valid": true,
"metadata": {
"campaign": "summer-2024"
}
}列出所有优惠券#
返回您的优惠券列表。
参数#
返回#
一个对象，包含一个 list 属性（内含优惠券数组）、一个 count 属性（内含优惠券总数）和一个 paging 对象。
示例#
List Coupons
import payment from '@blocklet/payment-js';
async function listCoupons() {
try {
const coupons = await payment.coupons.list({ valid: true, pageSize: 5 });
console.log('找到的优惠券:', coupons.list);
} catch (error) {
console.error('列出优惠券时出错:', error);
}
}
listCoupons();示例响应#
{
"count": 25,
"list": [
{
"id": "coupon_12345",
"name": "Summer Sale 2024",
"percent_off": 20,
"valid": true
},
{
"id": "coupon_67890",
"name": "10 USD Off",
"amount_off": "1000",
"valid": true
}
],
"paging": {
"page": 1,
"pageSize": 5
}
}删除优惠券#
您可以通过 API 删除优惠券。删除优惠券将阻止其应用于任何未来的订阅。但是，它不会从任何已经应用的订阅中移除。
参数#
返回#
返回已删除的优惠券对象。如果优惠券已被使用，则无法删除，并将抛出错误。
示例#
Delete a Coupon
import payment from '@blocklet/payment-js';
async function deleteCoupon(couponId) {
try {
const deletedCoupon = await payment.coupons.del(couponId);
console.log('优惠券已删除:', deletedCoupon.id);
} catch (error) {
console.error('删除优惠券时出错:', error);
}
}
deleteCoupon('coupon_abcde');示例响应#
{
"id": "coupon_abcde",
"name": "Temporary Discount",
"percent_off": 15,
"valid": false
}检查优惠券是否已使用#
检查优惠券是否至少被兑换过一次。
参数#
返回#
一个包含布尔值 used 属性的对象。
示例#
Check Coupon Usage
import payment from '@blocklet/payment-js';
async function checkCouponUsage(couponId) {
try {
const result = await payment.coupons.used(couponId);
console.log(`优惠券 ${couponId} 是否已使用？`, result.used);
} catch (error) {
console.error('检查优惠券使用情况时出错:', error);
}
}
checkCouponUsage('coupon_12345');示例响应#
{
"used": true
}获取优惠券兑换记录#
检索有关优惠券兑换的详细分析，包括哪些客户或订阅已使用它。
参数#
要检索的兑换数据类型。可以是 customer 或 subscription。
返回#
返回包含兑换详情的数据对象。
示例#
Get Coupon Redemptions
import payment from '@blocklet/payment-js';
async function getRedemptions(couponId) {
try {
const redemptions = await payment.coupons.redemptions(couponId, {
type: 'customer',
pageSize: 10,
});
console.log('总兑换次数:', redemptions.count);
console.log('兑换的客户:', redemptions.customers);
} catch (error) {
console.error('获取兑换记录时出错:', error);
}
}
getRedemptions('coupon_12345');示例响应#
{
"count": 1,
"subscriptions": [],
"customers": [
{
"id": "cus_abc123",
"did": "did:abt:z123...",
"email": "customer@example.com",
"name": "Test Customer",
"coupon_usage_stats": {
"coupon_12345": 1
}
}
],
"paging": {
"page": 1,
"pageSize": 10
}
}