Choose a version:

giftCard

query

Requires read_gift_cards access scope.

Retrieves a GiftCard by its ID. Returns the gift card's balance, transaction history, Customer information, and whether it's enabled.

Additional fields include the initial value, expiration date, deactivation timestamp (if applicable), and the associated Order if the gift card was purchased by a customer through checkout. Gift cards that merchants create manually won't have an associated order.

Anchor to Arguments

Arguments

Anchor to idid •ID! required: The ID of the GiftCard to return.

Was this section helpful?

Anchor to Possible returnsPossible returns

Anchor to GiftCardGiftCard

•GiftCard

A gift card that customers use as a payment method. Stores the initial value, current balance, and expiration date.

You can issue gift cards to a specific Customer or send them to a GiftCardRecipient with a personalized message. The card tracks its transaction history through GiftCardCreditTransaction and GiftCardDebitTransaction records. You can create and deactivate gift cards using the GiftCardCreate and GiftCardDeactivate mutations, respectively.

Note

After a gift card is deactivated, it can't be used for further purchases or re-enabled.

Anchor to balancebalance

•MoneyV2!

non-null

The gift card's remaining balance.

Anchor to createdAtcreatedAt

•DateTime!

non-null

The date and time at which the gift card was created.

Anchor to customercustomer

•Customer

The customer who will receive the gift card.

Anchor to deactivatedAtdeactivatedAt

•DateTime

The date and time at which the gift card was deactivated.

Anchor to enabledenabled

•Boolean!

non-null

Whether the gift card is enabled.

Anchor to expiresOnexpiresOn

•Date

The date at which the gift card will expire.

Anchor to idid

•ID!

non-null

A globally-unique ID.

Anchor to initialValueinitialValue

•MoneyV2!

non-null

The initial value of the gift card.

Anchor to lastCharacterslastCharacters

•String!

non-null

The final four characters of the gift card code.

Anchor to maskedCodemaskedCode

•String!

non-null

The gift card code. Everything but the final four characters is masked.

Anchor to notenote

•String

The note associated with the gift card, which isn't visible to the customer.

Anchor to orderorder

•Order

The order associated with the gift card. This value is null if the gift card was issued manually.

Anchor to recipientAttributesrecipientAttributes

•GiftCardRecipient

The recipient who will receive the gift card.

Anchor to templateSuffixtemplateSuffix

•String

The theme template used to render the gift card online.

Anchor to transactionstransactions

•GiftCardTransactionConnection

The transaction history of the gift card.

Anchor to firstfirst •Int: The first n elements from the paginated list.
Anchor to afterafter •String: The elements that come after the specified cursor.
Anchor to lastlast •Int: The last n elements from the paginated list.
Anchor to beforebefore •String: The elements that come before the specified cursor.
Anchor to reversereverse •Boolean Default:false: Reverse the order of the underlying list.

Anchor to updatedAtupdatedAt

•DateTime!

non-null

The date and time at which the gift card was updated.

Was this section helpful?

Examples

Receive a list of all Gift Card Adjustments

Query

query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {
  giftCard(id: $id) {
    id
    balance {
      amount
      currencyCode
    }
    transactions(first: $firstTransactions) {
      nodes {
        amount {
          amount
          currencyCode
        }
      }
    }
  }
}

Variables

