Gift Card

Version 2019-04

Shopify Plus

The Gift Card resource is available only for private apps installed on Shopify Plus stores.

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.

What you can do with Gift Card

The Shopify API lets you do the following with the Gift Card resource. More detailed versions of these general actions may be available:

Gift Card properties

api_client_id 
"api_client_id": 431223487

The ID of the app that issued the gift card, if it was issued by an app.
balance 
"balance": 80.17

The balance of the gift card.
code 
"code": "1234 4567 8901 2ABC"

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 
"created_at": "2008-12-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was created.
currency 
"currency": "CAD"

The currency of the gift card.
customer_id 
"customer_id": 368407052327

The ID of a customer who is associated with this gift card.
disabled_at 
"disabled_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was disabled.
expires_on 
"expires_on": "2020-01-31"

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": 989034056

The ID of the gift card.
initial_value 
"initial_value": 100.0

The initial value of the gift card when it was created.
last_characters 
"last_characters": "2ABC"

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 
"line_item_id": 241253183

The ID of the line item that caused the creation of this gift card, if it was created by an order.
note 
"note": "A note"

The text of an optional note that a merchant can attach to the gift card. Not visible to customers.
order_id 
"order_id": 241253183

The ID of the order that caused the creation of this gift card, if it was created by an order.
template_suffix 
"template_suffix": "birthday"

The suffix of the Liquid template that's used to render the gift card online. For example, if the value is birthday, then the gift card is rendered using the template gift_card.birthday.liquid. When the value is null, the default gift_card.liquid template is used.

user_id 
"user_id": 241253183

The ID of the user that issued the gift card, if it was issued by a user.
updated_at 
"updated_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was last modified.

Endpoints

GET /admin/api/2019-04/gift_cards.json
Retrieves a list of gift cards.
status

Retrieve gift cards with a given status. Valid values:

  • enabled: Restrict results to only enabled gift cards
  • disabled: Restrict results to only disabled gift cards
limit

The maximum number of results to show.

(default: 50, maximum: 250)
page
deprecated

The page of results to show.

(default: 1)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a list of all gift cards

GET /admin/api/2019-07/gift_cards.json
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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,
      "last_characters": "0y0y",
      "order_id": null
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}

Retrieve a list of all enabled gift cards

GET /admin/api/2019-07/gift_cards.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}
GET /admin/api/2019-04/gift_cards/{gift_card_id}.json
Retrieves a single gift card by its ID

Retrieve a single gift card

GET /admin/api/2020-07/gift_cards/48394658.json
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T12:56:27-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
  }
}
GET /admin/api/2019-04/gift_cards/count.json
Retrieves a count of gift cards
status

Count gift cards with a given status. Valid values:

  • enabled: Count only enabled gift cards
  • disabled: Count only disabled gift cards

Retrieve a count of all gift cards

GET /admin/api/2020-07/gift_cards/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of enabled gift cards

GET /admin/api/2020-07/gift_cards/count.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
POST /admin/api/2019-04/gift_cards.json
Creates a gift card

Create a gift card with a custom code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "note": "This is a note",
    "initial_value": 100.0,
    "code": "ABCD EFGH IJKL MNOP",
    "template_suffix": "gift_cards.birthday.liquid"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936316,
    "balance": "100.00",
    "created_at": "2020-07-09T13:00:42-04:00",
    "updated_at": "2020-07-09T13:00:42-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"
  }
}

Create a gift card with an automatically generated code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "initial_value": 25.0
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936317,
    "balance": "25.00",
    "created_at": "2020-07-09T13:00:48-04:00",
    "updated_at": "2020-07-09T13:00:48-04:00",
    "currency": "USD",
    "initial_value": "25.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "3b53",
    "order_id": null,
    "code": "549948948c4a3b53"
  }
}
PUT /admin/api/2019-04/gift_cards/{gift_card_id}.json

Updates an existing gift card.

The gift card's balance can't be changed via the API. You can change only the expiry date, note, and template suffix.

Update the note of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "note": "Updating with a new note"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:51-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": "Updating with a new note",
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

Update the expiry date of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "expires_on": "2020-01-01"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:57-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": "2020-01-01",
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
POST /admin/api/2019-04/gift_cards/{gift_card_id}/disable.json
Disables a gift card. Disabling a gift card can't be undone.

Disable a gift card

