get https://{shopdomain}.myshoplaza.com/openapi/2022-01/gift_cards
Requires
price_rulesaccess 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
Query Parameters
| Field | Type | Required | Example | Description |
|---|---|---|---|---|
status | string | No | enable | Status of the gift card. |
created_at_min | string | No | 2018-10-01T16:15:47-04:00 | Filter gift cards created at or after this date. |
created_at_max | string | No | 2018-10-01T16:15:47-04:00 | Filter gift cards created at or before this date. |
updated_at_min | string | No | 2018-10-01T16:15:47-04:00 | Filter gift cards last updated at or after this date. |
updated_at_max | string | No | 2018-10-01T16:15:47-04:00 | Filter gift cards last updated at or before this date. |
initial_value_min | string | No | 50.00 | Filter gift cards with initial value greater than this. |
initial_value_max | string | No | 200.00 | Filter gift cards with initial value less than this. |
page | string | No | 1 | Page number for pagination. |
limit | string | No | 10 | Limit of gift cards per page. |
ids | string | No | 377026890382183978,377006280092433706 | Comma-separated list of gift card IDs. |
Response Explanation
Public Response Parameters
Success Response
| Field | Type | Description | Example |
|---|---|---|---|
gift_cards[].id | string | Unique identifier for the gift card. | 377026890382183978 |
gift_cards[].last_characters | string | Last characters of the gift card code. | 218p |
gift_cards[].balance | string | Current balance of the gift card. | 100.00 |
gift_cards[].initial_value | string | The initial value of the gift card. | 100.00 |
gift_cards[].note | string | Note attached to the gift card. | note |
gift_cards[].expires_on | string | Expiration date of the gift card in ISO-8601 format. | 2025-11-01T00:00:00Z |
gift_cards[].disabled_at | string | Timestamp when the gift card was disabled. | null |
gift_cards[].enabled | boolean | Whether the gift card is currently enabled. | true |
gift_cards[].created_at | string | Timestamp of when the gift card was created. | 2024-05-06T10:12:05Z |
gift_cards[].updated_at | string | Timestamp of when the gift card was last updated. | 2024-05-06T10:12:05Z |
gift_cards[].status | string | Status of the gift card (enable or disable). | enable |
gift_cards[].currency | string | Currency in which the gift card is denominated. | USD |
gift_cards[].line_item_id | string | ID of the line item associated with the gift card. | null |
gift_cards[].order_id | string | ID of the order associated with the gift card. | null |
gift_cards[].user_id | string | User ID of the creator or owner of the gift card. | cba51e16-ac53-43d8-a7a3-161c5b1ecd8e |
gift_cards[].template_suffix | string | Suffix of the template used to render the gift card online. | null |
gift_cards[].customer_id | string | Customer ID associated with the gift card. | 2dd957e3-2051-4cdf-8584-9c0046b4d1ae |
total | string | Total number of gift cards matching the query. | 2 |
Error Response
Error responses in the API can be represented using two different fields: errors and error. Both fields provide details about issues encountered during request processing. Below is an explanation of the fields with their respective examples and descriptions.
| Field | Type | Example | Description |
|---|---|---|---|
errors | Array | [ "invalid line_item id"] | A list of errors encountered during the request processing. |
| Field | Type | Example | Description |
|---|---|---|---|
error | String | "store is not active" | Indicates an error encountered during the process |
Error Detail
| Status Code | Message | Possible Reason | Example Response |
|---|---|---|---|
| 400 | Bad Request | Invalid input format or request structure (e.g., missing required fields or incorrect data types). | Bad Request |
| Unauthorized | The request is missing valid authentication credentials or the credentials provided are invalid. | Unauthorized | |
| 422 | The time parameter passed in is illegal | invalid time parameter | The time parameter passed in is illegal |
| The status parameter passed in is illegal | invalid status | The status parameter passed in is illegal |