Recur Docs

Products API

View as Markdown View this page as plain textOpen in ChatGPT Ask ChatGPT about this pageOpen in Claude Ask Claude about this page

產品（Product）代表您在 Recur 上販售的項目，包含訂閱方案、一次性商品、儲值點數與打賞。Products API 為唯讀 API，用於在您的應用程式中取得產品資訊（例如渲染定價頁面）；建立與編輯產品請透過 Recur 後台。

所有 Products API 端點都需要 Secret Key 認證，僅限後端使用。

產品物件

{
  "object": "product",
  "id": "prod_xxxxx",
  "name": "專業方案",
  "slug": "pro-plan",
  "description": "適合成長中團隊的完整功能方案",
  "type": "SUBSCRIPTION",
  "interval": "month",
  "interval_count": 1,
  "price": 299,
  "currency": "TWD",
  "trial_days": 14,
  "display_order": 1,
  "metadata": null,
  "active": true,
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-15T10:00:00.000Z",
  "livemode": false
}

欄位說明

欄位類型說明
objectstring固定為 "product"
idstring產品 ID
namestring產品名稱
slugstring | nullURL 友善的產品識別碼
descriptionstring | null產品描述
typestring產品類型：SUBSCRIPTION、ONE_TIME、CREDITS、DONATION
intervalstring | null計費週期單位：day、week、month、year（非訂閱產品為 null）
interval_countnumber計費週期數量（例如 3 + month = 每季）
pricenumber價格（整數，例如 299 代表 NT$299）
currencystring幣別（目前為 TWD）
trial_daysnumber | null試用天數（無試用期為 null）
display_ordernumber | null顯示排序
metadataobject | null自訂 metadata
activeboolean是否啟用（false 為已封存）
created_atstring建立時間（ISO 8601）
updated_atstring最後更新時間（ISO 8601，僅單筆查詢回傳）
livemodeboolean是否為正式環境

列出產品

取得組織的產品列表，依建立時間由新到舊排序。預設只回傳啟用中的產品。

端點

GET /products

請求參數

參數類型說明
statusstring傳入 archived 時改為列出已封存的產品；省略則列出啟用中的產品
typestring依產品類型篩選：SUBSCRIPTION、ONE_TIME、CREDITS、DONATION（不分大小寫）

回應範例

{
  "object": "list",
  "data": [
    {
      "object": "product",
      "id": "prod_xxxxx",
      "name": "專業方案",
      "slug": "pro-plan",
      "description": "適合成長中團隊的完整功能方案",
      "type": "SUBSCRIPTION",
      "interval": "month",
      "interval_count": 1,
      "price": 299,
      "currency": "TWD",
      "trial_days": 14,
      "display_order": 1,
      "metadata": null,
      "active": true,
      "created_at": "2025-01-01T00:00:00.000Z"
    }
  ],
  "livemode": false
}

程式碼範例

// 列出所有啟用中的訂閱方案
const response = await fetch(
  'https://api.recur.tw/v1/products?type=subscription',
  {
    headers: {
      'Authorization': `Bearer ${process.env.RECUR_SECRET_KEY}`,
    },
  }
);

const { data } = await response.json();

for (const product of data) {
  console.log(`${product.name}: NT$${product.price} / ${product.interval}`);
}

取得產品

以產品 ID 取得單一產品的完整資訊。

端點

GET /products/:id

回應範例

{
  "object": "product",
  "id": "prod_xxxxx",
  "name": "專業方案",
  "slug": "pro-plan",
  "description": "適合成長中團隊的完整功能方案",
  "type": "SUBSCRIPTION",
  "interval": "month",
  "interval_count": 1,
  "price": 299,
  "currency": "TWD",
  "trial_days": 14,
  "display_order": 1,
  "metadata": null,
  "active": true,
  "created_at": "2025-01-01T00:00:00.000Z",
  "updated_at": "2025-01-15T10:00:00.000Z",
  "livemode": false
}

產品不存在時回傳 404 not_found。

以 Slug 取得產品

以產品的 slug 取得單一產品，適合用在以 slug 組成網址的定價或商品頁面。

端點

GET /products/by-slug/:slug

程式碼範例

const response = await fetch(
  'https://api.recur.tw/v1/products/by-slug/pro-plan',
  {
    headers: {
      'Authorization': `Bearer ${process.env.RECUR_SECRET_KEY}`,
    },
  }
);

if (response.status === 404) {
  throw new Error('找不到產品');
}

const product = await response.json();

回應格式與取得產品相同；slug 不存在時回傳 404 not_found。

下一步

Last updated on