POST /admin/api/2020-07/gift_cards/48394658/disable.json
{
  "gift_card": {
    "id": 48394658
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:01:02-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2020-07-09T13:01:02-04:00",
    "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
  }
}
GET /admin/api/2019-04/gift_cards/search.json?query=last_characters:mnop

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
order

The field and direction to order results by.

(default: disabled_at DESC)
query

The text to search for.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
page
deprecated

The page of results to show.

(default: 1)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all gift cards with the last characters "mnop"

GET /admin/api/2019-07/gift_cards/search.json?query=last_characters:mnop
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 1063936318,
      "balance": "10.00",
      "created_at": "2020-07-09T13:01:02-04:00",
      "updated_at": "2020-07-09T13:01:02-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,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}
Version 2019-07

Shopify Plus

The Gift Card resource is available only for private apps installed on Shopify Plus stores.

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.

What you can do with Gift Card

The Shopify API lets you do the following with the Gift Card resource. More detailed versions of these general actions may be available:

Gift Card properties

api_client_id 
"api_client_id": 431223487

The ID of the app that issued the gift card, if it was issued by an app.
balance 
"balance": 80.17

The balance of the gift card.
code 
"code": "1234 4567 8901 2ABC"

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 
"created_at": "2008-12-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was created.
currency 
"currency": "CAD"

The currency of the gift card.
customer_id 
"customer_id": 368407052327

The ID of a customer who is associated with this gift card.
disabled_at 
"disabled_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was disabled.
expires_on 
"expires_on": "2020-01-31"

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": 989034056

The ID of the gift card.
initial_value 
"initial_value": 100.0

The initial value of the gift card when it was created.
last_characters 
"last_characters": "2ABC"

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 
"line_item_id": 241253183

The ID of the line item that caused the creation of this gift card, if it was created by an order.
note 
"note": "A note"

The text of an optional note that a merchant can attach to the gift card. Not visible to customers.
order_id 
"order_id": 241253183

The ID of the order that caused the creation of this gift card, if it was created by an order.
template_suffix 
"template_suffix": "birthday"

The suffix of the Liquid template that's used to render the gift card online. For example, if the value is birthday, then the gift card is rendered using the template gift_card.birthday.liquid. When the value is null, the default gift_card.liquid template is used.

user_id 
"user_id": 241253183

The ID of the user that issued the gift card, if it was issued by a user.
updated_at 
"updated_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was last modified.

Endpoints

GET /admin/api/2019-07/gift_cards.json
Retrieves a list of gift cards.
status

Retrieve gift cards with a given status. Valid values:

  • enabled: Restrict results to only enabled gift cards
  • disabled: Restrict results to only disabled gift cards
limit

The maximum number of results to show.

(default: 50, maximum: 250)
page
deprecated

The page of results to show.

(default: 1)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a list of all gift cards

GET /admin/api/2019-07/gift_cards.json
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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,
      "last_characters": "0y0y",
      "order_id": null
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}

Retrieve a list of all enabled gift cards

GET /admin/api/2019-07/gift_cards.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}
GET /admin/api/2019-07/gift_cards/{gift_card_id}.json
Retrieves a single gift card by its ID

Retrieve a single gift card

GET /admin/api/2020-07/gift_cards/48394658.json
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T12:56:27-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
  }
}
GET /admin/api/2019-07/gift_cards/count.json
Retrieves a count of gift cards
status

Count gift cards with a given status. Valid values:

  • enabled: Count only enabled gift cards
  • disabled: Count only disabled gift cards

Retrieve a count of all gift cards

GET /admin/api/2020-07/gift_cards/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of enabled gift cards

GET /admin/api/2020-07/gift_cards/count.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
POST /admin/api/2019-07/gift_cards.json
Creates a gift card

Create a gift card with a custom code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "note": "This is a note",
    "initial_value": 100.0,
    "code": "ABCD EFGH IJKL MNOP",
    "template_suffix": "gift_cards.birthday.liquid"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936316,
    "balance": "100.00",
    "created_at": "2020-07-09T13:00:42-04:00",
    "updated_at": "2020-07-09T13:00:42-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"
  }
}

Create a gift card with an automatically generated code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "initial_value": 25.0
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936317,
    "balance": "25.00",
    "created_at": "2020-07-09T13:00:48-04:00",
    "updated_at": "2020-07-09T13:00:48-04:00",
    "currency": "USD",
    "initial_value": "25.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "3b53",
    "order_id": null,
    "code": "549948948c4a3b53"
  }
}
PUT /admin/api/2019-07/gift_cards/{gift_card_id}.json

