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. Buyers can purchase gift cards and introduce the seller's business to their friends and family. Customers can purchase Square gift cards online or in person and have the option to email digital cards.

Gift card support is integrated in the Square Seller Dashboard and the Square Point of Sale application. Sellers can easily 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 also links customers to and unlink customers from gift cards.

  • The Gift Card Activities API provides endpoints to create gift card activities, such as activate a gift card, add funds to a gift card, and redeem a gift card.

Core components Permalink Get a link to this section

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

GiftCard Permalink Get a link to this section

The GiftCard object represents a gift card (digital or physical). 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"
  }
}

A gift card type can be PHYSICAL or DIGITAL. In addition, every gift card has a gift card account number (GAN).

For Square gift cards (gan_source is SQUARE), the GAN is a 16-digit number that is unique across all sellers. Sellers share the GAN with the gift card recipient. Physical cards have the GAN printed on them. For digital cards, when using a Square first-party product (such as the Square Point of Sale application or Seller Dashboard), Square emails the GAN to the recipient.

An application can use the GAN or ID to create gift card activities (for example, add money to the gift card) using the CreateGiftCardActivity endpoint. The gift card holder can only use the card when the gift card state is ACTIVE.

You can add a gift card on file to one or more customer profiles in the seller's Customer Directory. The customer_ids field lists the profile IDs of the linked customers.

GiftCardActivity Permalink Get a link to this section

A GiftCardActivity object represents any balance or state changing activity on a gift card, or both. Applications can call CreateGiftCardActivity ( GiftCardActivities API) to perform various gift card activities. A CreateGiftCardActivity call returns a GiftCardActivity object. 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 type ACTIVATE indicates that CreateGiftCardActivity was called to activate a gift card.

  • Depending on the type of activity, the response includes the <activity-type>_activity_details field. In this example, the response also includes the activate_activity_details showing the details that are pertinent to the type ACTIVATE. Depending on the activity type, gift_card_activity includes the corresponding field with details.

A seller can use the Square Point of Sale application or Seller Dashboard to create gift card activities. For example, a seller might use the Point of Sale application to sell a gift card or use the Seller Dashboard to add money to an existing gift card. ListGiftCardActivities reports all these activities.

Selling Square gift cards Permalink Get a link to this section

A seller can use the Gift Cards API CreateGiftCard endpoint to create a gift card (physical or digital). The API creates a GiftCard object representing the gift card.

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. So typical application steps include:

  1. Create a gift card. If you are selling a digital card, call CreateGiftCard to create a card.

    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-07-21' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "location_id": "{LOCATION_ID}",
        "gift_card": {
          "type": "DIGITAL"
        }
      }'

    For physical gift cards, the request must include the gift card account number (GAN) printed on the physical gift card, as shown in the following example. This must be an unused Square gift card that the seller previously ordered from Square.

    ...
        "gift_card": {
            "type": "PHYSICAL",
            "gan": "7782731234567890"
        }
    ...
    }'  
    
  2. Process the payment from the buyer for the gift card purchase. The application has the option to use the Square Orders API or use its own order management system to process funds to add to the gift card.

  3. Activate the gift card. Call CreateGiftCardActivity with the type ACTIVATE. In the request, the activate_activity_details changes depending on whether your application uses the Square Orders API to process a gift card order.

    1. 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-07-21' \
        -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}"
            }
          }
        }'
    2. 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-07-21' \
        -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.

Note that, for gift cards created by the API, Square does not deliver the gift card to the recipient automatically.

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 Square payment form 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-07-21' \
      -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-07-21' \
      -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-07-21' \
      -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}"
          }
        }
      }'
  • 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-07-21' \
      -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 Square Point of Sale 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 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

The Gift Cards API requires OAuth credentials and permissions. For more information about credentials, see Square API Access Tokens.

An application, depending on the Gift Cards API functionality you want to integrate, needs the following permissions:

As you add more integrations to your application, you might need additional permissions. Each Square API technical reference provides the permissions needed for each individual endpoint.

Limitations Permalink Get a link to this section

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

  • When you load or redeem a gift card using the Orders API and Payments API, the Square Seller Dashboard reports include these transaction. 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