Retrieve Square Gift Cards and Track Activity

Developers can use the Gift Cards API and Gift Card Activities API to get details about a gift card, view all gift cards for a seller account, track activity history, and get details about a particular activity.

Square provides the following endpoints to retrieve gift cards and activities:

• RetrieveGiftCard - Retrieves a gift card using the gift card ID.
• RetrieveGiftCardFromGAN - Retrieves a gift card using the gift card number (GAN).
• RetrieveGiftCardFromNonce - Retrieves a gift cards using a payment token generated for the gift card by the Web Payments SDK or In-App Payments SDK.
• ListGiftCards - Lists the gift cards in a seller account. You can use query parameters to filter the results. For example, use customer_id to list the gift cards on file for a customer.
• ListGiftCardActivities - Lists activities for the gift cards in a seller account. You can use query parameters to filter the results. For example, use the gift_card_id query parameter to list the gift cards on file for a customer. Activities are actions that change the gift card balance or state.

To get details about a particular gift card, such as the balance, ID, GAN, state, or GAN source, you can retrieve a gift card using:

• The gift card ID.
• The gift card GAN.
• A payment token generated for the gift card by the Web Payments SDK or In-App Payments SDK.

To retrieve a gift card using its ID, call RetrieveGiftCard and provide the ID as a path parameter.

To retrieve a gift card using its GAN, call RetrieveGiftCardFromGAN and provide the GAN in the request body.

To retrieve a gift card using a payment token, call RetrieveGiftCardFromNonce and provide the payment token in the request body.

When using the Web Payments SDK to take online payments or the In-App Payments SDK to take in-app payments, the SDK generates a secure payment token from the GAN entered by the buyer. Payment tokens are used to represent a payment source in a CreatePayment request.

The RetrieveGiftCard, RetrieveGiftCardFromGAN, and RetrieveGiftCardFromNonce endpoints return a gift card in the response, as shown in the following example:

{
  "gift_card": {
    "id": "gftc:012440e514754c42990f3de45EXAMPLE",
    "type": "DIGITAL",
    "gan_source": "SQUARE",
    "state": "ACTIVE",
    "balance_money": {
      "amount": 3014,
      "currency": "USD"
    },
    "customer_ids": [
      "ASG67K1YGCSQQ47KSW7EXAMPLE", 
      "QNTC0TYTWMRSFFQ157KEXAMPLE"
    ],
    "gan": "7783320002000000",
    "created_at": "2021-04-11T18:49:34Z"
  }
}

If the gift card is linked to at least one customer, the customer_ids field is present and lists the IDs of all linked customers. For more information, see Manage Square Gift Cards on File.

To list the gift cards in a seller account, call ListGiftCards. You can optionally filter the request using the following query parameters:

• type - Returns only the gift cards of the specified type, either DIGITAL or PHYSICAL.
• state - Returns only the gift cards with the specified status, such as ACTIVE or PENDING.
• customer_id - Returns only the gift cards that are linked with the specified customer. If you need to get the customer ID, you can search customer profiles by phone number, email address, or other supported attribute.

The following request uses the type query parameter to filter for DIGITAL gift cards and the limit query parameter to specify a maximum page size of three results. The default page size is 30 and the maximum is 200.

Results are sorted by created_at in ascending order (oldest to newest). The following is an example response for the previous request:

{
  "gift_cards": [
    {
      "id": "gftc:06c30c2b9772458a9e87b2880EXAMPLE",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "ACTIVE",
      "balance_money": {
        "amount": 7941,
        "currency": "USD"
      },
      "gan": "7783320004000000",
      "created_at": "2021-08-10T22:08:00Z",
      "customer_ids": [
        "B4KYKTP8ARW6HDVEB54EXAMPLE"
      ]
    },
    {
      "id": "gftc:080fc3433b294b549213aa013EXAMPLE",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "ACTIVE",
      "balance_money": {
        "amount": 1500,
        "currency": "USD"
      },
      "gan": "7783320002000000",
      "created_at": "2021-08-26T15:39:40Z",
      "customer_ids": [
        "9P8R65HHRRRJBE1SAGREXAMPLE"
      ]
    },
    {
      "id": "gftc:065fd3c6e1014c9293bd2d094EXAMPLE",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "PENDING",
      "balance_money": {
        "amount": 0,
        "currency": "USD"
      },
      "gan": "7783320009000000",
      "created_at": "2021-09-05T08:36:45Z",
    }
  ],
  "cursor": "ZPNEhVUKHBuTOuRIZoUcX5VQEXAMPLE"
}

