折扣 | ArcBlock

PaymentKit 提供了一套使用優惠券 (Coupons) 和促銷代碼 (Promotion Codes) 的彈性折扣系統。這讓您可以為顧客提供各種類型的折扣，例如百分比折扣、固定金額折扣和限時優惠。

優惠券 (Coupons)：定義核心折扣規則，例如折扣百分比或金額、持續時間（例如：一次性、永久、重複）以及最大總兌換次數。
促銷代碼 (Promotion Codes)：這些是面向顧客並與優惠券連結的代碼。它們可以有自己的一套規則，例如個人兌換限制、到期日期和限制（例如：僅限首次消費的顧客）。

您可以將優惠券視為折扣的範本，而促銷代碼則是顧客可以使用的該折扣的具體實例。

有關所有可用 API 操作的詳細說明，請參閱 Coupons API 參考和 Promotion Codes API 參考。

折扣如何運作

下圖說明了優惠券、促銷代碼及其在交易過程中的應用關係。

Discounts

建立優惠券

一個 Coupon 物件包含折扣的相關資訊，例如是百分比折扣還是固定金額折扣。您可以建立優惠券，然後將促銷代碼附加到它們上面。

建立帶有促銷代碼的優惠券

您可以在單一 API 呼叫中建立一張優惠券和一個或多個相關的促銷代碼。這對於快速設定新的行銷活動很有用。

Create Coupon with Promo Code

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

