Learn how to check a gift card balance, add and remove gift cards on file, sell discounted gift cards, and review gift card sales in seller reports.
Gift Cards API

Additional Gift Cards API Considerations Beta release
This is pre-release documentation for an API in public beta and is subject to change.

This topic provides additional information about working with Square gift cards. It describes how to check a gift card balance, manage gift cards on file, list gift card activities, sell discounted gift cards, and view gift card reports in the Seller Dashboard.

Check a gift card balance Permalink Get a link to this section

The Gift Cards API provides endpoints to retrieve a gift card using the gift card ID, gift card number (GAN), or payment token generated by the Web Payments SDK or In-App Payments SDK.

The balance_money field in the returned GiftCard object represents the gift card balance.

Did you know?

The gift card balance is also returned in the gift_card_balance_money field in a CreateGiftCardActivity response.

Retrieve a gift card by ID Permalink Get a link to this section

Use the RetrieveGiftCard endpoint if you know the gift card ID. You provide the ID as a path parameter.

Retrieve Gift Card
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/gift-cards/{id} \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Retrieve a gift card by GAN Permalink Get a link to this section

Use the RetrieveGiftCardFromGAN endpoint if you know the GAN. You provide the GAN in the request body.

Retrieve Gift Card From G A N
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/gift-cards/from-gan \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "gan": "{GIFT_CARD_ACCOUNT_NUMBER}"
  }'

Retrieve a gift card by payment token Permalink Get a link to this section

Use the RetrieveGiftCardFromNonce endpoint if your application has a secure payment token generated by the Web Payments SDK or In-App Payments SDK that represents the gift card as the payment source. You provide the payment token in the request body.

Retrieve Gift Card From Nonce
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/gift-cards/from-nonce \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "nonce": "{PAYMENT_TOKEN}"
  }'

The following is an example response that shows a gift card balance of $22.21:

Check the activity history of a gift card Permalink Get a link to this section

To see the activity history for a gift card, call ListGiftCardActivities using the giftcard_id query parameter. If needed, you can call RetrieveGiftCardFromGAN, RetrieveGiftCardFromNonce, or ListGiftCards to get the gift card ID.

The following example request lists all activities for the specified gift card. By default, the response returns a maximum page size of 50 activities.

List Gift Card Activities
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/gift-cards/activities?gift_card_id={{gift_card_id}} \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

You can optionally use other query parameters to sort the activities and filter by activity type, location, and reporting period.

Note

If you encounter issues when running the cURL command from a terminal window, try wrapping the endpoint URL in quotation marks and resending the request.

Manage gift cards on file Permalink Get a link to this section

The Gift Cards API provides endpoints to add, remove, and list gift cards on file for a customer profile in the seller's Customer Directory. Adding a card on file is also referred to as linking customers to gift cards. Gift cards that are linked to one or more customers contain a customer_ids field that lists the IDs of the linked customers.

Note

This functionality replaces the deprecated CreateCustomerCard and DeleteCustomerCard endpoints and deprecated Customer.cards field in the Customers API.

Add a gift card on file Permalink Get a link to this section

The Gift Cards API provides the LinkCustomerToGiftCard endpoint that you can use to link a customer profile to a gift card.

The LinkCustomerToGiftCard request specifies a gift card ID and customer ID. To get the customer ID, call SearchCustomers to search by the customer's phone number, email address, or other supported attribute. For more information, see Search for Customer Profiles.

Link Customer To Gift Card
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/gift-cards/{gift_card_id}/link-customer \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "{CUSTOMER_ID}"
  }'

Square updates the gift card by adding the customer_ids field with the customer ID, as shown in the following example response:

Note

For gift cards with custom GANs, using the LinkCustomerToGiftCard adds the customer ID to the customer_ids field, but these gift cards are not currently visible as a card on file for the customer in first-party Square products, such as the Square Point of Sale application and Seller Dashboard. For more information, see Custom GANs.

Linking a customer profile to a gift card enables the following features:

  • Simplified payment process. Sellers can easily redeem a linked gift card when performing a transaction with a customer using Square first-party applications (such as the Square Point of Sale (POS) application or Seller Dashboard) or third-party applications that use the Gift Cards API.

  • Seller Dashboard enhancement. In the Customers section, the details pane shows credit cards and gift cards that are linked to the selected customer profile.

  • For developers using the CreatePayment endpoint in the Payments API, in addition to specifying a gift card as a payment source, developers can optionally specify the customer ID to associate the purchase with a customer (this customer need not be linked to the gift card).

The following constraints apply when linking a customer to a gift card:

  • A gift card can be linked to a maximum of 10 customer profiles.

  • A customer profile can be linked to a maximum of 50 gift cards.

Remove a gift card on file Permalink Get a link to this section

The Gift Cards API provides the UnlinkCustomerFromGiftCard endpoint that you can use to unlink the customer from the gift card.

The UnlinkCustomerFromGiftCard request specifies a gift card ID and customer ID. To get the customer ID, call SearchCustomers to search by the customer's phone number, email address, or other supported attribute. For more information, see Search for Customer Profiles.

Unlink Customer From Gift Card
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/gift-cards/{gift_card_id}/unlink-customer \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "{CUSTOMER_ID}"
  }'

Square removes the customer ID from the customer_ids field of the gift card. If the gift card is not linked to any other customers, the customer_ids field is also removed.

