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

Gift Cards API Overview

Square gift cards enable sellers to boost sales and attract new customers. Sellers can launch a complete gifting program with digital and physical gift cards, which can be purchased online or in person. Buyers can choose to send digital cards to friends and family and introduce them to the seller's business.

Sellers can use the Square Seller Dashboard and Square Point of Sale (POS) application to sell, redeem, track, and reload Square gift cards. In addition to these Square first-party applications, Square provides the following APIs for developers to integrate Square gift cards into third-party applications:

  • The Gift Cards API provides endpoints to create and access gift cards. The Gift Cards API can also be used to link customers to and unlink customers from gift cards.

  • The Gift Card Activities API provides endpoints to create and list activities performed on gift cards, such as activating a gift card with a balance, adding funds to a gift card, and redeeming a gift card.

Core components Permalink Get a link to this section

The GiftCard and GiftCardActivity objects are the core components in the Gift Cards API and Gift Card Activities API.

GiftCard object Permalink Get a link to this section

A GiftCard object represents a digital or physical gift card. Applications can call CreateGiftCard in the Gift Cards API to create a gift card. The following is an example GiftCard object:

{
  "gift_card": {
    "id": "gftc:012440e514754c42990f3de4527498dc",
    "type": "DIGITAL",
    "gan_source": "SQUARE",
    "state": "PENDING",
    "balance_money": {
      "amount": 0,
      "currency": "USD"
    },
    "customer_ids": [
      "ASG67K1YGCSQQ47KSW7J7WX53M", 
      "QNTC0TYTWMRSFFQ157KK4V7MVR"
    ],
    "gan": "7783320002382646",
    "created_at": "2021-04-11T18:49:34Z"
  }
}

The gift card type can be DIGITAL or PHYSICAL. All gift cards have an ID and a gift card account number (GAN). For Square gift cards, the gan_source is SQUARE and gan is a 16-digit number that is unique across all Square sellers.

  • For physical cards, the GAN is printed on the card.

  • For digital gift cards created using Square first-party applications (such as the POS application or Seller Dashboard), Square emails the GAN to the recipient.

  • For digital gift cards that you create and activate using the API, you are responsible for delivering the gift card information. For example, you might display the information on your application's website or send the information to the recipient.

You can use the gift card ID or GAN with the CreateGiftCardActivity endpoint to manage the gift card state or balance, such as activating the gift card with a balance, loading additional funds, or redeeming the gift card.

Note

A new gift card has a PENDING state and zero balance. Before the gift card can be used, it must be activated with a balance, which sets the state to ACTIVE. For more information, see Selling Square gift cards.

You can also use the gift card ID to manage gift cards on file for customers. Gift cards linked to customer profiles include a customer_ids field that lists the IDs of the linked profiles. In addition, you can retrieve a list of gift cards or retrieve a gift card by ID, GAN, or payment token.

GiftCardActivity object Permalink Get a link to this section

A GiftCardActivity object represents an activity that changes a gift card balance or state. Applications can call CreateGiftCardActivity in the Gift Card Activities API to perform various actions on a gift card. The following is an example GiftCardActivity object:

{
  "gift_card_activity": {
    "id": "gcact_c24da663c0d242f5a29837d8e165bf97",
    "type": "ACTIVATE",
    "location_id": "S8GWD5R9QB376",
    "created_at": "2021-04-11T19:01:14.000Z",
    "gift_card_id": "gftc:012440e514754c42990f3de4527498dc",
    "gift_card_gan": "7783320002382646",
    "gift_card_balance_money": {
      "amount": 2500,
      "currency": "USD"
    },
    "activate_activity_details": {
      "amount_money": {
        "amount": 2500,
        "currency": "USD"
      },
      "order_id": "q8vfn99RLTr7FuMaUtuDG6RHdCcZY",
      "line_item_uid": "syHOf0zv9OjS2vhkhFozVC"
    }
  }
}

