The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

Gift Card

Requires gift_cards access scope.

Note

You need to contact Shopify Support to request the write_gift_cards and read_gift_cards access scopes.

A gift card is an alternative payment method. Each gift card has a unique code that is entered during checkout. Its balance can be redeemed over multiple checkouts. Optionally, a gift card can assigned to a specific customer. Gift card codes cannot be retrieved after they're created—only the last four characters can be retrieved.

You can use the GiftCard resource to create, retrieve, and update gift cards for a store. After a gift card is created, only the expiry date, note, and template suffix can be updated.

Note

You can't delete gift cards, but you can disable them. You can't enable gift cards that were previously disabled.

Was this section helpful?
Anchor to section titled 'The Gift Card resource'

The Gift Card resource

Properties
api_client_id
deprecated
The ID of the client that issued the gift card.
balance
string
->balance
The balance of the gift card.
code
The gift card code, which is a string of alphanumeric characters. For security reasons, this is available only upon creation of the gift card. (minimum: 8 characters, maximum: 20 characters)
created_at
->createdAt
The date and time (ISO 8601 format) when the gift card was created.
currency
string
->balance
The currency of the gift card.
customer_id
->customer
The ID of the customer associated with this gift card.
disabled_at
->deactivatedAt
The date and time (ISO 8601 format) when the gift card was disabled.
expires_on
->expiresOn
The date (YYYY-MM-DD format) when the gift card expires. Returns null if the gift card doesn't have an expiration date.
id
->id
The ID of the gift card.
initial_value
string
->initialValue
The initial value of the gift card when it was created.
last_characters
->lastCharacters
The last four characters of the gift card code. Because gift cards are alternative payment methods, the full code cannot be retrieved.
line_item_id
deprecated
The ID of the line item that initiated the creation of this gift card, if it was created by an order.
Was this section helpful?
{}The Gift Card resource
{
  "api_client_id": 431223487,
  "balance": "80.17",
  "code": "1234 4567 8901 2ABC",
  "created_at": "2008-12-31T19:00:00-05:00",
  "currency": "CAD",
  "customer_id": 368407052327,
  "disabled_at": "2009-01-31T19:00:00-05:00",
  "expires_on": "2020-01-31",
  "id": 989034056,
  "initial_value": "100.00",
  "last_characters": "2ABC",
  "line_item_id": 241253183,
  "note": "A note",
  "order_id": 241253183,
  "template_suffix": "birthday",
  "user_id": 876543210,
  "updated_at": "2009-01-31T19:00:00-05:00"
}
Anchor to section titled 'POST request, Creates a gift card'

post
Creates a gift card

giftCardCreate

Creates a gift card.

There are additional optional parameters that can be specified in the body of the request when creating a gift card:

Anchor to section titled 'Parameters of Creates a gift card'

Parameters

api_version
string
required
customer_id
The ID of the customer that purchased the gift card.
recipient_id
The ID of the intended recipient of the gift card. This property should be used if the recipientis different from the purchaser. The customer with this ID must have an email address.
Was this section helpful?
Anchor to section titled 'Examples of Creates a gift card'

Examples

Request body
giftcard
Gift_card resource
Was this section helpful?
post
/admin/api/2024-10/gift_cards.json
Copy
curl -d '{"gift_card":{"note":"This is a note","initial_value":"100.00","code":"ABCD EFGH IJKL MNOP","template_suffix":"gift_cards.birthday.liquid"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-10/gift_cards.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936326,
    "balance": "100.00",
    "created_at": "2024-09-24T09:01:07-04:00",
    "updated_at": "2024-09-24T09:01:07-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": "This is a note",
    "expires_on": null,
    "template_suffix": "gift_cards.birthday.liquid",
    "last_characters": "mnop",
    "order_id": null,
    "code": "abcdefghijklmnop"
  }
}
Anchor to section titled 'POST request, Disables a gift card'

post
Disables a gift card

giftCardDeactivate
Disables a gift card. This action can't be undone.
Anchor to section titled 'Parameters of Disables a gift card'

Parameters

api_version
string
required
gift_card_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Disables a gift card'

Examples