Updates an existing gift card.

The gift card's balance can't be changed via the API. You can change only the expiry date, note, and template suffix.

Update the note of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "note": "Updating with a new note"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:51-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": "Updating with a new note",
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

Update the expiry date of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "expires_on": "2020-01-01"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:57-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": "2020-01-01",
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
POST /admin/api/2019-07/gift_cards/{gift_card_id}/disable.json
Disables a gift card. Disabling a gift card can't be undone.

Disable a gift card

POST /admin/api/2020-07/gift_cards/48394658/disable.json
{
  "gift_card": {
    "id": 48394658
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:01:02-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2020-07-09T13:01:02-04:00",
    "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
  }
}
GET /admin/api/2019-07/gift_cards/search.json?query=last_characters:mnop

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
order

The field and direction to order results by.

(default: disabled_at DESC)
query

The text to search for.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
page
deprecated

The page of results to show.

(default: 1)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all gift cards with the last characters "mnop"

GET /admin/api/2019-07/gift_cards/search.json?query=last_characters:mnop
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 1063936318,
      "balance": "10.00",
      "created_at": "2020-07-09T13:01:02-04:00",
      "updated_at": "2020-07-09T13:01:02-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,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}
Version 2019-10

Shopify Plus

The Gift Card resource is available only for private apps installed on Shopify Plus stores.

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.

What you can do with Gift Card

The Shopify API lets you do the following with the Gift Card resource. More detailed versions of these general actions may be available:

Gift Card properties

api_client_id 
"api_client_id": 431223487

The ID of the app that issued the gift card, if it was issued by an app.
balance 
"balance": 80.17

The balance of the gift card.
code 
"code": "1234 4567 8901 2ABC"

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 
"created_at": "2008-12-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was created.
currency 
"currency": "CAD"

The currency of the gift card.
customer_id 
"customer_id": 368407052327

The ID of a customer who is associated with this gift card.
disabled_at 
"disabled_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was disabled.
expires_on 
"expires_on": "2020-01-31"

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": 989034056

The ID of the gift card.
initial_value 
"initial_value": 100.0

The initial value of the gift card when it was created.
last_characters 
"last_characters": "2ABC"

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 
"line_item_id": 241253183

The ID of the line item that caused the creation of this gift card, if it was created by an order.
note 
"note": "A note"

The text of an optional note that a merchant can attach to the gift card. Not visible to customers.
order_id 
"order_id": 241253183

The ID of the order that caused the creation of this gift card, if it was created by an order.
template_suffix 
"template_suffix": "birthday"

The suffix of the Liquid template that's used to render the gift card online. For example, if the value is birthday, then the gift card is rendered using the template gift_card.birthday.liquid. When the value is null, the default gift_card.liquid template is used.

user_id 
"user_id": 241253183

The ID of the user that issued the gift card, if it was issued by a user.
updated_at 
"updated_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was last modified.

Endpoints

GET /admin/api/2019-10/gift_cards.json
Retrieves a list of gift cards. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
status

Retrieve gift cards with a given status. Valid values:

  • enabled: Restrict results to only enabled gift cards
  • disabled: Restrict results to only disabled gift cards
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a list of all gift cards

GET /admin/api/2020-07/gift_cards.json
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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,
      "last_characters": "0y0y",
      "order_id": null
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}

Retrieve a list of all enabled gift cards

GET /admin/api/2020-07/gift_cards.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}
GET /admin/api/2019-10/gift_cards/{gift_card_id}.json
Retrieves a single gift card by its ID

Retrieve a single gift card

GET /admin/api/2020-07/gift_cards/48394658.json
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T12:56:27-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
  }
}
GET /admin/api/2019-10/gift_cards/count.json
Retrieves a count of gift cards
status

Count gift cards with a given status. Valid values:

  • enabled: Count only enabled gift cards
  • disabled: Count only disabled gift cards

Retrieve a count of all gift cards

GET /admin/api/2020-07/gift_cards/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of enabled gift cards

GET /admin/api/2020-07/gift_cards/count.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
POST /admin/api/2019-10/gift_cards.json
Creates a gift card

Create a gift card with a custom code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "note": "This is a note",
    "initial_value": 100.0,
    "code": "ABCD EFGH IJKL MNOP",
    "template_suffix": "gift_cards.birthday.liquid"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936316,
    "balance": "100.00",
    "created_at": "2020-07-09T13:00:42-04:00",
    "updated_at": "2020-07-09T13:00:42-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"
  }
}