In this example gift card activity:

  • The ACTIVATE type indicates that CreateGiftCardActivity was called to activate a gift card.

  • The activate_activity_details field contains information related to the ACTIVATE activity. All gift card activities contain an <activity-type>_activity_details field that contains information that corresponds to the specific activity type. For example, a LOAD activity contains a load_activity_details field.

CreateGiftCardActivity can be used to perform the following activities:

Activity typeDescription
ACTIVATEActivate a gift card with a balance. A gift card must be in the ACTIVE state to be used for any other activity.
LOADLoad a gift card with additional funds.
REDEEMRedeem funds from a gift card for a transaction.

If your application uses the Payments API to make a gift card payment, Square automatically creates a REDEEM activity after the payment is completed. For more information, see Redeem a gift card for a purchase.
CLEAR_BALANCESet a gift card balance to zero. This activity should be called before reusing a physical gift card.

When a physical gift card reaches a zero balance for any reason, Square automatically unlinks all customers from the gift card. This behavior helps keep the linked customer profile setting up to date if the card is reused.
DEACTIVATEPermanently block a gift card from any future balance-changing activities. This activity should be called to prevent a gift card from being used (for example, before discarding a physical gift card or if the card is lost or stolen).
ADJUST_INCREMENTIncrease a gift card balance when the adjustment is not related to a transaction. To increase the balance based on a transaction, use the appropriate LOAD, REFUND, or UNLINKED_ACTIVITY_REFUND activity.
ADJUST_DECREMENTDecrease a gift card balance when the adjustment is not related to a transaction. To decrease the balance based on a transaction, use the REDEEM activity.
REFUNDAdd money to a gift card from a refunded transaction that was paid with the same gift card.
UNLINKED_ACTIVITY_REFUNDAdd money to a gift card from a refunded transaction that was not paid with the same gift card. For example, applications that use an external payment processing system can specify a reference_id for this activity and refund the payment to a Square gift card.

In addition, Square first-party applications create these activities when a seller refunds a credit card payment to a gift card. Currently, the Refunds API does not support refunding a credit card payment directly to a gift card.

Note

The CreateGiftCardActivity endpoint does not support all activity types. For more information, see Unsupported gift card activities.

Sellers can also use the POS application or Seller Dashboard to create gift card activities. For example, a seller might use the POS application to sell a gift card or use the Seller Dashboard to add money to an existing gift card.

You can call ListGiftCardActivities to view all activities for a gift card or a set of filtered activities. The ListGiftCardActivities results include all gift card activities initiated by Square, first-party applications, and third-party applications.

Selling Square gift cards Permalink Get a link to this section

You can use the CreateGiftCard endpoint in the Gift Cards API to create a GiftCard object that represents a digital or physical gift card.

Note

To sell physical gift cards, a seller must first order a pack of physical gift cards in the Seller Dashboard.

