Search Gifts

🚧
Breaking Changes
Jul. 30, 2025 拿取商品相關資訊 API 異動公告 Products related API Breaking Change

Function

To search gifts with specific conditions.
利用特殊條件搜尋贈品列表。

URL

GET <<api_domain>>/v1/gifts/search

Request Parameters

Parameter	Column Type	Description	Example
id	`String`	Gift's ID 贈品 ID
page	`Integer`	Page Number 頁數（第n頁） (Default: 1)	`ruby page=2`
per_page	`Integer`	Numbers of Add-on Products Per Page 每頁顯示 n 筆資料 (Default: 24)	`ruby per_page=10`
status	`String`	Status 贈品狀態 Status： active上架 draft 下架	`ruby status=active`
sort_by	`String`	Sort by created_atdesc 降冪asc升冪	`ruby sort_by=desc sort_by=asc`
sku	`String`	SKU 貨物編號	`ruby sku=fru001`
quantity	`Integer`	Quantity 數量 *Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於	`ruby quantity=100 quantity=not:100 quantity=lt:100 quantity=lte:100 quantity=gt:100 quantity=gte:100`
updated_at	`String`	Updated Time 更新時間 *Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於	`ruby updated_at=2018-11-11 12:30:30 updated_at=not: 2018-11-11 12:30:30 updated_at=lt: 2018-11-11 12:30:30 updated_at=lte: 2018-11-11 12:30:30 updated_at=gt: 2018-11-11 12:30:30 updated_at=gte: 2018-11-11 12:30:30`
created_at	`String`	Created Time 創建時間 *Support `equal` or `not equal` or `less than` or `less than or equal` or `greater than` or `greater than or equal` 支援等於或不等於或小於或小於等於或大於或大於等於	`ruby created_at=2018-11-11 12:30:30 created_at=not: 2018-11-11 12:30:30 created_at=lt: 2018-11-11 12:30:30 created_at=lte: 2018-11-11 12:30:30 created_at=gt: 2018-11-11 12:30:30 created_at=gte: 2018-11-11 12:30:30`

🚧
Note
Please note the following pagination limitations when using this API:

The request will fail if page * per_page exceeds 10,000.

Example: If per_page = 50, the maximum value for page should be 200. Exceeding this value will result in an error.

使用此 API 時，請注意以下分頁限制：

當 page * per_page 大於 10,000 時，請求將會失敗。

範例：如果 per_page = 50，page 最大值應為 200，超過此值請求將會失敗。

Response Fields

Field	Column Type	Description	Example
items	Get Gifts	Array of Gifts 贈品資訊	Please check the link on the left
pagination	Pagination	Pagination Data 頁面資訊	Please check the link on the left

Response Example

{
    "items": [
        {
            "id": "60d5b37b52fb76002665d821",
            "status": "active",
            "title_translations": {
                "en": "Sample Gift 0001"
            },
            "sku": "GIFT-SKU-0001",
            "quantity": 0,
            "cost": {
                "cents": 12,
                "currency_symbol": "NT$",
                "currency_iso": "TWD",
                "label": "NT$12",
                "dollars": 12.0
            },
            "weight": 12.1,
            "medias": [],
            "updated_at": "2021-06-25T10:44:11.072+00:00",
            "created_at": "2021-06-25T10:44:11.072+00:00",
            "unlimited_quantity": true,
        },
        {
            "id": "60d5b34923df7b002cd70f67",
            "status": "active",
            "title_translations": {
                "en": "Sample Gift 0001"
            },
            "sku": "GIFT-SKU-0001",
            "quantity": 0,
            "cost": {
                "cents": 12,
                "currency_symbol": "NT$",
                "currency_iso": "TWD",
                "label": "NT$12",
                "dollars": 12.0
            },
            "weight": 12.1,
            "medias": [],
            "updated_at": "2021-06-25T10:43:21.971+00:00",
            "created_at": "2021-06-25T10:43:21.971+00:00",
            "unlimited_quantity": false,
        },
        {
            "id": "60d5b3409e545a003e4b8c69",
            "status": "active",
            "title_translations": {
                "en": "Sample Gift 0001"
            },
            "sku": "GIFT-SKU-0001",
            "quantity": 0,
            "cost": {
                "cents": 12,
                "currency_symbol": "NT$",
                "currency_iso": "TWD",
                "label": "NT$12",
                "dollars": 12.0
            },
            "weight": 12.1,
            "medias": [],
            "updated_at": "2021-06-25T10:43:12.145+00:00",
            "created_at": "2021-06-25T10:43:12.145+00:00",
            "unlimited_quantity": false,
        },
        {
            "id": "60d5b2b0ca4c5b00176ba405",
            "status": "active",
            "title_translations": {
                "en": "create by open api"
            },
            "sku": "GIFT-SKU-0001",
            "quantity": 0,
            "cost": {
                "cents": 12,
                "currency_symbol": "NT$",
                "currency_iso": "TWD",
                "label": "NT$12",
                "dollars": 12.0
            },
            "weight": 12.1,
            "medias": [],
            "updated_at": "2021-06-25T10:40:48.970+00:00",
            "created_at": "2021-06-25T10:40:48.970+00:00",
            "unlimited_quantity": true,
        }
    ],
    "pagination": {
        "current_page": 1,
        "per_page": 10,
        "total_pages": 1,
        "total_count": 4
    }
}

Sample Request

Search Gift with specific SKU

curl --location --request GET '<<api_domain>>/v1/gifts/search?page=1&per_page=10&sku=GIFT-SKU-0001' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${token}'

Search with status , SKU , updated_at

curl --location --request GET '<<api_domain>>/v1/gifts/search?page=1&per_page=10&status=active&sku=GIFT-SKU-0001&updated_at=gt:2018-12-05' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer ${token}'

Updated 13 days ago