**Version: 202601**

# List gift cards

**GET** `/openapi/2026-01/gift_cards`

Retrieves a list of gift cards with various filtering options.

## Request

**Query Parameters**

- `cursor` string

  Cursor for pagination
- `page_size` int32

  Number of records per page. The default value is 10
- `page` int32

  Page number (1-based). Mutually exclusive with cursor
- `ids` string[]

  List of gift card IDs to filter by. Example: ?ids=GC1001&ids=GC1002
- `created_at_min` string

  Filter gift cards created at or after this time (e.g., 2018-11-02T12:30:10Z)
- `created_at_max` string

  Filter gift cards created at or before this time (e.g., 2018-11-02T12:30:10Z)
- `updated_at_min` string

  Filter gift cards last updated at or after this time (e.g., 2018-11-02T12:30:10Z)
- `updated_at_max` string

  Filter gift cards last updated at or before this time (e.g., 2018-11-02T12:30:10Z)
- `initial_value_min` float

  Filter gift cards with initial value greater than or equal to this amount
- `initial_value_max` float

  Filter gift cards with initial value less than or equal to this amount
- `status` string

  Status of the gift card:

  *   `enable`: gift card is active and usable
  *   `disable`: gift card is disabled and cannot be used
- `balance_status` string

  Filter by balance status of the gift card
- `keyword` string

  Keyword for searching gift cards (e.g., matches against code or note)
- `sort_by` string

  Field to sort the results by (e.g., created\_at, updated\_at)
- `sort_direction` string

  Sort direction:

  *   `asc`: ascending order
  *   `desc`: descending order

## Responses

**200**

OK

**application/json**

**Schema | Example**

**Schema**

- `code` string

  error code
- `message` string

  error message
- `data` object

  - `gift_cards` object[]

    List of gift cards

    *   Array \[

    - `id` string

      Gift card ID
    - `last_characters` string

      Last four characters of the gift card code
    - `balance` string

      Current balance of the gift card
    - `initial_value` string

      The initial value of the gift card
    - `note` string

      Note attached to the gift card
    - `expires_on` string

      Expiration date of the gift card (e.g., 2018-11-02T12:30:10Z)
    - `disabled_at` string

      Time when the gift card was disabled (e.g., 2018-11-02T12:30:10Z)
    - `enabled` boolean

      Whether the gift card is currently enabled
    - `created_at` string

      Time when the gift card was created (e.g., 2018-11-02T12:30:10Z)
    - `updated_at` string

      Time when the gift card was last updated (e.g., 2018-11-02T12:30:10Z)
    - `status` string

      Status of the gift card:

      *   `enable`: gift card is active and usable
      *   `disable`: gift card is disabled and cannot be used
    - `currency` string

      Currency in which the gift card is denominated
    - `line_item_id` string

      ID of the line item associated with the gift card
    - `order_id` string

      ID of the order associated with the gift card
    - `user_id` string

      User ID of the creator or owner of the gift card
    - `template_suffix` string

      Suffix of the template used to render the gift card online
    - `customer_id` string

      Customer ID associated with the gift card
    - `code` string

      The gift card code, consisting of alphanumeric characters (minimum: 8 characters, maximum: 20 characters)
    *   \]
  - `cursor` string

    The cursor for the next page of results
  - `has_more` boolean

    Whether there are more records
  - `total` int32

    Total number of records across all pages (for page-mode pagination)

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "gift_cards": [
      {
        "id": "string",
        "last_characters": "string",
        "balance": "string",
        "initial_value": "string",
        "note": "string",
        "expires_on": "string",
        "disabled_at": "string",
        "enabled": true,
        "created_at": "string",
        "updated_at": "string",
        "status": "string",
        "currency": "string",
        "line_item_id": "string",
        "order_id": "string",
        "user_id": "string",
        "template_suffix": "string",
        "customer_id": "string",
        "code": "string"
      }
    ],
    "cursor": "string",
    "has_more": true,
    "total": 0
  }
}
```