If the response is paged, the response includes a cursor field. To retrieve the next page of results, include the cursor query parameter in the next ListGiftCards call, as shown in the following example:

If no matching gift cards are found, the response contains an empty object:

{}

Activities represent actions that change the balance or state of a gift card. A gift card activity can be initiated by:

• Sellers and buyers using a Square product. For example, sellers can reload a gift card using Square Point of Sale and buyers can reload a gift card from their Square profile.
• Third-party applications calling CreateGiftCardActivity directly, creating a gift card payment using the Payments API or refunding a gift card payment using the Refunds API.
• Square, which manages some activity types such as BLOCK and IMPORT.

To see the activity history for gift cards in a seller account, call ListGiftCardActivities. You can optionally filter the request using the following query parameters:

• gift_card_id - Returns only the activities for the specified gift card. Square supports several methods to get the gift card ID if needed.
• type - Returns only the activities of the specified type, such as ACTIVATE or REDEEM.
• location_id - Returns only the activities that occurred at the specified location. If needed, call ListLocations to get a location ID.
• begin_time and end_time - Returns only the activities that occurred in the specified range (inclusive). The begin_time timestamp defaults to one year prior to the current time and the end_time timestamp defaults to the current time.

The following request uses the gift_card_id query parameter to return activities for a particular gift card and the limit query parameter to specify a maximum page size of three results. The default page size is 50 and the maximum is 100.

By default, results are sorted by created_at in descending order (newest to oldest), but you can change to ascending order using the sort_order query parameter. The following is an example response for the previous request:

{
  "gift_card_activities": [
    {
      "id": "gcact_443f8c39a573478cbacfe1d4aEXAMPLE",
      "type": "REFUND",
      "location_id": "LNCXKAEXAMPLE",
      "created_at": "2023-07-28T23:06:01.000Z",
      "gift_card_id": "gftc:065fd3c6e1014c9293bd2d094EXAMPLE",
      "gift_card_gan": "7783320009000000",
      "gift_card_balance_money": {
        "amount": 7950,
        "currency": "USD"
      },
      "refund_activity_details": {
        "redeem_activity_id": "gcact_0b0ae7483d8a4d73a5f7eafd5EXAMPLE",
        "amount_money": {
          "amount": 2250,
          "currency": "USD"
        },
        "payment_id": "dywT8pGJR17ucj22F6JcP0EXAMPLE"
      }
    },
    {
      "id": "gcact_0b0ae7483d8a4d73a5f7eafd5EXAMPLE",
      "type": "REDEEM",
      "location_id": "LNCXKAEXAMPLE",
      "created_at": "2023-07-28T20:16:52.000Z",
      "gift_card_id": "gftc:065fd3c6e1014c9293bd2d094EXAMPLE",
      "gift_card_gan": "7783320009000000",
      "gift_card_balance_money": {
        "amount": 5600,
        "currency": "USD"
      },
      "redeem_activity_details": {
        "amount_money": {
          "amount": 2250,
          "currency": "USD"
        },
        "payment_id": "dywT8pGJR17ucj22F6JcP0EXAMPLE",
        "status": "COMPLETED"
      }
    },
    {
      "id": "gcact_f35eae6f5e5b4f63b2b087febEXAMPLE",
      "type": "REDEEM",
      "location_id": "SBZLMYEXAMPLE",
      "created_at": "2023-06-02T12:10:38.000Z",
      "gift_card_id": "gftc:065fd3c6e1014c9293bd2d094EXAMPLE",
      "gift_card_gan": "7783320009000000",
      "gift_card_balance_money": {
        "amount": 7950,
        "currency": "USD"
      },
      "redeem_activity_details": {
        "amount_money": {
          "amount": 1899,
          "currency": "USD"
        },
        "payment_id": "brHEqXns75QWKIxDVai4pCEXAMPLE",
        "status": "COMPLETED"
      }
    }
  ],
  "cursor": "4sEObMa2hctgwXECz0sQREXAMPLE"
}

