Gift Card

Shopify Plus

The Gift Card resource is available to Shopify Plus merchants only.

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 a masked code or last 4 digits can be retrieved.

What can you 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).

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.

masked_code
{ "masked_code" : "•••• •••• •••• 2ABC" }

Because gift cards are alternate payment methods, the gift card code is masked the same way a credit card would be.

last_characters
{ "last_characters" : "2ABC" }

The last four characters of the gift card code.

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 gift cards

GET /admin/gift_cards.json
View Response
HTTP/1.1 200 OK
{
  "gift_cards": [
    {
      "id": 48394658,
      "balance": "100.00",
      "created_at": "2016-06-29T13:36:40-04:00",
      "updated_at": "2016-06-29T13:36:40-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": "2016-06-29T13:36:40-04:00",
      "updated_at": "2016-06-29T13:36:40-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": "2015-06-29",
      "template_suffix": null,
      "last_characters": "0e0e",
      "order_id": null
    },
    {
      "id": 283097216,
      "balance": "0.00",
      "created_at": "2016-06-29T13:36:40-04:00",
      "updated_at": "2016-06-29T13:36:40-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 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": "2016-06-29T13:36:40-04:00",
      "updated_at": "2016-06-29T13:36:40-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": "2016-06-29T13:36:40-04:00",
      "updated_at": "2016-06-29T13:36:40-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": "2015-06-29",
      "template_suffix": null,
      "last_characters": "0e0e",
      "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": "2016-06-29T13:36:40-04:00",
    "updated_at": "2016-06-29T13:36:40-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 all gift cards

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

Retrieve a count of enabled gift cards

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

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": 1063936317,
    "balance": "25.00",
    "created_at": "2016-06-29T13:38:13-04:00",
    "updated_at": "2016-06-29T13:38:13-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": "e94c",
    "order_id": null,
    "code": "3h3bb83aadb6e94c"
  }
}

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": 1063936318,
    "balance": "100.00",
    "created_at": "2016-06-29T13:38:14-04:00",
    "updated_at": "2016-06-29T13:38:14-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"
  }
}
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 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": "2016-06-29T13:36:40-04:00",
    "updated_at": "2016-06-29T13:38: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": "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/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": "2016-06-29T13:36:40-04:00",
    "updated_at": "2016-06-29T13:38: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": null,
    "expires_on": "2020-01-01",
    "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": "2016-06-29T13:36:40-04:00",
    "updated_at": "2016-06-29T13:38:12-04:00",
    "currency": "USD",
    "initial_value": "100.00",
    "disabled_at": "2016-06-29T13:38:12-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
  }
}