Create a gift card with an automatically generated code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "initial_value": 25.0
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936317,
    "balance": "25.00",
    "created_at": "2020-07-09T13:00:48-04:00",
    "updated_at": "2020-07-09T13:00:48-04:00",
    "currency": "USD",
    "initial_value": "25.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "3b53",
    "order_id": null,
    "code": "549948948c4a3b53"
  }
}
PUT /admin/api/2019-10/gift_cards/{gift_card_id}.json

Updates an existing gift card.

The gift card's balance can't be changed via the API. You can change only the expiry date, note, and template suffix.

Update the note of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "note": "Updating with a new note"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:51-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": "Updating with a new note",
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

Update the expiry date of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "expires_on": "2020-01-01"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:57-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": "2020-01-01",
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
POST /admin/api/2019-10/gift_cards/{gift_card_id}/disable.json
Disables a gift card. Disabling a gift card can't be undone.

Disable a gift card

POST /admin/api/2020-07/gift_cards/48394658/disable.json
{
  "gift_card": {
    "id": 48394658
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:01:02-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2020-07-09T13:01:02-04:00",
    "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
  }
}
GET /admin/api/2019-10/gift_cards/search.json?query=last_characters:mnop

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: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

order

The field and direction to order results by.

(default: disabled_at DESC)
query

The text to search for.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all gift cards with the last characters "mnop"

GET /admin/api/2020-07/gift_cards/search.json?query=last_characters:mnop
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 1063936319,
      "balance": "10.00",
      "created_at": "2020-07-09T13:01:44-04:00",
      "updated_at": "2020-07-09T13:01:44-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,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}
Version 2020-01

Shopify Plus

The Gift Card resource is available only for private apps installed on Shopify Plus stores.

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.

What you can do with Gift Card

The Shopify API lets you do the following with the Gift Card resource. More detailed versions of these general actions may be available:

Gift Card properties

api_client_id 
"api_client_id": 431223487

The ID of the app that issued the gift card, if it was issued by an app.
balance 
"balance": 80.17

The balance of the gift card.
code 
"code": "1234 4567 8901 2ABC"

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 
"created_at": "2008-12-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was created.
currency 
"currency": "CAD"

The currency of the gift card.
customer_id 
"customer_id": 368407052327

The ID of a customer who is associated with this gift card.
disabled_at 
"disabled_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was disabled.
expires_on 
"expires_on": "2020-01-31"

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": 989034056

The ID of the gift card.
initial_value 
"initial_value": 100.0

The initial value of the gift card when it was created.
last_characters 
"last_characters": "2ABC"

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 
"line_item_id": 241253183

The ID of the line item that caused the creation of this gift card, if it was created by an order.
note 
"note": "A note"

The text of an optional note that a merchant can attach to the gift card. Not visible to customers.
order_id 
"order_id": 241253183

The ID of the order that caused the creation of this gift card, if it was created by an order.
template_suffix 
"template_suffix": "birthday"

The suffix of the Liquid template that's used to render the gift card online. For example, if the value is birthday, then the gift card is rendered using the template gift_card.birthday.liquid. When the value is null, the default gift_card.liquid template is used.

user_id 
"user_id": 241253183

The ID of the user that issued the gift card, if it was issued by a user.
updated_at 
"updated_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was last modified.

Endpoints

GET /admin/api/2020-01/gift_cards.json
Retrieves a list of gift cards. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
status

Retrieve gift cards with a given status. Valid values:

  • enabled: Restrict results to only enabled gift cards
  • disabled: Restrict results to only disabled gift cards
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a list of all gift cards

GET /admin/api/2020-07/gift_cards.json
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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,
      "last_characters": "0y0y",
      "order_id": null
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}

Retrieve a list of all enabled gift cards

GET /admin/api/2020-07/gift_cards.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}
GET /admin/api/2020-01/gift_cards/{gift_card_id}.json
Retrieves a single gift card by its ID

Retrieve a single gift card

GET /admin/api/2020-07/gift_cards/48394658.json
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T12:56:27-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
  }
}
GET /admin/api/2020-01/gift_cards/count.json
Retrieves a count of gift cards
status

Count gift cards with a given status. Valid values:

  • enabled: Count only enabled gift cards
  • disabled: Count only disabled gift cards

Retrieve a count of all gift cards

GET /admin/api/2020-07/gift_cards/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of enabled gift cards

GET /admin/api/2020-07/gift_cards/count.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
POST /admin/api/2020-01/gift_cards.json
Creates a gift card

