促銷代碼 | ArcBlock

促銷代碼是客戶在結帳時可以輸入以獲得折扣的特定、面向用戶的代碼。每個促銷代碼都連結到一個父級優惠券，該優惠券定義了實際的折扣（例如，八折、折價 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，則為必填項。
- addresses string[] — 合約地址列表。
- tags string[] — NFT 標籤列表。
- trusted_issuers string[] — 可信發行者 DID 列表。
- trusted_parents string[] — 可信父級收藏 ID 列表。
- min_balance number (default: 1) — 用戶必須持有的所需 NFT 的最低餘額。
vc_config object — 基於可驗證憑證驗證的設定。如果 verification_type 為 vc，則為必填項。
- roles string[] — VC 中所需角色的列表。
- trusted_issuers string[] — VC 的可信發行者 DID 列表。
customer_dids string[] — 允許使用此促銷代碼的客戶 DID 列表。如果 verification_type 為 user_restricted，則為必填項。
restrictions object — 定義促銷代碼適用的條件。
- currency_options object — 應用促銷代碼所需的特定貨幣最低金額。
  - {currency_code} object
    - minimum_amount number (required) — 指定貨幣的最低交易金額。
- first_time_transaction boolean — 如果為 true，則促銷代碼僅適用於客戶的首次交易。
metadata object — 一組用於儲存有關物件的附加資訊的鍵值對。

返回創建的促銷代碼物件。

Create a promotion code

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% off for the summer sale',
      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% off for the summer sale",
  "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": "Summer Sale",
    "percent_off": 25,
    // ... 其他優惠券詳細資訊
  }
}

檢索促銷代碼

檢索現有促銷代碼的詳細資訊。

參數

id string (required) — 要檢索的促銷代碼的唯一識別碼。

返回促銷代碼物件。

Retrieve a promotion code

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 — 一組用於儲存有關物件的附加資訊的鍵值對。

返回更新後的促銷代碼物件。

Update a promotion code

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

async function updatePromotionCode(promotionCodeId) {
  try {
    const updatedPromotionCode = await payment.promotionCodes.update(promotionCodeId, {
      description: 'Updated summer sale 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 — 按其有效狀態篩選促銷代碼。

一個分頁的促銷代碼物件列表。

List promotion codes

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。

Archive a promotion code

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) — 要刪除的促銷代碼的唯一識別碼。

返回已刪除的促銷代碼物件。

Delete a promotion code

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 屬性的物件。

Check if a promotion code is 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) — 面向用戶的代碼字串。

返回促銷代碼物件。

Retrieve a promotion code by its code string

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。

一個包含兌換資料的物件，包括客戶和訂閱列表。

List redemptions for a promotion code

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