If the response is paged, the response includes a cursor field. To retrieve the next page of results, include the cursor query parameter in the next ListGiftCardActivities call, as shown in the following example:

If no matching activities are found, the response contains an empty object:

{}

To find the balance of a gift card, retrieve the gift card and check the balance_money field. You can retrieve a gift card using:

• The gift card ID.
• The gift card GAN.
• A payment token generated for the gift card by the Web Payments SDK or In-App Payments SDK.

A gift card's balance is represented by the balance_money field. The amount field is the monetary amount in the lowest denomination of the currency. The following gift card has a balance of $22.21 USD:

{
  "gift_card": {
    "id": "gftc:01696eaf3d5141bfb4c786949EXAMPLE",
    "type": "DIGITAL",
    "gan_source": "SQUARE",
    "state": "ACTIVE",
    "balance_money": {
      "amount": 2221,
      "currency": "USD"
    },
    "gan": "7783320005000000",
    "created_at": "2023-04-01T18:49:34Z"
  }
}

A gift card balance can be zero or higher, up to the maximum allowed amount. A gift card balance cannot be negative.

Some operations require a gift card ID, such as linking and unlinking customers with gift cards, listing activities for a specified gift card, and providing a gift card ID as a payment source. Depending on your use case and the information you have, there are several ways to get a gift card ID:

• If you collect the GAN from the buyer, call RetrieveGiftCardFromGAN. Note that CreateGiftCardActivity requests accept either a gift card ID or GAN.
• If you use the Web Payments SDK to take online payments or the In-App Payments SDK to take in-app payments, call RetrieveGiftCardFromNonce and provide the payment token generated by the SDK for the gift card payment.
• If you just created or registered the gift card, check the ID from the corresponding CreateGiftCard or CreateGiftCardActivity response.
• If the gift card is linked to a customer, call ListGiftCards with the customer_id query parameter to get the customer's gift cards on file. Otherwise, you can try filtering the request or parsing the response to find the target gift card.
• If you have a payment (or an order tender) made using the gift card, call ListGiftCardActivities and filter by the timestamp of the payment. This method might return better results than calling ListGiftCards, as described in the following section.

When you need to retrieve a gift card but don't have the gift card ID, GAN, or payment token, you can call ListGiftCardActivities to find the ID. Depending on the information you have, this method might provide more conclusive results than calling ListGiftCards.

For example, suppose you have an order and you want to retrieve the gift card that was used for the payment. You can call ListGiftCardActivities and filter using information from the order, such as the created_at timestamp of the corresponding tender.

The following is an excerpt of an order that has one tender, which corresponds to the payment for the order. Note that tenders and payments don't include the gift card ID or full GAN.

{
  "id": "eYzvKpbrkqcK7Np6hgGOEXAMPLE",
  "location_id": "LNCXKAEXAMPLE",
  ...
  "tenders": [
    {
      "id": "xCJGyy4N4DcINY6EakKm4JEXAMPLE",
      "location_id": "LNCXKAEXAMPLE",
      "transaction_id": "eYzvKpbrkqcK7Np6hgGOEXAMPLE",
      "created_at": "2022-10-19T20:42:26Z",
      "amount_money": {
        "amount": 1500,
        "currency": "USD"
      },
      "type": "SQUARE_GIFT_CARD",
      "card_details": {
        "status": "CAPTURED",
        "card": {
          "card_brand": "SQUARE_GIFT_CARD",
          "last_4": "3922",
          "fingerprint": "sq-1-y_yFcziMlsxVSomRNQZ7xBaW0F1xxE-6TbcGKl7KOoy3GI1mh094CY4_Ox5EXAMPLE"
       },
       "entry_method": "KEYED"
     },
     "payment_id": "xCJGyy4N4DcINY6EakKm4JEXAMPLE"
    }
  ],
  ...
}