A gift card can be used only after it is activated and funds are added. Therefore, typical application steps for selling a gift card include:

  1. Create the gift card. Call CreateGiftCard and provide the information needed to create a digital gift card or register a physical gift card.

    • Digital gift cards. For type, specify DIGITAL.

      Create Gift Card
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      curl https://connect.squareupsandbox.com/v2/gift-cards \
        -X POST \
        -H 'Square-Version: 2021-09-15' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "idempotency_key": "{UNIQUE_KEY}",
          "location_id": "{LOCATION_ID}",
          "gift_card": {
            "type": "DIGITAL"
          }
        }'
    • Physical gift cards. Provide the following information:

      • For type, specify PHYSICAL.

      • For gan, specify the GAN printed on the physical gift card. This must be the GAN of an unused Square gift card that the seller previously ordered from Square.

      Note

      Testing physical gift cards in the Sandbox environment is not supported.

      When a physical gift card reaches a zero balance for any reason, Square automatically unlinks all customers from the gift card. This behavior helps keep the linked customer profile setting up to date if the card is reused.

  2. Process the payment from the buyer for the gift card purchase. The application has the option to use the Orders API or its own order management system to process funds to add to the gift card.

  3. Activate the gift card with a balance. Call CreateGiftCardActivity and specify the ACTIVATE type. In the request, the information you provide for activate_activity_details depends on whether your application uses the Orders API to process a gift card order.

    • Using the Orders API. Provide the order ID and line item ID. The API reads the order and determines the amount to add to the gift card.

      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: 2021-09-15' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "idempotency_key": "{UNIQUE_KEY}",
          "gift_card_activity": {
            "gift_card_gan": "{GIFT_CARD_GAN}",
            "type": "ACTIVATE",
            "location_id": "{LOCATION_ID}",
            "activate_activity_details": {
              "order_id": "{ORDER_ID}",
              "line_item_uid": "{LINE_ITEM_UID}"
            }
          }
        }'

      Note

      If your application uses the Orders API to process gift card orders, the order must be in the COMPLETED state before you can use it to activate or load a gift card.
    • Using a non-Square API. If an application uses a custom API to process money from the buyer, explicitly specify the amount to add to the gift card and provide payment instrument IDs.

      Create Gift Card Activity
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      • 14
      • 15
      • 16
      • 17
      • 18
      • 19
      • 20
      • 21
      • 22
      • 23
      • 24
      curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
        -X POST \
        -H 'Square-Version: 2021-09-15' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "idempotency_key": "{UNIQUE_KEY}",
          "gift_card_activity": {
            "gift_card_gan": "{GIFT_CARD_GAN}",
            "type": "ACTIVATE",
            "location_id": "{LOCATION_ID}",
            "activate_activity_details": {
              "amount_money": {
                "amount": 2500,
                "currency": "USD"
              },
              "buyer_payment_instrument_ids": [
                "example-id-1",
                "example-id-2"
              ],
              "reference_id": "client-side-example-reference-id"
            }
          }
        }'

    After activating the gift card, it is ready to be used by the recipient.

For gift cards created using the API, Square does not deliver the gift card to the recipient. The developer is responsible for delivering gift card information to the recipient.

Third-party gift cards Permalink Get a link to this section

If a seller has gift cards previously purchased from another gift card provider (not from Square) and sold them to customers, the seller must follow a one-time process with Square Support to import these third-party gift cards into Square. The seller can then accept these gift cards for redemption like Square gift cards. Third-party gift cards have the gan_source type set to OTHER.

Using activated gift cards Permalink Get a link to this section

After a gift card is activated, the gift card holder can do the following:

  • Redeem a gift card for purchases.

  • Add money to the gift card.

Redeem a gift card for a purchase Permalink Get a link to this section

The way in which a gift card is redeemed depends on whether the application uses the Square Payments API to process payments.

  • Applications using the Square Payments API. When your application uses the Payments API to process a gift card payment, a GiftCardActivity object with type REDEEM is automatically created after the application successfully completes the payment. For example, you might use the Web Payments SDK in your web application in conjunction with the Payments API. After taking the gift card information, your application calls CreatePayment to take payment.

  • Applications using manual redeems. If an application does not use the Square Payments API for processing a payment, the application must explicitly call CreateGiftCardActivity with REDEEM as the activity type to record the redemption. The application is responsible for making this call to ensure that the gift card balance is accurately reflected. For example, suppose the buyer redeemed a gift card to pay $3 for a purchase. After processing the payment, the application calls CreateGiftCardActivity as shown:

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_id": "{GIFT_CARD_ID}",
          "type": "REDEEM",
          "location_id": "{LOCATION_ID}",
          "redeem_activity_details": {
            "amount_money": {
              "amount": 300,
              "currency": "USD"
            },
            "reference_id": "client-side-example-reference-id"
          }
        }
      }'

    The redeem_activity_details in the request body provides:

    • The amount to redeem.

    • An optional reference_id to associate any other reference.

    In response, the endpoint creates a GiftCardActivity object and returns it in the response as shown:

    {
      "gift_card_activity": {
        "id": "gcact_8705537d2d75461da6d681384115c401",
        "type": "REDEEM",
        "location_id": "S8GWD5R9QB376",
        "created_at": "2021-04-11T20:44:32.000Z",
        "gift_card_id": "gftc:01696eaf3d5141bfb4c7869494257bb6",
        "gift_card_gan": "7783320005719034",
        "gift_card_balance_money": {
          "amount": 2200,
          "currency": "USD"
        },
        "redeem_activity_details": {
          "amount_money": {
            "amount": 300,
            "currency": "USD"
          },
          "reference_id": "client-side-example-reference-id"
        }
      }
    }
    

    You can optionally call RetrieveGiftCard to review the balance on the gift card.

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

    The following is an example response:

    {
      "gift_card": {
        "id": "gftc:012440e514754c42990f3de4527498dc",
        "type": "DIGITAL",
        "gan_source": "SQUARE",
        "state": "ACTIVE",
        "balance_money": {
          "amount": 2500,
          "currency": "USD"
        },
        "gan": "7783320002382646",
        "created_at": "2021-04-11T18:49:34Z"
      }
    }
    