List gift cards on file Permalink Get a link to this section

To retrieve the gift cards that are linked to a customer, call ListGiftCards and specify the customer_id query parameter. To get the customer ID, call SearchCustomers to search by the customer's phone number, email address, or other supported attribute. For more information, see Search for Customer Profiles.

List Gift Cards
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/gift-cards?customer_id={{customer_id}} \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

The following example response shows that the customer is linked to two gift cards, one of which is also linked to another customer:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
{
  "gift_cards": [
    {
      "id": "gftc:080fc3433b294b549213aa01376661dc",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "PENDING",
      "balance_money": {
        "amount": 0,
        "currency": "USD"
      },
      "gan": "7783320002499499",
      "created_at": "2021-10-26T15:39:40Z",
      "customer_ids": [
        "62Y0FBFDQ0ZHDCGKBYP7FZK474"
      ]
    },
    {
      "id": "gftc:0a785b3644b64b74878d8e86f4a7ac70",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "ACTIVE",
      "balance_money": {
        "amount": 5373,
        "currency": "USD"
      },
      "gan": "7783320006798490",
      "created_at": "2021-01-31T22:00:34Z",
      "customer_ids": [
        "1WX4B9HYEMVW716HVQ7Y10XQ34",
        "62Y0FBFDQ0ZHDCGKBYP7FZK474"
      ]
    }
  ]
}

Note

In the Seller Dashboard, you can see a customer's gift cards on file by selecting the customer in the Customers Directory. If the customer is linked to any gift cards, they are listed under Cards on File.

Sell discounted gift cards Permalink Get a link to this section

When you use the Orders API to sell or reload a gift card, you can include a discount for the GIFT_CARD line item. The discount must be defined as an ad hoc discount for the order.

The following CreateOrder example includes an ad hoc, line item discount for a gift card purchase. In the request:

  • The discounts field contains the ad hoc discount definition for the order.

  • The applied_discounts field applies the discount to the gift card line item.

  • The item_type field of the gift card line item specifies GIFT_CARD.

Create Order
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
  • 22
  • 23
  • 24
  • 25
  • 26
  • 27
  • 28
  • 29
  • 30
  • 31
  • 32
  • 33
  • 34
  • 35
curl https://connect.squareupsandbox.com/v2/orders \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "order": {
      "location_id": "{LOCATION_ID}",
      "line_items": [
        {
          "name": "Square Gift Card",
          "quantity": "1",
          "item_type": "GIFT_CARD",
          "base_price_money": {
            "amount": 2500,
            "currency": "USD"
          },
          "applied_discounts": [
            {
              "discount_uid": "10_PERCENT_OFF"
            }
          ]
        }
      ],
      "discounts": [
        {
          "uid": "10_PERCENT_OFF",
          "name": "Sale - 10% off",
          "percentage": "10.0",
          "scope": "LINE_ITEM"
        }
      ]
    }
  }'

After you generate a payment token using the Web Payments SDK or In-App Payment SDK, you can pay for the order by calling CreatePayment in the Payments API, as shown in the following example request. Alternatively, you can provide the ID of a card on file for source_id in the CreatePayment request. For more information, see Take Payments.

The following example request creates a payment for the total_money amount from the order, which includes the 10% discount:

Create Payment
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
curl https://connect.squareupsandbox.com/v2/payments \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "{PAYMENT_TOKEN}",
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 2250,
      "currency": "USD"
    },
    "order_id": "{ORDER_ID}",
    "location_id": "{LOCATION_ID}"
  }'

When the transaction is complete, you can create the ACTIVATE or LOAD activity by calling CreateGiftCardActivity in the Gift Card Activities API. The following example request creates a LOAD activity and specifies the ID of the order and UID of the GIFT_CARD line item:

Create Gift Card Activity
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "gift_card_activity": {
      "gift_card_gan": "{GIFT_CARD_ACCOUNT_NUMBER}",
      "type": "LOAD",
      "location_id": "{LOCATION_ID}",
      "load_activity_details": {
        "order_id": "{ORDER_ID}",
        "line_item_uid": "{LINE_ITEM_UID}"
      }
    }
  }'

Square adds the prediscounted amount to the gift card balance. In the following example response, you can see that Square added $25.00:

When your application uses the Orders API to process a gift card order, the order must be in the COMPLETED state before you activate or load the gift card. In addition, the line item for the gift card must specify GIFT_CARD as the item_type. Otherwise, the order is not processed as a gift card sale and the gift card cannot be activated or loaded using Orders API integration.

If the gift card order is refunded after the funds are added to the gift card, you must call CreateGiftCardActivity to deduct the funds from the gift card balance. You can create a CLEAR_BALANCE activity to set the balance to zero or an ADJUST_DECREMENT activity to deduct a specified amount. Using the Refunds API to refund a gift card order does not update the gift card balance (unlike using the Refunds API to refund a gift card payment, which does update the gift card balance).

View gift card reports in the Seller Dashboard Permalink Get a link to this section

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 does not 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 an order ID, 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 does not appear in the Sales Summary report. Only the Gift Cards report tracks this activity.

Sellers can also use the Gift cards section in the Seller Dashboard to manage gift card settings, view information about activated gift cards, and clear a gift card's balance. You can search for a particular gift card by entering the full GAN in the Search by Gift Card Number box.

Related topics Permalink Get a link to this section

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.