Create a gift card with a custom code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "note": "This is a note",
    "initial_value": 100.0,
    "code": "ABCD EFGH IJKL MNOP",
    "template_suffix": "gift_cards.birthday.liquid"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936316,
    "balance": "100.00",
    "created_at": "2020-07-09T13:00:42-04:00",
    "updated_at": "2020-07-09T13:00:42-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"
  }
}

Create a gift card with an automatically generated code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "initial_value": 25.0
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936317,
    "balance": "25.00",
    "created_at": "2020-07-09T13:00:48-04:00",
    "updated_at": "2020-07-09T13:00:48-04:00",
    "currency": "USD",
    "initial_value": "25.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "3b53",
    "order_id": null,
    "code": "549948948c4a3b53"
  }
}
PUT /admin/api/2020-01/gift_cards/{gift_card_id}.json

Updates an existing gift card.

The gift card's balance can't be changed via the API. You can change only the expiry date, note, and template suffix.

Update the note of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "note": "Updating with a new note"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:51-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": "Updating with a new note",
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

Update the expiry date of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "expires_on": "2020-01-01"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:57-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": "2020-01-01",
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
POST /admin/api/2020-01/gift_cards/{gift_card_id}/disable.json
Disables a gift card. Disabling a gift card can't be undone.

Disable a gift card

POST /admin/api/2020-07/gift_cards/48394658/disable.json
{
  "gift_card": {
    "id": 48394658
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:01:02-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2020-07-09T13:01:02-04:00",
    "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
  }
}
GET /admin/api/2020-01/gift_cards/search.json?query=last_characters:mnop

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: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

order

The field and direction to order results by.

(default: disabled_at DESC)
query

The text to search for.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all gift cards with the last characters "mnop"

GET /admin/api/2020-07/gift_cards/search.json?query=last_characters:mnop
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 1063936319,
      "balance": "10.00",
      "created_at": "2020-07-09T13:01:44-04:00",
      "updated_at": "2020-07-09T13:01:44-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,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}
Version 2020-04

Shopify Plus

The Gift Card resource is available only for private apps installed on Shopify Plus stores.

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.

What you can do with Gift Card

The Shopify API lets you do the following with the Gift Card resource. More detailed versions of these general actions may be available:

Gift Card properties

api_client_id 
"api_client_id": 431223487

The ID of the app that issued the gift card, if it was issued by an app.
balance 
"balance": 80.17

The balance of the gift card.
code 
"code": "1234 4567 8901 2ABC"

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 
"created_at": "2008-12-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was created.
currency 
"currency": "CAD"

The currency of the gift card.
customer_id 
"customer_id": 368407052327

The ID of a customer who is associated with this gift card.
disabled_at 
"disabled_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was disabled.
expires_on 
"expires_on": "2020-01-31"

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": 989034056

The ID of the gift card.
initial_value 
"initial_value": 100.0

The initial value of the gift card when it was created.
last_characters 
"last_characters": "2ABC"

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 
"line_item_id": 241253183

The ID of the line item that caused the creation of this gift card, if it was created by an order.
note 
"note": "A note"

The text of an optional note that a merchant can attach to the gift card. Not visible to customers.
order_id 
"order_id": 241253183

The ID of the order that caused the creation of this gift card, if it was created by an order.
template_suffix 
"template_suffix": "birthday"

The suffix of the Liquid template that's used to render the gift card online. For example, if the value is birthday, then the gift card is rendered using the template gift_card.birthday.liquid. When the value is null, the default gift_card.liquid template is used.

user_id 
"user_id": 241253183

The ID of the user that issued the gift card, if it was issued by a user.
updated_at 
"updated_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was last modified.

Endpoints

GET /admin/api/2020-04/gift_cards.json
Retrieves a list of gift cards. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
status

Retrieve gift cards with a given status. Valid values:

  • enabled: Restrict results to only enabled gift cards
  • disabled: Restrict results to only disabled gift cards
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a list of all gift cards

GET /admin/api/2020-07/gift_cards.json
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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,
      "last_characters": "0y0y",
      "order_id": null
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}

Retrieve a list of all enabled gift cards

GET /admin/api/2020-07/gift_cards.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}
GET /admin/api/2020-04/gift_cards/{gift_card_id}.json
Retrieves a single gift card by its ID

Retrieve a single gift card

