---
title: Products API
description: 查詢可用的產品（訂閱方案、一次性付款等）
---

# Products API

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

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

## 產品物件

```json
{
  "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
}
```

### 欄位說明

| 欄位 | 類型 | 說明 |
|------|------|------|
| `object` | string | 固定為 `"product"` |
| `id` | string | 產品 ID |
| `name` | string | 產品名稱 |
| `slug` | string \| null | URL 友善的產品識別碼 |
| `description` | string \| null | 產品描述 |
| `type` | string | 產品類型：`SUBSCRIPTION`、`ONE_TIME`、`CREDITS`、`DONATION` |
| `interval` | string \| null | 計費週期單位：`day`、`week`、`month`、`year`（非訂閱產品為 `null`） |
| `interval_count` | number | 計費週期數量（例如 `3` + `month` = 每季） |
| `price` | number | 價格（整數，例如 `299` 代表 NT$299） |
| `currency` | string | 幣別（目前為 `TWD`） |
| `trial_days` | number \| null | 試用天數（無試用期為 `null`） |
| `display_order` | number \| null | 顯示排序 |
| `metadata` | object \| null | 自訂 metadata |
| `active` | boolean | 是否啟用（`false` 為已封存） |
| `created_at` | string | 建立時間（ISO 8601） |
| `updated_at` | string | 最後更新時間（ISO 8601，僅單筆查詢回傳） |
| `livemode` | boolean | 是否為正式環境 |

---

## 列出產品

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

### 端點

```
GET /products
```

### 請求參數

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

### 回應範例

```json
{
  "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
}
```

### 程式碼範例

```typescript
// 列出所有啟用中的訂閱方案
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}`);
}
```

```bash
curl "https://api.recur.tw/v1/products?type=subscription" \
  -H "Authorization: Bearer sk_test_xxx"
```

---

## 取得產品

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

### 端點

```
GET /products/:id
```

### 回應範例

```json
{
  "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
```

### 程式碼範例

```typescript
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();
```

```bash
curl "https://api.recur.tw/v1/products/by-slug/pro-plan" \
  -H "Authorization: Bearer sk_test_xxx"
```

回應格式與[取得產品](#取得產品)相同；slug 不存在時回傳 `404 not_found`。

---

## 下一步

- [Checkout Sessions API](/api-reference/checkout-sessions) — 用產品 ID 建立結帳
- [付款功能總覽](/features/payments) — 了解各種產品類型的計費行為
- [useProducts Hook](/guides/react-hooks/use-products) — 在 React 前端取得產品列表