When you call ListGiftCardActivities, you can use information from the order as query parameters. The following example request includes:

• type set to REDEEM because paying with a gift card creates a REDEEM activity.
• location_id set to the location of the corresponding tender.
• begin_time and end_time set based on the created_at timestamp of the corresponding tender.

The following example response contains two activities. To confirm that you find the specific activity, compare the payment_id and the last four characters of gift_card_gan in the activity to id and last_4 of the corresponding tender.

{
  "gift_card_activities": [
    {
      "id": "gcact_728713fd9d034195811d58a30EXAMPLE",
      "type": "REDEEM",
      "location_id": "LNCXKAEXAMPLE",
      "created_at": "2022-10-19TT20:42:25.000Z",
      "gift_card_id": "gftc:1afce56ce3b74b9c92b2b1ad4EXAMPLE",
      "gift_card_gan": "7783320005003922",
      "gift_card_balance_money": {
        "amount": 1765,
        "currency": "USD"
      },
      "redeem_activity_details": {
        "amount_money": {
          "amount": 1500,
          "currency": "USD"
        },
        "payment_id": "xCJGyy4N4DcINY6EakKm4JEXAMPLE",
        "status": "COMPLETED"
      }
    },
    {
      "id": "gcact_2f7000463bdc45fd899439d62EXAMPLE",
      "type": "REDEEM",
      "location_id": "LNCXKAEXAMPLE",
      "created_at": "2022-10-19TT20:44:57.000Z",
      "gift_card_id": "gftc:065fd3c6e1014c9293bd2d094EXAMPLE",
      "gift_card_gan": "7783320009003257",
      "gift_card_balance_money": {
        "amount": 13506,
        "currency": "USD"
      },
      "redeem_activity_details": {
        "amount_money": {
          "amount": 2873,
          "currency": "USD"
        },
        "payment_id": "vFR58dqbNIIOV2gDXRCngsEXAMPLE",
        "status": "COMPLETED"
      }
    }
  ]
}

If you need additional gift card details, you can call RetrieveGiftCard using the gift_card_id.

The Reports section in the Seller Dashboard includes the following gift card related reports:

• Sales Summary report - Shows a summary of all activities that occurred using the Point of Sale application, Seller Dashboard, and transactions made using the Orders API and Payments API. This report includes a section for gift card sales, but doesn't include redemptions.
• Gift Cards report - Shows gift card specific activities.

When your application uses the Orders API and Payments API, these reports are Square-backed and accurately reflect the activities. For example:

• When you redeem a gift card using the Payments API, Square automatically creates the corresponding REDEEM gift card activity.
• When you activate a gift card and provide the ID of a Square order, Square reads the order and determines the amount to add to the card as the initial balance.

When an application uses a custom solution to create an order and process a payment, the activity doesn't appear in the Sales Summary report. Only the Gift Cards report tracks this activity.

The Gift Cards section in the Seller Dashboard can be used for the following tasks:

• View information about all gift cards, such as recent activation and redemption totals and the Last Used location and date for each card.
• View the status and activity history for an individual gift card and clear the gift card balance. Orders that are processed with the Orders API provide a Receipt link that opens the transaction details. You can search for a gift card by entering the full GAN in the Search by Gift Card Number box.
• Manage your gift card settings on the Settings page.

The Customers section in the Seller Dashboard can be used for the following tasks:

• View the gift cards that are linked to a customer. When you select a customer profile, the Cards on File tile in the details pane shows credit cards and gift cards on file.
• View the activity history of a linked gift card.

• Gift Cards API and Gift Card Activities API Overview
• API Reference: Gift Cards
• API Reference: Gift Card Activities