Gift Cards API

Additional Gift Cards API Considerations

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
Check the activity history of a gift card
Manage gift cards on file
Sell discounted gift cards
View gift card reports in the Seller Dashboard
Related topics

Check a gift card balance
Retrieve a gift card by ID
Retrieve a gift card by GAN
Retrieve a gift card by payment token
Check the activity history of a gift card
Calling ListGiftCardActivities to get a gift card ID
Manage gift cards on file
Add a gift card on file
Remove a gift card on file
List gift cards on file
Sell discounted gift cards
View gift card reports in the Seller Dashboard
Related topics

Link to section
Check a gift card balance

The Gift Cards API provides endpoints to retrieve a gift card using the gift card ID, gift card account 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.

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

Link to section
Retrieve a gift card by ID

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

Retrieve Gift Card

curl https://connect.squareupsandbox.com/v2/gift-cards/{{GIFT_CARD_ID}} \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

Link to section
Retrieve a gift card by GAN

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

Retrieve Gift Card From G A N

curl https://connect.squareupsandbox.com/v2/gift-cards/from-gan \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "gan": "{GIFT_CARD_ACCOUNT_NUMBER}"
  }'

Link to section
Retrieve a gift card by payment token

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

curl https://connect.squareupsandbox.com/v2/gift-cards/from-nonce \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

Link to section
Check the activity history of a gift card

To see the activity history for a gift card, call ListGiftCardActivities using the gift_card_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

curl https://connect.squareupsandbox.com/v2/gift-cards/activities?gift_card_id={{GIFT_CARD_ID}} \
  -H 'Square-Version: 2023-05-17' \
  -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.

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.

Link to section
Calling ListGiftCardActivities to get a gift card ID

When you need to retrieve a gift card but do not have the gift card ID, GAN, or payment token, you can call ListGiftCardActivities to find the ID and then call RetrieveGiftCard. 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 your request using information from the order.

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 do not include the gift card ID or full GAN.

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

{
  "id": "eYzvKpbrkqcK7Np6hgGOdsyDuaB",
  "location_id": "S8GWD5R9QB376",
  ...
  "tenders": [
    {
      "id": "xCJGyy4N4DcINY6EakKm4J0VrUCZY",
      "location_id": "S8GWD5R9QB376",
      "transaction_id": "eYzvKpbrkqcK7Np6hgGOdsyDuaB",
      "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_Ox5RzUN7Vg"
       },
       "entry_method": "KEYED"
     },
     "payment_id": "xCJGyy4N4DcINY6EakKm4J0VrUCZY"
    }
  ],
  ...
}

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.

List Gift Card Activities

curl https://connect.squareupsandbox.com/v2/gift-cards/activities?type=REDEEM&location_id=S8GWD5R9QB376&begin_time=2022-10-19T20%3A39%3A26Z&end_time=2022-10-19T20%3A45%3A26Z \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

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

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
36
37
38
39
40
41
42
43
44

{
  "gift_card_activities": [
    {
      "id": "gcact_728713fd9d034195811d58a3056bc0da",
      "type": "REDEEM",
      "location_id": "S8GWD5R9QB376",
      "created_at": "2022-10-19TT20:42:25.000Z",
      "gift_card_id": "gftc:1afce56ce3b74b9c92b2b1ad46d077e6",
      "gift_card_gan": "7783320005183922",
      "gift_card_balance_money": {
        "amount": 1765,
        "currency": "USD"
      },
      "redeem_activity_details": {
        "amount_money": {
          "amount": 1500,
          "currency": "USD"
        },
        "payment_id": "xCJGyy4N4DcINY6EakKm4J0VrUCZY",
        "status": "COMPLETED"
      }
    },
    {
      "id": "gcact_2f7000463bdc45fd899439d62f76226a",
      "type": "REDEEM",
      "location_id": "S8GWD5R9QB376",
      "created_at": "2022-10-19TT20:44:57.000Z",
      "gift_card_id": "gftc:065fd3c6e1014c9293bd2d09475ea189",
      "gift_card_gan": "7783320009623257",
      "gift_card_balance_money": {
        "amount": 13510,
        "currency": "USD"
      },
      "redeem_activity_details": {
        "amount_money": {
          "amount": 0,
          "currency": "USD"
        },
        "payment_id": "vFR58dqbNIIOV2gDXRCngsbvkxKZY",
        "status": "CANCELED"
      }
    }
  ]
}

You can then use the gift_card_id to call RetrieveGiftCard.

gift_card_balance_money represents the gift card balance at the time of the activity. It is not the current gift card balance.

