List gift cards

GET 
/openapi/2026-07/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

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

Schema

codestring

error code

messagestring

error message

data object

gift_cards object[]

List of gift cards

Array [

idstring

Gift card ID

last_charactersstring

Last four characters of the gift card code

balancestring

Current balance of the gift card

initial_valuestring

The initial value of the gift card

notestring

Note attached to the gift card

expires_onstring

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

disabled_atstring

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

enabledboolean

Whether the gift card is currently enabled

created_atstring

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

updated_atstring

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

statusstring

Status of the gift card:

• enable: gift card is active and usable
• disable: gift card is disabled and cannot be used

currencystring

Currency in which the gift card is denominated

line_item_idstring

ID of the line item associated with the gift card

order_idstring

ID of the order associated with the gift card

user_idstring

User ID of the creator or owner of the gift card

template_suffixstring

Suffix of the template used to render the gift card online

customer_idstring

Customer ID associated with the gift card

codestring

The gift card code, consisting of alphanumeric characters (minimum: 8 characters, maximum: 20 characters)

]

cursorstring

The cursor for the next page of results

has_moreboolean

Whether there are more records

Example

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