優惠券 | 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
  }
}