Manage Square Gift Cards on File

Square gift cards can be linked with customers and saved as gift cards on file. Linking gift cards with customers makes it easy for buyers and sellers to access gift cards for future redemptions, reloading, and activity tracking. Developers can use the Gift Cards API for managing gift cards on file.

Square provides the following endpoints to manage gift cards on file:

• LinkCustomerToGiftCard - Adds a gift card on file.
• UnlinkCustomerFromGiftCard - Removes a gift card on file.
• ListGiftCards with the customer_id query parameter - Lists the gift cards on file for a customer.

Linked gift cards include a customer_ids field that lists the IDs of all linked customers.

To add a gift card on file for a customer, call LinkCustomerToGiftCard and provide the following information in the request:

• gift_card_id - The ID of the gift card to link to the customer. There are several ways that you can get a gift card ID.
• customer_id - The ID of the customer to link to the gift card. You can search customer profiles by phone number, email address, or other supported attribute if you need to get the ID.

If successful, the gift card in the response includes the customer_ids field with the ID of the linked customer, as shown in the following example:

{
   "gift_card": {
      "id": "gftc:73df43542ef447f0905c2f21bEXAMPLE",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "ACTIVE",
      "balance_money": {
         "amount": 5000,
         "currency": "USD"
      },
      "gan": "7783320008000000",
      "created_at": "2023-04-08T20:17:25Z",
      "customer_ids": [
         "7TPK262NN0SP5CC4ZNMEXAMPLE"
      ]
   }
}

To unlink a customer from a gift card, call UnlinkCustomerFromGiftCard and provide the following information in the request:

• gift_card_id - The ID of the gift card to unlink from the customer. After you get the customer ID, you can list the customer's gift cards on file to get the gift card ID.
• customer_id - The ID of the customer to unlink from the gift card. You can search customer profiles by phone number, email address, or other supported attribute if you need to get the ID.

If successful, Square removes the customer ID from the customer_ids field. Square also removes the customer_ids field if the gift card has no other linked customers.

To retrieve gift cards that are linked to a customer, call ListGiftCards using the customer_id query parameter. You can list gift cards to get the ID of a gift card on file to use for a payment or to check other details such as the gift card balance or state. For example, you might need to show a list of ACTIVE gift cards and balances to the buyer so they can choose one to use for a payment.

Provide the following information in the request:

• customer_id - The ID of the linked customer. You can search customer profiles by phone number, email address, or other supported attribute if you need to get the ID.
• state - An optional filter that you can include to request gift cards in a particular state. For example, you can filter for ACTIVE gift cards.

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

{
  "gift_cards": [
    {
      "id": "gftc:080fc3433b294b549213aa013EXAMPLE",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "ACTIVE",
      "balance_money": {
        "amount": 210,
        "currency": "USD"
      },
      "gan": "7783320002000000",
      "created_at": "2021-10-26T15:39:40Z",
      "customer_ids": [
        "62Y0FBFDQ0ZHDCGKBYPEXAMPLE"
      ]
    },
    {
      "id": "gftc:0a785b3644b64b74878d8e86fEXAMPLE",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "ACTIVE",
      "balance_money": {
        "amount": 5373,
        "currency": "USD"
      },
      "gan": "7783320006000000",
      "created_at": "2021-01-31T22:00:34Z",
      "customer_ids": [
        "1WX4B9HYEMVW716HVQ7YEXAMPLE",
        "62Y0FBFDQ0ZHDCGKBYPEXAMPLE"
      ]
    }
  ]
}

To take a payment from a gift card on file, first list the gift cards on file for the customer and get the gift card ID. Then, call CreatePayment and provide the gift card ID as the source_id of the payment, as shown in the following request:

The payment in the response contains the following card_details.card settings:

• card_brand is SQUARE_GIFT_CARD.
• card_type is DEBIT.
• prepaid_type is PREPAID.

After the payment is completed, Square automatically updates the gift card balance. You don't need to call CreateGiftCardActivity directly.

Unlike using a credit or debit card ID, the customer_id field is optional for payments made using a gift card ID. If provided, customer_id can specify any customer in the seller's Customer Directory; Square doesn't validate that the specified customer is linked to the gift card. As a best practice, you should provide a customer_id in your CreatePayment requests.

For more payment-related information, see Redeem a gift card when using the Payments API.

The following considerations apply to managing gift cards on file:

• A gift card can be linked to one or more customers. To link or unlink multiple customers, you must call LinkCustomerToGiftCard or UnlinkCustomerFromGiftCard for each customer profile.

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

• Square invokes the gift_card.updated webhook event after a customer is linked to or unlinked from a gift card. These operations don't invoke gift_card.activity or customer events.

• When the balance of a physical (plastic) 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.

• In the Customers Directory in the Square Dashboard or Square Point of Sale, sellers can view gift cards on file for the selected customer profile in the Cards on File tile in the details pane. Sellers can also add a gift card on file from the tile.

  Note that gift cards with custom GANs aren't currently visible as a gift card on file for the customer profile.

• Buyers can view and manage their own gift cards from their Square profile.

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