🔒
Requires read_gift_cards access scope. More access scope

The Gift Card List API retrieves a list of gift cards with various filtering options.

This API is especially useful for:

Listing all gift cards with detailed information.
Filtering gift cards by creation date, update date, or initial value.
Paginating and managing large sets of gift card data.

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Body Parameters

Parameter	Type	Required	Description	Example
`cursor`	string	No	Cursor for pagination	`"next_page_token"`
`page_size`	integer	No	Number of records per page. Default is 10	`20`
`ids`	array of strings	No	List of gift card IDs	`["gc_123", "gc_456"]`
`created_at_min`	string	No	Filter gift cards created at or after this date (ISO 8601 format)	`"2025-01-01T00:00:00Z"`
`created_at_max`	string	No	Filter gift cards created at or before this date (ISO 8601 format)	`"2025-06-30T23:59:59Z"`
`updated_at_min`	string	No	Filter gift cards last updated at or after this date (ISO 8601 format)	`"2025-03-01T00:00:00Z"`
`updated_at_max`	string	No	Filter gift cards last updated at or before this date (ISO 8601 format)	`"2025-05-31T23:59:59Z"`
`initial_value_min`	float	No	Filter gift cards with initial value greater than this	`10.0`
`initial_value_max`	float	No	Filter gift cards with initial value less than this	`100.0`
`status`	string	No	Status of the gift card	`"active"`
`balance_status`	string	No	Keyword for balance status	`"positive"`
`keyword`	string	No	Search keyword	`"birthday"`
`sort_by`	string	No	Field to sort by	`"created_at"`
`sort_direction`	string	No	Sort direction	`"desc"`

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`"200"`	The status code of the response
`message`	string	`"success"`	The message describing the response status
`data.gift_cards`	array	`[{"id": "gc_123", "last_characters": "123", "balance": "50.00", ...}]`	List of gift card objects
`data.gift_cards[].id`	string	`"gc_123456"`	The unique identifier of the gift card
`data.gift_cards[].last_characters`	string	`"456"`	The last characters of the gift card code
`data.gift_cards[].balance`	string	`"50.00"`	The current balance of the gift card
`data.gift_cards[].initial_value`	string	`"100.00"`	The initial value of the gift card
`data.gift_cards[].note`	string	`"Birthday gift"`	Notes about the gift card
`data.gift_cards[].expires_on`	string	`"2025-12-31"`	Expiration date of the gift card
`data.gift_cards[].disabled_at`	string	`"2025-06-01"`	Date when the gift card was disabled (null if active)
`data.gift_cards[].enabled`	boolean	`true`	Whether the gift card is enabled
`data.gift_cards[].created_at`	string	`"2025-01-15T10:30:00Z"`	Creation timestamp of the gift card
`data.gift_cards[].updated_at`	string	`"2025-03-20T14:45:00Z"`	Last update timestamp of the gift card
`data.gift_cards[].status`	string	`"active"`	Current status of the gift card
`data.gift_cards[].currency`	string	`"USD"`	Currency of the gift card
`data.gift_cards[].line_item_id`	string	`"li_123"`	Associated line item ID (if any)
`data.gift_cards[].order_id`	string	`"order_456"`	Associated order ID (if any)
`data.gift_cards[].user_id`	string	`"user_789"`	User ID who created the gift card
`data.gift_cards[].template_suffix`	string	`"birthday"`	Template suffix used for the gift card
`data.gift_cards[].customer_id`	string	`"cust_101"`	Customer ID associated with the gift card
`data.gift_cards[].code`	string	`"GIFT123456"`	Full gift card code
`data.cursor`	string	`"next_page_token"`	Cursor for next page of results
`data.has_more`	boolean	`true`	Whether there are more results available

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message

200OK

400InvalidParameter

500ServerError