get
https://{subdomain}.myshoplaza.com/openapi/2025-06/gift_cards
Retrieves a list of gift cards with various filtering options.
Requiresread_gift_cardsaccess 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
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
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 |