Gift Card

Shopify Plus

The Gift Card resource is available to Shopify Plus merchants only. Contact your Merchant Success Manger to enable this API resource for your store.

A gift card is a an alternative payment method, and has a code which is entered during checkout. It has a balance which can be redeemed over multiple checkouts, and can be assigned to a specific customer (optional). Gift card codes cannot be retrieved once created – only the last four digits can be retrieved.

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

id
"id": 989034056

A unique numeric identifier for the gift card.

api_client_id
"api_client_id": 431223487

A unique numeric identifier of the application that issued the gift card (if it was issued by an application).

user_id
"user_id": 241253183

A unique numeric identifier of the user that issued the gift card (if it was issued by a user).

order_id
"order_id": 241253183

A unique numeric identifier of the order that caused the creation of this gift card (if it was created by an order).

customer_id
"customer_id": 1234

The id of a customer who is associated with this gift card.

line_item_id
"line_item_id": 241253183

A unique numeric identifier of the line_item that caused the creation of this gift card (if it was created by an order).

balance
"balance": 80.17

The balance of the gift card.

currency
"currency": "CAD"

The currency of the gift card.

code
"code": "1234 4567 8901 2ABC"

The gift card code which consists of a minimum of 8 alphanumeric characters. For security reasons, this is only available upon creation of the gift card.

last_characters
"last_characters": "2ABC"

The last four characters of the gift card code. Because gift cards are alternate payment methods, the full code cannot be retrieved.

note
"note": "A friendly note"

The text of an optional note that a shop owner can attach to the gift card. Not visible to merchants.

template_suffix
"template_suffix": "gift_cards.birthday.liquid"

When specified, the gift card will be rendered using gift_card.SUFFIX.liquid instead of gift_card.liquid.

created_at
"created_at": "2008-12-31T19:00:00-05:00"

The date and time when the gift card was created. The API returns this value in ISO 8601 format.

updated_at
"updated_at": "2009-01-31T19:00:00-05:00"

The date and time when the gift card was last modified. The API returns this value in ISO 8601 format.

disabled_at
"disabled_at": "2009-01-31T19:00:00-05:00"

The date and time when the gift card was disabled. The API returns this value in ISO 8601 format.

expires_on
"expires_on": "2020-01-31"

The date and time when the gift card expires. The format must be YYYY-MM-DD.

Endpoints

GET /admin/gift_cards.json
Retrieve all gift cards of a shop
status
  • enabled - Restrict results to only enabled gift cards
  • disabled - Restrict results to only disabled gift cards
limit

Amount of results

(default: 50) (maximum: 250)
page

Page to show

(default: 1)
fields

comma-separated list of fields to include in the response

Get a list of all enabled gift cards

GET /admin/gift_cards.json?status=enabled
View Response
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2017-08-17T14:03:05-04:00",
      "updated_at": "2017-08-17T14:03:05-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
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2017-08-17T14:03:05-04:00",
      "updated_at": "2017-08-17T14:03:05-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": "2016-08-17",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    }
  ]
}

Get a list of all gift cards

GET /admin/gift_cards.json
View Response
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2017-08-17T14:03:05-04:00",
      "updated_at": "2017-08-17T14:03:05-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
    },
    {
      "id": 227709309,
      "balance": "25.00",
      "created_at": "2017-08-17T14:03:05-04:00",
      "updated_at": "2017-08-17T14:03:05-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": "2016-08-17",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2017-08-17T14:03:05-04:00",
      "updated_at": "2017-08-17T14:03:05-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
    }
  ]
}
GET /admin/gift_cards/48394658.json

Show a specific gift card's details

GET /admin/gift_cards/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2017-08-17T14:03:05-04:00",
    "updated_at": "2017-08-17T14:03:05-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/gift_cards/count.json
status
  • enabled - Count only enabled gift cards
  • disabled - Count only disabled gift cards

Retrieve a count of enabled gift cards

GET /admin/gift_cards/count.json?status=enabled
View Response
HTTP/1.1 200 OK
{
  "count": 3
}

Retrieve a count of all gift cards

GET /admin/gift_cards/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 3
}
POST /admin/gift_cards.json

Create a new gift card with a custom code

POST /admin/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": 1063936329,
    "balance": "100.00",
    "created_at": "2017-08-17T14:43:11-04:00",
    "updated_at": "2017-08-17T14:43:11-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": 0,
    "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 new gift card with an automatically generated code

POST /admin/gift_cards.json
{
  "gift_card": {
    "initial_value": 25.0
  }
}
View Response
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 1063936330,
    "balance": "25.00",
    "created_at": "2017-08-17T14:43:14-04:00",
    "updated_at": "2017-08-17T14:43:14-04:00",
    "currency": "USD",
    "initial_value": "25.00",
    "disabled_at": null,
    "line_item_id": null,
    "api_client_id": 755357713,
    "user_id": 0,
    "customer_id": null,
    "note": null,
    "expires_on": null,
    "template_suffix": null,
    "last_characters": "642c",
    "order_id": null,
    "code": "bahb47d39dg4642c"
  }
}
PUT /admin/gift_cards/48394658.json
The gift card's balance cannot be changed by this API. You can change the expiry date, note, and template prefix.

Update the expiry date of a gift card

PUT /admin/gift_cards/#{id}.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": "2017-08-17T14:03:05-04:00",
    "updated_at": "2017-08-17T14:43:12-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
  }
}

Update the note of a gift card

PUT /admin/gift_cards/#{id}.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": "2017-08-17T14:03:05-04:00",
    "updated_at": "2017-08-17T14:43:13-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
  }
}
POST /admin/gift_cards/48394658/disable.json

Disable a gift card

POST /admin/gift_cards/#{id}/disable.json
{
  "gift_card": {
    "id": 48394658
  }
}
View Response
HTTP/1.1 201 Created
{
  "gift_card": {
    "id": 48394658,
    "balance": "100.00",
    "created_at": "2017-08-17T14:03:05-04:00",
    "updated_at": "2017-08-17T14:43:00-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2017-08-17T14:43:00-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
  }
}