Add money to a gift card Permalink Get a link to this section

An application can call CreateGiftCardActivity with LOAD as the activity type to add money to a gift card.

Typically, a gift card holder provides a GAN and an amount to add to the gift card. The activity details the application provides in the request depends on whether it used the Orders API to process the order to add money to the card.

  • Using the Orders API. In this case, the application provides the order ID and line item ID in a CreateGiftCardActivity call as shown. The API can then access the order and determine the amount to add to the gift card.

    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: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_id": "{GIFT_CARD_ID}",
          "type": "LOAD",
          "location_id": "{LOCATION_ID}",
          "load_activity_details": {
            "order_id": "{ORDER_ID}",
            "line_item_uid": "{LINE_ITEM_UID}"
          }
        }
      }'

    Note

    If your application uses the Orders API to process gift card orders, the order must be in the COMPLETED state before you can use it to activate or load a gift card.
  • Using non-Square API. If the application does not use the Orders API, the activity details in the request must include the amount to add to the gift card as shown in the following CreateGiftCardActivity call:

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_id": "{GIFT_CARD_ID}",
          "type": "LOAD",
          "location_id": "{LOCATION_ID}",
          "load_activity_details": {
            "amount_money": {
              "amount": 1000,
              "currency": "USD"
            },
            "reference_id": "client-side-example-reference-id",
            "buyer_payment_instrument_ids": [
              "id-1",
              "id-2"
            ]
          }
        }
      }'

You can optionally call RetrieveGiftCard to view the balance on the gift card.

A seller can also use the POS application or the Seller Dashboard to add money to a gift card. The resulting gift card activity is reported when you call ListGiftCardActivity.

Gift cards as payment source in the Payments API Permalink Get a link to this section

You can specify a gift card as a payment source when taking payment using the Payments API. For more information, see Take Card Payments.

Requirements and limitations Permalink Get a link to this section

When working with the Gift Cards API, the following requirements and limitations apply:

Requirements Permalink Get a link to this section

Limitations Permalink Get a link to this section

  • The Gift Cards API does not support creating gift cards with a custom GAN.

  • Creating and managing physical gift cards in the Sandbox environment is not currently supported.

  • Using a gift card ID as the source_id for a CreatePayment request in the Sandbox environment is not currently supported. However, you can use a payment token that represents a test Square gift card.

  • When you load or redeem a gift card using the Orders API and Payments API, the Square Seller Dashboard reports include these transactions. However, there is no reporting when loading and redeeming gift cards using a custom client-side API (not the Square Orders API and Payments API).

  • The maximum number of gift cards you can link to a customer is 50.

  • The maximum number of customers you can link to a gift card is 10.

Related topics Permalink Get a link to this section