Path parameters
giftcardid=1035197676
string
required
Request body
giftcard
Gift_card resource
Was this section helpful?
post
/admin/api/2024-10/gift_cards/1035197676/disable.json
Copy
curl -d '{"gift_card":{"id":1035197676}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2024-10/gift_cards/1035197676/disable.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 201 Created
{
  "gift_card": {
    "disabled_at": "2024-09-24T09:01:06-04:00",
    "template_suffix": null,
    "initial_value": "100.00",
    "balance": "100.00",
    "id": 1035197676,
    "created_at": "2024-09-24T09:00:31-04:00",
    "updated_at": "2024-09-24T09:01:06-04:00",
    "currency": "USD",
    "line_item_id": null,
    "api_client_id": null,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
Anchor to section titled 'GET request, Retrieves a list of gift cards'

get
Retrieves a list of gift cards

giftCards
Retrieves a list of gift cards. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.
Anchor to section titled 'Parameters of Retrieves a list of gift cards'

Parameters

api_version
string
required
fields
Show only certain fields, specified by a comma-separated list of field names.
limit
≤ 250
default 50
The maximum number of results to show.
since_id
Restrict results to after the specified ID.
status
Retrieve gift cards with a given status. Valid values:
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a list of gift cards'

Examples

Query parameters
status=enabled
Retrieve gift cards with a given status. Valid values:
Was this section helpful?
get
/admin/api/2024-10/gift_cards.json?status=enabled
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/gift_cards.json?status=enabled" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 766118925,
      "balance": "25.00",
      "created_at": "2024-09-24T09:00:31-04:00",
      "updated_at": "2024-09-24T09:00:31-04:00",
      "currency": "USD",
      "initial_value": "50.00",
      "disabled_at": null,
      "line_item_id": null,
      "api_client_id": null,
      "user_id": null,
      "customer_id": null,
      "note": null,
      "expires_on": "2023-09-24",
      "template_suffix": null,
      "notify": true,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 10274553,
      "balance": "0.00",
      "created_at": "2024-09-24T09:00:31-04:00",
      "updated_at": "2024-09-24T09:00:31-04:00",
      "currency": "USD",
      "initial_value": "50.00",
      "disabled_at": null,
      "line_item_id": null,
      "api_client_id": null,
      "user_id": null,
      "customer_id": null,
      "note": null,
      "expires_on": null,
      "template_suffix": null,
      "notify": true,
      "last_characters": "0y0y",
      "order_id": null
    }
  ]
}
Anchor to section titled 'GET request, Retrieves a single gift card'

get
Retrieves a single gift card

giftCard
Retrieves a single gift card by its ID
Anchor to section titled 'Parameters of Retrieves a single gift card'

Parameters

api_version
string
required
gift_card_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a single gift card'

Examples

Path parameters
giftcardid=1035197676
string
required
Was this section helpful?
get
/admin/api/2024-10/gift_cards/1035197676.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/gift_cards/1035197676.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 1035197676,
    "balance": "100.00",
    "created_at": "2024-09-24T09:00:31-04:00",
    "updated_at": "2024-09-24T09:00:31-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": null,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
Anchor to section titled 'GET request, Retrieves a count of gift cards'

get
Retrieves a count of gift cards

giftCardsCount
Retrieves a count of gift cards with a given status.
Anchor to section titled 'Parameters of Retrieves a count of gift cards'

Parameters

api_version
string
required
status
Count gift cards with a given status. Valid values:
Was this section helpful?
Anchor to section titled 'Examples of Retrieves a count of gift cards'

Examples

Was this section helpful?
get
/admin/api/2024-10/gift_cards/count.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/gift_cards/count.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "count": 3
}
Anchor to section titled 'GET request, Searches for gift cards'

get
Searches for gift cards

giftCards

Searches for gift cards that match a supplied query. The following fields are indexed by search:

  • created_at
  • updated_at
  • disabled_at
  • balance
  • initial_value
  • amount_spent
  • email
  • last_characters

Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

Anchor to section titled 'Parameters of Searches for gift cards'

Parameters

api_version
string
required
created_at_max
date
ISO 8601
Show gift cards created at or before date.
created_at_min
date
ISO 8601
Show gift cards created at or after date.
fields
Show only certain fields, specified by a comma-separated list of field names.
limit
≤ 250
default 50
The maximum number of results to retrieve.
order
default disabled_at DESC
The field and direction to order results by.
query
The text to search for.
updated_at_max
date
ISO 8601
Show gift cards last updated at or before date.
updated_at_min
date
ISO 8601
Show gift cards last updated at or after date.
Was this section helpful?
Anchor to section titled 'Examples of Searches for gift cards'

Examples

Query parameters
query=last_characters:mnop
The text to search for.
Was this section helpful?
get
/admin/api/2024-10/gift_cards/search.json?query=last_characters:mnop
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/gift_cards/search.json?query=last_characters%3Amnop" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 1063936323,
      "balance": "10.00",
      "created_at": "2024-09-24T09:01:03-04:00",
      "updated_at": "2024-09-24T09:01:03-04:00",
      "currency": "USD",
      "initial_value": "10.00",
      "disabled_at": null,
      "line_item_id": null,
      "api_client_id": null,
      "user_id": null,
      "customer_id": null,
      "note": null,
      "expires_on": null,
      "template_suffix": null,
      "notify": true,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}
Anchor to section titled 'PUT request, Updates an existing gift card'

put
Updates an existing gift card

giftCardUpdate

Updates an existing gift card.

Expiry date, note, and template suffix properties of a gift card can be changed via the API.

A customer ID can only be set if the current value is `null`.

Anchor to section titled 'Parameters of Updates an existing gift card'

Parameters

api_version
string
required
gift_card_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Updates an existing gift card'

Examples

Path parameters
giftcardid=1035197676
string
required
Request body
giftcard
Gift_card resource
Was this section helpful?
put
/admin/api/2024-10/gift_cards/1035197676.json
Copy
curl -d '{"gift_card":{"id":1035197676,"expires_on":"2020-01-01"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2024-10/gift_cards/1035197676.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"
{}Response
JSON
HTTP/1.1 200 OK
{
  "gift_card": {
    "expires_on": "2020-01-01",
    "template_suffix": null,
    "initial_value": "100.00",
    "balance": "100.00",
    "id": 1035197676,
    "created_at": "2024-09-24T09:00:31-04:00",
    "updated_at": "2024-09-24T09:01:09-04:00",
    "currency": "USD",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": null,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}