Gift cards are products that merchants can sell through their stores. Customers use gift cards as a payment method to make purchases. This tutorial shows you how to create, retrieve, update, and disable gift cards for a store using the GraphQL Admin API.

How gift cards work

A gift card is a special type of product and an alternative payment method. Its value can be used as payment toward future orders from an online store.

Each gift card has a unique code that is entered during checkout. Its balance can be redeemed over multiple checkouts. Optionally, a gift card code can be assigned to a specific customer.

After a gift card is created, the gift card code can't be updated. Only the customer, expiry date, note, and template suffix can be updated. The gift card code can't be retrieved after it's created — only the last four characters can be retrieved.

Requirements

• Your app must be either private or custom and installed on a Shopify Plus store.
• You've completed our Getting started with the GraphQL Admin and REST Admin APIs guide and you're authenticated with the API.
• You've activated the gift card feature in the Shopify admin of your store.

Scopes

To use the GraphQL queries and mutations, your app needs to request the following access scopes for a Shopify store:

• read_gift_cards: Allows an app to read gift cards.
• write_gift_cards: Allows an app to write gift cards.

Create a gift card

To create a new gift card, run the giftCardCreate mutation. The returned fields include the ID of the gift card (id), the redacted gift card code (maskedCode), the timestamp of when the gift card was created (createdAt), and the full gift card code (giftCardCode). In the following example, the initial value of the gift card is supplied as an input variable.

Example request

POST /admin/api/2021-04/graphql.json

mutation giftCardCreate($input: GiftCardCreateInput!) {
  giftCardCreate(input: $input){
    giftCard{
      id
      maskedCode
      createdAt      
    }
    giftCardCode
    userErrors{
      code
      field
    }
  }
}

## Input variables

{
  "input": {
    "initialValue" : 100
  }
}

View response

{
  "data": {
    "giftCardCreate": {
      "giftCard": {
        "id": "gid://shopify/GiftCard/1234",
        "maskedCode": "•••• •••• •••• be55",
        "createdAt": "2021-03-03T21:23:17Z"
      },
      "giftCardCode": "123445678901be55",
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 10
    }
  }
}

Retrieve gift cards

To retrieve existing gift cards, you can query giftCards on the QueryRoot. In the following example, the response body returns the first five gift cards and their corresponding IDs.

Example request

POST /admin/api/2021-04/graphql.json

query {
  giftCards(first: 5) {
    edges {
      node {
        id
      }
    }
  }
}

View response

{
  "data": {
    "giftCards": {
      "edges": [
        {
          "node": {
            "id": "gid://shopify/GiftCard/1234"
          }
        },
        {
          "node": {
            "id": "gid://shopify/GiftCard/2345"
          }
        },
        {
          "node": {
            "id": "gid://shopify/GiftCard/3456"
          }
        },
        {
          "node": {
            "id": "gid://shopify/GiftCard/4567"
          }
        },
        {
          "node": {
            "id": "gid://shopify/GiftCard/5678"
          }
        },
      ]
    }
  },
}

Update a gift card

To update a gift card, you can run the giftCardUpdate mutation. For example, if you want to update a gift card's expiration date, you can supply the gift card ID (id) and new expiration date (expiresOn) as input variables in the mutation. In the following example, the gift card's expiration date is updated to December 26, 2025.

Example request

POST /admin/api/2021-04/graphql.json

mutation giftCardUpdate($id: ID!, $input: GiftCardUpdateInput!) {
  giftCardUpdate(id: $id, input: $input){
    giftCard{
      id
      maskedCode
      createdAt  
      expiresOn
    }
    userErrors{
      field
    }
  }
}

## Input variables

{
  "id": "gid://shopify/GiftCard/1234",
  "input": {
    "expiresOn": "2025-12-26"
  }
}

View response

{
  "data": {
    "giftCardUpdate": {
      "giftCard": {
        "id": "gid://shopify/GiftCard/1234",
        "maskedCode": "•••• •••• •••• be55",
        "createdAt": "2021-03-03T21:23:17Z",
        "expiresOn": "2025-12-26"
      },
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 10
    }
  }
}

Disable a gift card

To disable a gift card, run the giftCardDisable mutation and supply the ID of the gift card that you want to disable. After you disable a gift card, the merchant can't sell the gift card in their store and customers can't use the gift card to make purchases.

Example request

POST /admin/api/2021-04/graphql.json

mutation giftCardDisable($id: ID!) {
  giftCardDisable(id: $id){
    giftCard{
      id
      maskedCode
      createdAt  
      expiresOn
    }
    userErrors{
      field
    }
  }
}

## Input variables

{
  "id": "gid://shopify/GiftCard/1234"
}

View response

{
  "data": {
    "giftCardDisable": {
      "giftCard": {
        "id": "gid://shopify/GiftCard/1234",
        "maskedCode": "•••• •••• •••• be55",
        "createdAt": "2021-03-03T21:23:17Z",
        "expiresOn": "2025-12-26"
      },
      "userErrors": []
    }
  },
  "extensions": {
    "cost": {
      "requestedQueryCost": 10,
      "actualQueryCost": 10
    }
  }
}

Next steps

• Get answers to frequently asked questions about gift cards.
• Learn how to personalize gift cards using custom images.
• Get familiar with using statuses to identify, filter, and manage products, such as gift cards.