async function createDiscountCampaign() {
  try {
    const result = await payment.coupons.create({
      name: '新用戶折扣',
      percent_off: 20,
      duration: 'once',
      max_redemptions: 1000, // 優惠券本身的最大兌換次數
      promotion_codes: [
        {
          code: 'WELCOME20',
          description: '給新用戶的歡迎折扣',
          max_redemptions: 100, // 此特定代碼的最大兌換次數
          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.message);
  }
}

createDiscountCampaign();

Parameters

name string (required) — 優惠券的名稱，供內部顯示使用。
percent_off number — 從小計中扣除的百分比 (0-100)。如果設定了 amount_off，則不得提供此項。
amount_off string — 從小計中扣除的固定金額。如果設定了 percent_off，則不得提供此項。
currency_id string — 如果設定了 amount_off，則為必填項。用於固定金額折扣的貨幣 ID。
duration string (required) — 描述折扣的適用時長。可以是 once (一次性)、forever (永久) 或 repeating (重複)。
duration_in_months number — 如果 duration 是 repeating，則為優惠券適用的月數。
max_redemptions number — 該優惠券可被兌換的最大次數。
redeem_by number — 指定優惠券到期日的 Unix 時間戳。
promotion_codes array — 一個包含要建立並附加到此優惠券的促銷代碼物件的陣列。
- code string — 面向顧客的代碼。如果省略，將會產生一個隨機代碼。
- max_redemptions number — 此特定促銷代碼可使用的最大次數。
- expires_at number — 此促銷代碼到期的 Unix 時間戳。
- description string — 促銷代碼的選填描述。
metadata object — 一組用於儲存額外資訊的鍵值對。

建立促銷代碼

雖然您可以在建立優惠券的同時建立促銷代碼，但也可以單獨建立它們並附加到現有的優惠券上。這對於為單一行銷活動產生多個獨特代碼很有用。

建立獨立的促銷代碼

Create Promotion Code

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

async function createPromoCode(couponId) {
  try {
    const promotionCode = await payment.promotionCodes.create({
      coupon_id: couponId, // 現有優惠券的 ID
      code: 'SAVE15NOW',
      description: '下次購買享八五折優惠',
      max_redemptions: 500,
      restrictions: {
        first_time_transaction: true, // 僅限新顧客
      }
    });
    console.log('促銷代碼已建立：', promotionCode);
  } catch (error) {
    console.error('建立促銷代碼時發生錯誤：', error.message);
  }
}

createPromoCode('coupon_xxx'); // 請替換為您實際的優惠券 ID

Parameters

coupon_id string (required) — 此促銷代碼應附加到的優惠券 ID。
code string — 面向顧客的代碼。如果省略，將會產生一個隨機代碼。
active boolean (default: true) — 此促銷代碼目前是否有效。
max_redemptions number — 此特定促銷代碼可使用的最大次數。
expires_at number — 此促銷代碼到期的 Unix 時間戳。
restrictions object — 對此促銷代碼應用限制。
- first_time_transaction boolean — 若為 true，則此促銷代碼只能由沒有任何先前付款紀錄的顧客兌換。
- minimum_amount number — 使用此代碼所需的最低交易金額。
- minimum_amount_currency string — 最低金額的貨幣。
metadata object — 一組用於儲存額外資訊的鍵值對。

在結帳時套用折扣

要讓顧客在結帳頁面輸入促銷代碼，您必須在建立結帳工作階段 (Checkout Session) 或付款連結 (Payment Link) 時明確啟用此選項。

在結帳工作階段中啟用

在建立結帳工作階段時，將 allow_promotion_codes 參數設定為 true。這會在付款頁面上新增一個欄位，供顧客輸入他們的代碼。

Enable Promotion Codes

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

async function createCheckoutWithDiscounts() {
  try {
    const session = await payment.checkout.sessions.create({
      success_url: 'https://example.com/success',
      cancel_url: 'https://example.com/cancel',
      mode: 'payment',
      line_items: [
        { price_id: 'price_xxx', quantity: 1 }
      ],
      allow_promotion_codes: true // 這會啟用促銷代碼欄位
    });
    console.log('已建立啟用促銷代碼的結帳工作階段：', session.url);
  } catch (error) {
    console.error('建立結帳工作階段時發生錯誤：', error.message);
  }
}

createCheckoutWithDiscounts();

在付款連結中啟用

同樣的邏輯也適用於可重複使用的付款連結。將 allow_promotion_codes 設定為 true 可確保任何使用該連結的人都能套用有效的促銷代碼。

Enable on Payment Link

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

async function createPaymentLinkWithDiscounts() {
  try {
    const paymentLink = await payment.paymentLinks.create({
      line_items: [{
        price_id: 'price_xxx',
        quantity: 1,
      }],
      allow_promotion_codes: true,
    });
    console.log('已建立啟用促銷代碼的付款連結：', paymentLink.url);
  } catch (error) {
    console.error('建立付款連結時發生錯誤：', error.message);
  }
}

createPaymentLinkWithDiscounts();

管理折扣

The SDK 提供了多種方法來管理和追蹤您的折扣。

透過代碼擷取促銷代碼

您可以使用面向顧客的代碼字串直接取得促銷代碼的詳細資訊。

Get Promotion Code by Code

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

async function getPromoDetails(code) {
  try {
    const promoByCode = await payment.promotionCodes.byCode(code);
    console.log('找到促銷代碼：', promoByCode);
    // 您現在可以存取相關的優惠券詳細資訊
    console.log('折扣：', promoByCode.coupon);
  } catch (error) {
    console.error(`找不到促銷代碼 '${code}' 或發生錯誤：`, error.message);
  }
}

getPromoDetails('WELCOME20');

檢查優惠券使用情況

判斷優惠券是否至少被兌換過一次。這對於決定優惠券的規則是否仍可編輯很有用。

Check Coupon Usage

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

async function checkCouponUsage(couponId) {
  try {
    const { used } = await payment.coupons.used(couponId);
    if (used) {
      console.log(`優惠券 ${couponId} 已被使用，其規則現已鎖定。`);
    } else {
      console.log(`優惠券 ${couponId} 尚未使用。`);
    }
  } catch (error) {
    console.error('檢查優惠券使用情況時發生錯誤：', error.message);
  }
}

checkCouponUsage('coupon_xxx'); // 請替換為有效的優惠券 ID

列出兌換紀錄

您可以擷取已兌換特定優惠券或促銷代碼的顧客或訂閱的分頁列表。

List Coupon Redemptions

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

async function getCouponRedemptions(couponId) {
  try {
    const redemptions = await payment.coupons.redemptions(couponId, {
      type: 'customer', // 或 'subscription'
      page: 1,
      pageSize: 10
    });
    console.log(`找到 ${redemptions.count} 筆優惠券 ${couponId} 的顧客兌換紀錄：`);
    redemptions.customers.forEach(customer => {
      console.log(`- 顧客 ID：${customer.id}`);
    });
  } catch (error) {
    console.error('取得兌換紀錄時發生錯誤：', error.message);
  }
}

getCouponRedemptions('coupon_xxx'); // 請替換為有效的優惠券 ID