{
  "id": "gid://shopify/GiftCard/411106674",
  "firstTransactions": 5
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query GiftCardTransactionList($id: ID!, $firstTransactions: Int) { giftCard(id: $id) { id balance { amount currencyCode } transactions(first: $firstTransactions) { nodes { amount { amount currencyCode } } } } }",
 "variables": {
    "id": "gid://shopify/GiftCard/411106674",
    "firstTransactions": 5
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {
    giftCard(id: $id) {
      id
      balance {
        amount
        currencyCode
      }
      transactions(first: $firstTransactions) {
        nodes {
          amount {
            amount
            currencyCode
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/GiftCard/411106674",
        "firstTransactions": 5
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {
    giftCard(id: $id) {
      id
      balance {
        amount
        currencyCode
      }
      transactions(first: $firstTransactions) {
        nodes {
          amount {
            amount
            currencyCode
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/GiftCard/411106674",
  "firstTransactions": 5
}

response = client.query(query: query, variables: variables)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {
      giftCard(id: $id) {
        id
        balance {
          amount
          currencyCode
        }
        transactions(first: $firstTransactions) {
          nodes {
            amount {
              amount
              currencyCode
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/GiftCard/411106674",
        "firstTransactions": 5
    },
  },
});

Response

{
  "giftCard": {
    "id": "gid://shopify/GiftCard/411106674",
    "balance": {
      "amount": "25.0",
      "currencyCode": "USD"
    },
    "transactions": {
      "nodes": []
    }
  }
}

Retrieves a single gift card

Description

The following query takes a gift card ID, and returns the balance of the gift card.

Query

query {
  giftCard(id: "gid://shopify/GiftCard/411106674") {
    balance {
      amount
      currencyCode
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query { giftCard(id: \"gid://shopify/GiftCard/411106674\") { balance { amount currencyCode } } }"
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query {
    giftCard(id: "gid://shopify/GiftCard/411106674") {
      balance {
        amount
        currencyCode
      }
    }
  }`,
  );
  const json = await response.json();
  return json.data;
}

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query {
    giftCard(id: "gid://shopify/GiftCard/411106674") {
      balance {
        amount
        currencyCode
      }
    }
  }
QUERY

response = client.query(query: query)

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: `query {
    giftCard(id: "gid://shopify/GiftCard/411106674") {
      balance {
        amount
        currencyCode
      }
    }
  }`,
});

Response

{
  "giftCard": {
    "balance": {
      "amount": "25.0",
      "currencyCode": "USD"
    }
  }
}

Examples

Open in GraphiQL

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {

const { admin } = await authenticate.admin(request);

const response = await admin.graphql(

`#graphql

query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {

giftCard(id: $id) {

balance {

amount

currencyCode

}

transactions(first: $firstTransactions) {

nodes {

amount {

amount

currencyCode

}

}`,

{

variables: {

"id": "gid://shopify/GiftCard/411106674",

"firstTransactions": 5

);

const json = await response.json();

return json.data;

}

GQL

query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {
  giftCard(id: $id) {
    id
    balance {
      amount
      currencyCode
    }
    transactions(first: $firstTransactions) {
      nodes {
        amount {
          amount
          currencyCode
        }
      }
    }
  }
}

cURL

curl -X POST \
https://your-development-store.myshopify.com/admin/api/2025-10/graphql.json \
-H 'Content-Type: application/json' \
-H 'X-Shopify-Access-Token: {access_token}' \
-d '{
"query": "query GiftCardTransactionList($id: ID!, $firstTransactions: Int) { giftCard(id: $id) { id balance { amount currencyCode } transactions(first: $firstTransactions) { nodes { amount { amount currencyCode } } } } }",
 "variables": {
    "id": "gid://shopify/GiftCard/411106674",
    "firstTransactions": 5
  }
}'

React Router

import { authenticate } from "../shopify.server";

export const loader = async ({request}) => {
  const { admin } = await authenticate.admin(request);
  const response = await admin.graphql(
    `#graphql
  query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {
    giftCard(id: $id) {
      id
      balance {
        amount
        currencyCode
      }
      transactions(first: $firstTransactions) {
        nodes {
          amount {
            amount
            currencyCode
          }
        }
      }
    }
  }`,
  {
    variables: {
        "id": "gid://shopify/GiftCard/411106674",
        "firstTransactions": 5
    },
  },
  );
  const json = await response.json();
  return json.data;
}

Node.js

const client = new shopify.clients.Graphql({session});
const data = await client.query({
  data: {
    "query": `query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {
      giftCard(id: $id) {
        id
        balance {
          amount
          currencyCode
        }
        transactions(first: $firstTransactions) {
          nodes {
            amount {
              amount
              currencyCode
            }
          }
        }
      }
    }`,
    "variables": {
        "id": "gid://shopify/GiftCard/411106674",
        "firstTransactions": 5
    },
  },
});

Ruby

session = ShopifyAPI::Auth::Session.new(
  shop: "your-development-store.myshopify.com",
  access_token: access_token
)
client = ShopifyAPI::Clients::Graphql::Admin.new(
  session: session
)

query = <<~QUERY
  query GiftCardTransactionList($id: ID!, $firstTransactions: Int) {
    giftCard(id: $id) {
      id
      balance {
        amount
        currencyCode
      }
      transactions(first: $firstTransactions) {
        nodes {
          amount {
            amount
            currencyCode
          }
        }
      }
    }
  }
QUERY

variables = {
  "id": "gid://shopify/GiftCard/411106674",
  "firstTransactions": 5
}

response = client.query(query: query, variables: variables)

Input variables

JSON

{

"id": "gid://shopify/GiftCard/411106674",

"firstTransactions": 5

}

Response

JSON

{

"giftCard": {

"id": "gid://shopify/GiftCard/411106674",

"balance": {

"amount": "25.0",

"currencyCode": "USD"

"transactions": {

"nodes": []

}