GET /admin/api/2020-07/gift_cards/48394658.json
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T12:56:27-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
  }
}
GET /admin/api/2020-04/gift_cards/count.json
Retrieves a count of gift cards
status

Count gift cards with a given status. Valid values:

  • enabled: Count only enabled gift cards
  • disabled: Count only disabled gift cards

Retrieve a count of all gift cards

GET /admin/api/2020-07/gift_cards/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of enabled gift cards

GET /admin/api/2020-07/gift_cards/count.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
POST /admin/api/2020-04/gift_cards.json
Creates a gift card

Create a gift card with a custom code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "note": "This is a note",
    "initial_value": 100.0,
    "code": "ABCD EFGH IJKL MNOP",
    "template_suffix": "gift_cards.birthday.liquid"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936316,
    "balance": "100.00",
    "created_at": "2020-07-09T13:00:42-04:00",
    "updated_at": "2020-07-09T13:00:42-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"
  }
}

Create a gift card with an automatically generated code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "initial_value": 25.0
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936317,
    "balance": "25.00",
    "created_at": "2020-07-09T13:00:48-04:00",
    "updated_at": "2020-07-09T13:00:48-04:00",
    "currency": "USD",
    "initial_value": "25.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "3b53",
    "order_id": null,
    "code": "549948948c4a3b53"
  }
}
PUT /admin/api/2020-04/gift_cards/{gift_card_id}.json

Updates an existing gift card.

The gift card's balance can't be changed via the API. You can change only the expiry date, note, and template suffix.

Update the note of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "note": "Updating with a new note"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:51-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": "Updating with a new note",
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

Update the expiry date of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "expires_on": "2020-01-01"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:57-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": "2020-01-01",
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
POST /admin/api/2020-04/gift_cards/{gift_card_id}/disable.json
Disables a gift card. Disabling a gift card can't be undone.

Disable a gift card

POST /admin/api/2020-07/gift_cards/48394658/disable.json
{
  "gift_card": {
    "id": 48394658
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:01:02-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2020-07-09T13:01:02-04:00",
    "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
  }
}
GET /admin/api/2020-04/gift_cards/search.json?query=last_characters:mnop

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: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

order

The field and direction to order results by.

(default: disabled_at DESC)
query

The text to search for.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all gift cards with the last characters "mnop"

GET /admin/api/2020-07/gift_cards/search.json?query=last_characters:mnop
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 1063936319,
      "balance": "10.00",
      "created_at": "2020-07-09T13:01:44-04:00",
      "updated_at": "2020-07-09T13:01:44-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,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}
Version 2020-07 (Latest)

Shopify Plus

The Gift Card resource is available only for private apps installed on Shopify Plus stores.

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.

What you can do with Gift Card

The Shopify API lets you do the following with the Gift Card resource. More detailed versions of these general actions may be available:

Gift Card properties

api_client_id 
"api_client_id": 431223487

The ID of the app that issued the gift card, if it was issued by an app.
balance 
"balance": 80.17

The balance of the gift card.
code 
"code": "1234 4567 8901 2ABC"

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 
"created_at": "2008-12-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was created.
currency 
"currency": "CAD"

The currency of the gift card.
customer_id 
"customer_id": 368407052327

The ID of a customer who is associated with this gift card.
disabled_at 
"disabled_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was disabled.
expires_on 
"expires_on": "2020-01-31"

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": 989034056

The ID of the gift card.
initial_value 
"initial_value": 100.0

The initial value of the gift card when it was created.
last_characters 
"last_characters": "2ABC"

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 
"line_item_id": 241253183

The ID of the line item that caused the creation of this gift card, if it was created by an order.
note 
"note": "A note"

The text of an optional note that a merchant can attach to the gift card. Not visible to customers.
order_id 
"order_id": 241253183

The ID of the order that caused the creation of this gift card, if it was created by an order.
template_suffix 
"template_suffix": "birthday"

The suffix of the Liquid template that's used to render the gift card online. For example, if the value is birthday, then the gift card is rendered using the template gift_card.birthday.liquid. When the value is null, the default gift_card.liquid template is used.

user_id 
"user_id": 241253183

The ID of the user that issued the gift card, if it was issued by a user.
updated_at 
"updated_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was last modified.

Endpoints

GET /admin/api/2020-07/gift_cards.json
Retrieves a list of gift cards. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
status

Retrieve gift cards with a given status. Valid values:

  • enabled: Restrict results to only enabled gift cards
  • disabled: Restrict results to only disabled gift cards
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a list of all gift cards

