> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 取得禮品卡購買紀錄

若要檢視您帳戶的歷史禮品卡購買與虛擬卡，請使用 `getUserPurchases` [查詢](https://storage.googleapis.com/fluz-public-docs/api-reference.html#group-Reference-Queries)。此查詢需要 `LIST_PURCHASES` 範圍。此查詢的回應可能會很龐大，因此我們要求您提供分頁輸入，以及可選的篩選輸入：

## 擷取購買歷史

您可以使用以下查詢來檢視您的交易。

1. `getUserPurchases` — 取得使用者購買紀錄

<StickyContactSalesBanner />

## 分頁輸入

`OffsetInput` 參數用於管理 API 回應的分頁，讓您可以控制每頁要回傳的項目數量，以及從清單開頭要略過多少項目。

### 欄位

**`limit`** **(Int)**：此欄位指定每頁要回傳的項目數量。每頁可要求的最大項目數為 20。若未指定 limit，預設為 20。

**`offset`** **(Int)**：此欄位指定在開始回傳項目前要略過的項目數量。若未指定 offset，預設為 0，表示將從清單的第一個項目開始。

## 篩選輸入

`UserPurchaseFilterInput` 參數用於篩選回應中回傳的購買紀錄。它允許您擷取與您的應用程式關聯之使用者所做的購買，或與您的應用程式關聯之帳戶下的購買，等等。此參數為可選。若未提供，回應將回傳與您的應用程式關聯之使用者在所有帳戶中的購買。

### 欄位

**`scope`** **(Array of `PurchaseScopeFilter`)**：此欄位指定要使用的篩選類型。

##### `PurchaseScopeFilter` 列舉

* TOKEN\_USER：依據 userId 篩選
* TOKEN\_ACCOUNT：依據 accountId 篩選

### 範例

```javascript theme={null}
// QUERY VARIABLES
// returns purchases made by the user across all accounts
{
  "filter": {
	"scope": ["TOKEN_USER"] 
  }	
}
```

```javascript theme={null}
// QUERY VARIABLES
// returns purchases made under the account across all users
{
  "filter": {
	"scope": ["TOKEN_ACCOUNT"] 
  }	
}
```

```javascript theme={null}
// QUERY VARIABLES
// returns purchases made by the user and account
{
  "filter": {
	"scope": ["TOKEN_USER", "TOKEN_ACCOUNT"] 
  }	
}
```

# 回應

當您執行此查詢時，將會回傳一個陣列，包含您歷史的禮品卡購買以及所產生的虛擬卡。

```json theme={null}
{
  "data": {
    "getUserPurchases": [
      {
        "purchaseId": "255f8245-02c7-4817-901e-15fe265f6968",
        "purchaseDisplayId": "1019688",
        "purchaseBankCardId": "255f8245-02c7-4817-901e-15fe265f6968",
        "bankAccountId": "255f8245-02c7-4817-901e-15fe265f6968",
        "purchaseAmount": 987.65,
        "fluzpayAmount": 123.45,
        "seatRewardValue": 987.65,
        "paypalVaultId": "255f8245-02c7-4817-901e-15fe265f6968",
        "createdAt": "2007-12-03T10:15:30Z",
        "purchaserUserId": "4c42e368-d150-492d-8dec-6cda1b58ffa9",
				"accountId": "d67af480-21dc-4c23-93ff-3b7288e52e1a",
        "giftCard": {
          // GiftCardFragment details
        },
        "virtualCard": {
          // VirtualCardFragment details
        }
      },
      {
        "purchaseId": "4f4b3c5d-6f7e-8a9b-0c1d-23e4f5678a90",
        "purchaseDisplayId": "1019688",
        "purchaseBankCardId": "4f4b3c5d-6f7e-8a9b-0c1d-23e4f5678a90",
        "bankAccountId": "4f4b3c5d-6f7e-8a9b-0c1d-23e4f5678a90",
        "purchaseAmount": 250.00,
        "fluzpayAmount": 50.00,
        "seatRewardValue": 10.00,
        "paypalVaultId": "4f4b3c5d-6f7e-8a9b-0c1d-23e4f5678a90",
        "createdAt": "2024-01-10T08:20:00Z",
        "giftCard": {
          // GiftCardFragment details
        },
        "virtualCard": {
          // VirtualCardFragment details
        }
      },
      {
        "purchaseId": "7e8f9a0b-1c2d-3e4f-5g6h-789i0jklm1no",
        "purchaseDisplayId": "1019688",
        "purchaseBankCardId": "7e8f9a0b-1c2d-3e4f-5g6h-789i0jklm1no",
        "bankAccountId": "7e8f9a0b-1c2d-3e4f-5g6h-789i0jklm1no",
        "purchaseAmount": 450.75,
        "fluzpayAmount": 75.00,
        "seatRewardValue": 30.00,
        "paypalVaultId": "7e8f9a0b-1c2d-3e4f-5g6h-789i0jklm1no",
        "createdAt": "2024-02-15T14:45:00Z",
        "giftCard": {
          // GiftCardFragment details
        },
        "virtualCard": {
          // VirtualCardFragment details
        }
      }
    ]
  }
}
```

## UserPurchase 物件中的欄位

| Field name         | Type        | Description                                 |
| :----------------- | :---------- | :------------------------------------------ |
| purchaseId         | String      | 購買紀錄的唯一識別碼。                                 |
| purchaseDisplayId  | String      | 購買紀錄的顯示 ID。                                 |
| purchaseBankCardId | String      | 用於此次購買之銀行卡的識別碼。                             |
| bankAccountId      | String      | 與此次購買相關聯之銀行帳戶識別碼。                           |
| purchaseAmount     | Float       | 此次購買的總支出金額。                                 |
| fluzpayAmount      | Float       | 交易中使用的可用 Fluz 餘額金額。                         |
| seatRewardValue    | Float       | 此次購買所產生的網路席次獎勵價值。                           |
| paypalVaultId      | String      | 此次購買所使用的 PayPal vault 識別碼。                  |
| createdAt          | DateTime    | 指示進行購買的時間戳記。                                |
| purchaserUserId    | String      | 進行購買之使用者的識別碼。                               |
| accountId          | String      | 進行購買之帳戶的識別碼。                                |
| giftCard           | GiftCard    | 包含此次購買中任何禮品卡的詳細資料，由 GiftCardFragment 表示。    |
| virtualCard        | VirtualCard | 包含此次購買中任何虛擬卡的詳細資料，由 VirtualCardFragment 表示。 |