优惠券 | ArcBlock

优惠券是为您的产品和服务提供折扣的强大工具。优惠券对象包含有关特定折扣的信息，例如百分比折扣或固定金额折扣。要使优惠券可兑换，您必须将其与一个或多个促销代码关联。此 API 允许您创建、管理和跟踪优惠券的使用情况。

创建优惠券

创建一个新的优惠券。您可以选择在同一次请求中创建一个或多个促销代码与此优惠券关联。

参数

name string (required) — 优惠券的名称，旨在向客户显示。例如 SUMMER25。
percent_off number — 一个介于 1 和 100 之间的正整数，表示将要折扣的订阅发票小计的百分比。percent_off 或 amount_off 必须提供一个。
amount_off string — 一个正小数，表示将应用于发票的折扣金额。percent_off 或 amount_off 必须提供一个。需要设置 currency_id。
currency_id string — amount_off 所用货币的 ID。如果设置了 amount_off，则此项为必填项。
duration string (required) — 指定折扣的有效期。可以是 once（一次）、repeating（重复）或 forever（永久）。
duration_in_months number — 如果 duration 是 repeating，则为优惠券适用的月数。如果 duration 是 repeating，则此项为必填项。
max_redemptions number — 一个正整数，指定优惠券可以兑换的最大次数。留空将允许优惠券无限次兑换。
redeem_by number — Unix 时间戳，指定优惠券可以兑换的最后时间。在此时间之后，优惠券不能再应用于新客户。
applies_to object — 一个哈希表，包含此优惠券适用的产品 ID。
- products string[] — 此优惠券将适用的产品 ID 数组。
currency_options object — 当指定 amount_off 时，此哈希表可用于配置每种货币的优惠券金额。如果客户的货币与哈希表中的键匹配，则该键的值将用作折扣金额。
metadata object — 您可以附加到对象上的一组键值对。这对于以结构化格式存储有关对象的附加信息很有用。
promotion_codes array — 要创建并附加到此优惠券的促销代码对象数组。详见下文。

promotion_codes 对象属性

code string — 面向客户的代码。如果留空，将生成一个随机代码。
description string — 促销代码的可选描述。
max_redemptions number — 此特定促销代码可以兑换的最大次数。
expires_at number — Unix 时间戳，指定促销代码的到期时间。

返回一个包含新创建的 coupon 和 promotion_codes 数组的对象。

**** object
- coupon object — 创建的优惠券对象。
- promotion_codes array — 创建的促销代码对象数组。

示例

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

createCoupon();

示例响应

{
  "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,
      "expires_at": 1699984800,
      "livemode": false
    }
  ]
}

检索优惠券

检索具有给定 ID 的优惠券。响应包括关联的促销代码以及优惠券适用的任何产品。

参数

id string (required) — 要检索的优惠券的 ID。

如果提供了有效的 ID，则返回一个优惠券对象。否则返回错误。

**** object — 检索到的优惠券对象，已展开相关的促销代码和适用的产品。

示例

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": []
}

更新优惠券

通过设置传入参数的值来更新指定的优惠券。任何未提供的参数将保持不变。

参数

id string (required) — 要更新的优惠券的 ID。
name string — 优惠券的名称。
description string — 优惠券的可选描述。
max_redemptions number — 优惠券可以兑换的最大次数。
redeem_by number — Unix 时间戳，指定优惠券可以兑換的最后时间。
valid boolean — 优惠券当前是否有效。
currency_options object — 更新每种货币的优惠券金额。
metadata object — 要在对象上更新的键值对集合。

返回更新后的优惠券对象。

**** object — 更新后的优惠券对象。

示例

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"
  }
}

列出所有优惠券

返回您的优惠券列表。

参数

valid boolean — 按有效性筛选优惠券。
name string — 按名称筛选优惠券。
page number (default: 1) — 要检索的页码。
pageSize number (default: 20) — 每页检索的项目数。

一个对象，包含一个 list 属性（内含优惠券数组）、一个 count 属性（内含优惠券总数）和一个 paging 对象。

**** object
- list array — 优惠券对象数组。
- count number — 与查询匹配的优惠券总数。
- paging object — 分页信息。
  - page number — 当前页码。
  - pageSize number — 每页项目数。

示例

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 删除优惠券。删除优惠券将阻止其应用于任何未来的订阅。但是，它不会从任何已经应用的订阅中移除。

参数

id string (required) — 要删除的优惠券的 ID。

返回已删除的优惠券对象。如果优惠券已被使用，则无法删除，并将抛出错误。

**** object — 已删除的优惠券对象。

示例

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
}

检查优惠券是否已使用

检查优惠券是否至少被兑换过一次。

参数

id string (required) — 要检查的优惠券的 ID。

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

used boolean — 如果优惠券已被兑换，则为 true，否则为 false。

示例

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
}

获取优惠券兑换记录

检索有关优惠券兑换的详细分析，包括哪些客户或订阅已使用它。

参数

id string (required) — 优惠券的 ID。
type string — 要检索的兑换数据类型。可以是 customer 或 subscription。
page number (default: 1) — 要检索的页码。
pageSize number (default: 20) — 每页检索的项目数。

返回包含兑换详情的数据对象。

**** object
- count number — 兑换总数。
- subscriptions array — 兑换了该优惠券的订阅列表（如果类型是 'subscription'）。
- customers array — 兑换了该优惠券的客户列表（如果类型是 'customer'）。
- paging object — 分页信息。

示例

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