GET /admin/api/2020-07/gift_cards.json
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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,
      "last_characters": "0y0y",
      "order_id": null
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}

Retrieve a list of all enabled gift cards

GET /admin/api/2020-07/gift_cards.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}
GET /admin/api/2020-07/gift_cards/{gift_card_id}.json
Retrieves a single gift card by its ID

Retrieve a single gift card

GET /admin/api/2020-07/gift_cards/48394658.json
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T12:56:27-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
  }
}
GET /admin/api/2020-07/gift_cards/count.json
Retrieves a count of gift cards
status

Count gift cards with a given status. Valid values:

  • enabled: Count only enabled gift cards
  • disabled: Count only disabled gift cards

Retrieve a count of all gift cards

GET /admin/api/2020-07/gift_cards/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of enabled gift cards

GET /admin/api/2020-07/gift_cards/count.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
POST /admin/api/2020-07/gift_cards.json
Creates a gift card

Create a gift card with a custom code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "note": "This is a note",
    "initial_value": 100.0,
    "code": "ABCD EFGH IJKL MNOP",
    "template_suffix": "gift_cards.birthday.liquid"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936316,
    "balance": "100.00",
    "created_at": "2020-07-09T13:00:42-04:00",
    "updated_at": "2020-07-09T13:00:42-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"
  }
}

Create a gift card with an automatically generated code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "initial_value": 25.0
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936317,
    "balance": "25.00",
    "created_at": "2020-07-09T13:00:48-04:00",
    "updated_at": "2020-07-09T13:00:48-04:00",
    "currency": "USD",
    "initial_value": "25.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "3b53",
    "order_id": null,
    "code": "549948948c4a3b53"
  }
}
PUT /admin/api/2020-07/gift_cards/{gift_card_id}.json

Updates an existing gift card.

The gift card's balance can't be changed via the API. You can change only the expiry date, note, and template suffix.

Update the note of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "note": "Updating with a new note"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:51-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": "Updating with a new note",
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

Update the expiry date of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "expires_on": "2020-01-01"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:57-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": "2020-01-01",
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
POST /admin/api/2020-07/gift_cards/{gift_card_id}/disable.json
Disables a gift card. Disabling a gift card can't be undone.

Disable a gift card

POST /admin/api/2020-07/gift_cards/48394658/disable.json
{
  "gift_card": {
    "id": 48394658
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:01:02-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2020-07-09T13:01:02-04:00",
    "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
  }
}
GET /admin/api/2020-07/gift_cards/search.json?query=last_characters:mnop

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: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

order

The field and direction to order results by.

(default: disabled_at DESC)
query

The text to search for.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all gift cards with the last characters "mnop"

GET /admin/api/2020-07/gift_cards/search.json?query=last_characters:mnop
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 1063936319,
      "balance": "10.00",
      "created_at": "2020-07-09T13:01:44-04:00",
      "updated_at": "2020-07-09T13:01:44-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,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}
Version 2020-10 (Release candidate)

Shopify Plus

The Gift Card resource is available only for private apps installed on Shopify Plus stores.

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.

What you can do with Gift Card

The Shopify API lets you do the following with the Gift Card resource. More detailed versions of these general actions may be available:

Gift Card properties

api_client_id 
"api_client_id": 431223487

The ID of the app that issued the gift card, if it was issued by an app.
balance 
"balance": 80.17

The balance of the gift card.
code 
"code": "1234 4567 8901 2ABC"

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 
"created_at": "2008-12-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was created.
currency 
"currency": "CAD"

The currency of the gift card.
customer_id 
"customer_id": 368407052327

The ID of a customer who is associated with this gift card.
disabled_at 
"disabled_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was disabled.
expires_on 
"expires_on": "2020-01-31"

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": 989034056

The ID of the gift card.
initial_value 
"initial_value": 100.0

The initial value of the gift card when it was created.
last_characters 
"last_characters": "2ABC"

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 
"line_item_id": 241253183

The ID of the line item that caused the creation of this gift card, if it was created by an order.
note 
"note": "A note"

The text of an optional note that a merchant can attach to the gift card. Not visible to customers.
order_id 
"order_id": 241253183

The ID of the order that caused the creation of this gift card, if it was created by an order.
template_suffix 
"template_suffix": "birthday"

The suffix of the Liquid template that's used to render the gift card online. For example, if the value is birthday, then the gift card is rendered using the template gift_card.birthday.liquid. When the value is null, the default gift_card.liquid template is used.

user_id 
"user_id": 241253183