Link to section
Manage gift cards on file

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.

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

Link to section
Add a gift card on file

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

curl https://connect.squareupsandbox.com/v2/gift-cards/{gift_card_id}/link-customer \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

{
   "gift_card":{
      "id":"gftc:73df43542ef447f0905c2f21b38480b0",
      "type":"DIGITAL",
      "gan_source":"SQUARE",
      "state":"NOT_ACTIVE",
      "balance_money":{
         "amount":0,
         "currency":"USD"
      },
      "gan":"7783320008367013",
      "created_at":"2021-04-08T20:17:25Z",
      "customer_ids":[
         "7TPK262NN0SP5CC4ZNMFXPY808"
      ]
   }
}

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.

When the balance of a physical gift card reaches zero, Square automatically unlinks the gift card from any customer profiles. This prevents past customers from receiving receipts in the case that a seller resells the gift card to a new customer.

Link to section
Remove a gift card on file

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

curl https://connect.squareupsandbox.com/v2/gift-cards/{gift_card_id}/unlink-customer \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -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.

Link to section
List gift cards on file

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

curl https://connect.squareupsandbox.com/v2/gift-cards?customer_id={{customer_id}} \
  -H 'Square-Version: 2023-05-17' \
  -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"
      ]
    }
  ]
}

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.

Link to section
Sell discounted gift cards

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: 2023-05-17' \
  -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: 2023-05-17' \
  -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: 2023-05-17' \
  -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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
  "gift_card_activity": {
    "id": "gcact_afe01be1e2c74ce2af06f1e19d344ad4",
    "type": "LOAD",
    "location_id": "M8AKAD8160XGR",
    "created_at": "2021-10-20T20:45:10.000Z",
    "gift_card_id": "gftc:0a785b3644b64b74878d8e86f4a7ac70",
    "gift_card_gan": "7783320006798490",
    "gift_card_balance_money": {
      "amount": 7873,
      "currency": "USD"
    },
    "load_activity_details": {
      "amount_money": {
        "amount": 2500,
        "currency": "USD"
      },
      "order_id": "24fKnZTsLPbg7bX6nuE5hpiXuaB",
      "line_item_uid": "3m47NE7MCgASdPYbUUQVUC"
    }
  }
}

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 an ADJUST_DECREMENT activity with the PURCHASE_WAS_REFUNDED reason to deduct a specified amount. Using the Refunds API to refund a gift card order does not automatically update the gift card balance (unlike using the Refunds API to refund a gift card payment, which does update the gift card balance).

Link to section
View gift card reports in the Seller Dashboard

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 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 does not 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.

Link to section
Related topics

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

Docs

Additional Gift Cards API Considerations

On this page

On this page

Link to section
Check a gift card balance

Did you know?

Link to section
Retrieve a gift card by ID

Link to section
Retrieve a gift card by GAN

Link to section
Retrieve a gift card by payment token

Link to section
Check the activity history of a gift card

Note

Link to section
Calling ListGiftCardActivities to get a gift card ID

Note

Link to section
Manage gift cards on file

Note

Link to section
Add a gift card on file

Note

Link to section
Remove a gift card on file

Link to section
List gift cards on file

Note

Link to section
Sell discounted gift cards

Link to section
View gift card reports in the Seller Dashboard

Link to section
Related topics

On this page

Docs

Additional Gift Cards API Considerations

On this page

On this page

Link to section Check a gift card balance

Did you know?

Link to section Retrieve a gift card by ID

Link to section Retrieve a gift card by GAN

Link to section Retrieve a gift card by payment token

Link to section Check the activity history of a gift card

Note

Link to section Calling ListGiftCardActivities to get a gift card ID

Note

Link to section Manage gift cards on file

Note

Link to section Add a gift card on file

Note

Link to section Remove a gift card on file

Link to section List gift cards on file

Note

Link to section Sell discounted gift cards

Link to section View gift card reports in the Seller Dashboard

Link to section Related topics

On this page

Link to section
Check a gift card balance

Link to section
Retrieve a gift card by ID

Link to section
Retrieve a gift card by GAN

Link to section
Retrieve a gift card by payment token

Link to section
Check the activity history of a gift card

Link to section
Calling ListGiftCardActivities to get a gift card ID

Link to section
Manage gift cards on file

Link to section
Add a gift card on file

Link to section
Remove a gift card on file

Link to section
List gift cards on file

Link to section
Sell discounted gift cards

Link to section
View gift card reports in the Seller Dashboard

Link to section
Related topics