The ID of the user that issued the gift card, if it was issued by a user.
updated_at 
"updated_at": "2009-01-31T19:00:00-05:00"

The date and time (ISO 8601 format) when the gift card was last modified.

Endpoints

GET /admin/api/2020-10/gift_cards.json
Retrieves a list of gift cards. Note: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
status

Retrieve gift cards with a given status. Valid values:

  • enabled: Restrict results to only enabled gift cards
  • disabled: Restrict results to only disabled gift cards
limit

The maximum number of results to show.

(default: 50, maximum: 250)
since_id

Restrict results to after the specified ID.
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a list of all gift cards

GET /admin/api/2020-07/gift_cards.json
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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,
      "last_characters": "0y0y",
      "order_id": null
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}

Retrieve a list of all enabled gift cards

GET /admin/api/2020-07/gift_cards.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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": "2019-07-09",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2020-07-09T12:56:27-04:00",
      "updated_at": "2020-07-09T12:56:27-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
    }
  ]
}
GET /admin/api/2020-10/gift_cards/{gift_card_id}.json
Retrieves a single gift card by its ID

Retrieve a single gift card

GET /admin/api/2020-07/gift_cards/48394658.json
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T12:56:27-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
  }
}
GET /admin/api/2020-10/gift_cards/count.json
Retrieves a count of gift cards
status

Count gift cards with a given status. Valid values:

  • enabled: Count only enabled gift cards
  • disabled: Count only disabled gift cards

Retrieve a count of all gift cards

GET /admin/api/2020-07/gift_cards/count.json
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of enabled gift cards

GET /admin/api/2020-07/gift_cards/count.json?status=enabled
View Response 
HTTP/1.1 200 OK
{
  "count": 3
}
POST /admin/api/2020-10/gift_cards.json
Creates a gift card

Create a gift card with a custom code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "note": "This is a note",
    "initial_value": 100.0,
    "code": "ABCD EFGH IJKL MNOP",
    "template_suffix": "gift_cards.birthday.liquid"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936316,
    "balance": "100.00",
    "created_at": "2020-07-09T13:00:42-04:00",
    "updated_at": "2020-07-09T13:00:42-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"
  }
}

Create a gift card with an automatically generated code

POST /admin/api/2020-07/gift_cards.json
{
  "gift_card": {
    "initial_value": 25.0
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936317,
    "balance": "25.00",
    "created_at": "2020-07-09T13:00:48-04:00",
    "updated_at": "2020-07-09T13:00:48-04:00",
    "currency": "USD",
    "initial_value": "25.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": null,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "3b53",
    "order_id": null,
    "code": "549948948c4a3b53"
  }
}
PUT /admin/api/2020-10/gift_cards/{gift_card_id}.json

Updates an existing gift card.

The gift card's balance can't be changed via the API. You can change only the expiry date, note, and template suffix.

Update the note of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "note": "Updating with a new note"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:51-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": "Updating with a new note",
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}

Update the expiry date of a gift card

PUT /admin/api/2020-07/gift_cards/48394658.json
{
  "gift_card": {
    "id": 48394658,
    "expires_on": "2020-01-01"
  }
}
View Response 
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:00:57-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": "2020-01-01",
    "template_suffix": null,
    "last_characters": "0d0d",
    "order_id": null
  }
}
POST /admin/api/2020-10/gift_cards/{gift_card_id}/disable.json
Disables a gift card. Disabling a gift card can't be undone.

Disable a gift card

POST /admin/api/2020-07/gift_cards/48394658/disable.json
{
  "gift_card": {
    "id": 48394658
  }
}
View Response 
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2020-07-09T12:56:27-04:00",
    "updated_at": "2020-07-09T13:01:02-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2020-07-09T13:01:02-04:00",
    "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
  }
}
GET /admin/api/2020-10/gift_cards/search.json?query=last_characters:mnop

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: As of version 2019-10, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

order

The field and direction to order results by.

(default: disabled_at DESC)
query

The text to search for.
limit

The maximum number of results to retrieve.

(default: 50, maximum: 250)
fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve all gift cards with the last characters "mnop"

GET /admin/api/2020-07/gift_cards/search.json?query=last_characters:mnop
View Response 
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 1063936319,
      "balance": "10.00",
      "created_at": "2020-07-09T13:01:44-04:00",
      "updated_at": "2020-07-09T13:01:44-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,
      "last_characters": "mnop",
      "order_id": null
    }
  ]
}