Use the Gift Cards API and Gift Card Activities API to create and manage Square gift cards that help sellers increase sales and attract new customers.
Gift Cards API

Gift Cards API and Gift Card Activities 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 and Square Point of Sale to sell, redeem, track, and reload Square gift cards. In addition to these Square products, developers can use the following APIs to integrate Square gift cards into third-party applications:

  • The Gift Cards API provides endpoints to create a gift card, retrieve gift card information, link a customer to a gift card, and unlink a customer from a gift card.

  • 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, loading additional funds, and redeeming a gift card.

Developers can also receive webhook notifications about gift card events.

The core component of the Gift Cards API is the GiftCard object. The core component of the Gift Card Activities API is the GiftCardActivity object.

Link to section
GiftCard object

Applications can call CreateGiftCard in the Gift Cards API to create a DIGITAL gift card or register a PHYSICAL gift card. Digital and physical gift cards are represented by a GiftCard object.

The following is an example GiftCard object:

  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
{
  "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"
  }
}

All gift cards have both an ID and a gift card account number (GAN). For physical gift cards, the gan field matches the GAN that is printed on the card. Gift cards also have a gan_source field that indicates how the GAN was generated. If generated by Square, the gan_source is SQUARE. For imported gift cards and gift cards created with a custom GAN, the gan_source is OTHER.

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.

Link to section
GiftCardActivity object

Applications can call CreateGiftCardActivity in the Gift Card Activities API to perform actions on a gift card that change the balance or state. These activities are represented by a GiftCardActivity object. The following is an example GiftCardActivity object:

  • 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_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 activities contain an <activity-type>_activity_details field that corresponds to the specific activity type. For example, a LOAD activity contains a load_activity_details field.

  • The gift_card_balance_money field shows the updated gift card balance.

Link to section
Managing the gift card balance or state

After you create or register a gift card, you create activities to manage the gift card balance or state. These activities include activating the gift card with a balance, loading additional funds, and redeeming the gift card for purchases. To create activities, call the CreateGiftCardActivity endpoint and provide the gift card ID or GAN and the activity details.

You can also use the gift card ID to manage gift cards on file for customers. If a gift card is linked to one or more customer profiles, the GiftCard object includes a customer_ids field that lists the IDs of the linked profiles. In addition, you can retrieve a gift card by ID, GAN, or payment token.

Link to section
Supported activity types for CreateGiftCardActivity

You can use the CreateGiftCardActivity endpoint to perform the following activities:

Activity type
Description
ACTIVATEActivate a gift card with a balance. A gift card must be in the ACTIVE state to be used for any other activity.

Details field: activate_activity_details
LOADLoad a gift card with additional funds.

Details field: load_activity_details
REDEEMRedeem funds from a gift card after a gift card payment.

If your application uses the Payments API to make a gift card payment, Square automatically creates a REDEEM activity that updates the gift card balance after the payment is completed. For more information, see Redeem a gift card for a purchase.

Details field: redeem_activity_details
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.

Details field: clear_balance_activity_details
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).

Details field: deactivate_activity_details
ADJUST_INCREMENTIncrease a gift card balance when the adjustment is not related to a gift card order or payment. To increase the balance based on gift card orders or payments, use the appropriate LOAD, REFUND, or UNLINKED_ACTIVITY_REFUND activity.

Details field: adjust_increment_activity_details
ADJUST_DECREMENTDecrease a gift card balance when the adjustment is not related to a gift card payment. To decrease the balance based on a gift card payment, use the REDEEM activity.

Details field: adjust_decrement_activity_details
REFUNDAdd money to a gift card from a refunded transaction. The refund might be linked to a Square payment, depending on how the payment and refund are processed. For example:
 •   A gift card payment processed by Square can be refunded to the same gift card using the Refunds API. In this case, Square automatically creates a REFUND activity that updates the gift card balance after the RefundPayment request is completed. These activities have a payment_id and a redeem_activity_id.
 •   A cross-tender payment processed by Square can be refunded to a gift card using Square Point of Sale or the . The cross-tender payment source can be a credit card or different gift card. In this case, Square automatically creates a REFUND activity that updates the gift card balance after the RefundPayment request is completed. These activities have a payment_id but do not have a redeem_activity_id.
 •   A payment processed with a custom processing system can be refunded to the same gift card used for payment. In this case, the application must create a REFUND activity that updates the gift card balance. These activities have a redeem_activity_id but do not have a payment_id.

Details field: refund_activity_details
UNLINKED_ACTIVITY_REFUNDAdd money to a gift card from a refunded transaction that was not paid with the same gift card.

This activity type is used to refund a payment that was processed with a custom processing system and that is not being refunded to the same gift card used for payment.

Details field: unlinked_activity_refund_activity_details

Note

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

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

Sellers can also use Square Point of Sale or the to create and view gift card activities. For example, a seller might sell a gift card in Square Point of Sale or reload a gift card in the .

Link to section
Integration with the Orders API and Payments API

The requirements for some activities depend on whether your application uses the Orders API and Payments API to process orders and payments.

Link to section
Orders API integration with ACTIVATE and LOAD activities

The information you provide when activating or reloading a gift card depends on whether your application uses the Orders API to process gift card orders.

Order processing system
ACTIVATE or LOAD activity details
Orders APIorder_id
line_item_uid
Custom (non-Square APIs)amount_money
buyer_payment_instrument_ids
reference_id (optional)

For more information, see Selling gift cards and Reloading gift cards.

Link to section
Payments API integration with REDEEM and REFUND activities

The steps for redeeming a gift card or refunding a gift card payment to the same gift card depend on whether your application uses the Payments API to process gift card payments.

Payment processing system
Steps for REDEEM or REFUND activity
Payments APINo action required. When the payment is completed using the Payments API or the refund is completed using the Refunds API, Square creates a REDEEM or REFUND activity to update the gift card balance. Only payments processed with the Payments API can be refunded with the Refunds API.
Custom (non-Square APIs)Application must call CreateGiftCardActivity to create a REDEEM or REFUND activity after the payment or refund is completed. Note that custom payment processing applications create an UNLINKED_ACTIVITY_REFUND activity to refund a cross-tender payment to a (different) gift card.

For more information, see Redeeming gift cards for purchases.

Link to section
Selling gift cards

Selling a gift card includes the following high-level steps:

It is your responsibility to deliver information for digital gift cards that you create. For more information, see Delivering digital gift cards.

Note

For detailed steps that show how to sell a gift card in the Square Sandbox, see Walkthrough 1: Sell a Gift Card. For a diagram that shows the end-to-end process, see Flow diagram: Selling a gift card (Orders API integration).

You can also watch the Sandbox 101: Gift Cards API video to see how to purchase, create, and activate a gift card in the Sandbox or check out the Gift Cards API Sample App and accompanying Gift Cards API Sample App Overview video to learn how to create and manage gift cards using a Node.js application.

Link to section
Process the gift card order

The first step for selling a gift card is creating an order for the gift card amount and processing the payment from the buyer. You can use the Square Orders API and Payments API or a custom processing system.

For information about selling discounted gift cards when using the Orders API, see Sell discounted gift cards.

Link to section
Create or register the gift card

After processing the gift card order, call CreateGiftCard to create a digital gift card or register a physical gift card for a Square seller. Note the following about the request:

  • gift_card contains the gift card properties. The type field is required and must specify DIGITAL for a digital gift card or PHYSICAL for a physical (plastic) gift card. The gan_source and gan fields are included as follows:

    • To direct Square to generate a 16-digit GAN, omit gan_source and gan. The default gan_source value is SQUARE.

    • To provide a custom GAN, include gan_source and gan.

      • For gan_source, specify OTHER.

      • For gan, provide a custom GAN containing 8 to 20 alphanumeric characters. The GAN must be unique for the seller and cannot start with the same bank identification number (BIN) as major credit cards. For more information, see Custom GANs.

    • To register a physical gift card that the seller previously ordered from Square, include gan and provide the GAN that is printed on the gift card. The gift card must be unused.

  • location_id is the ID of the reporting location to use when gift card sales are processed. If needed, call ListLocations to get the location ID. Gift cards can be redeemed at any of the seller's locations.

  • idempotency_key is a unique ID for the request that can be optionally included to ensure idempotency.

The following example request creates a digital card and directs Square to generate the GAN:

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: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "gift_card": {
      "type": "DIGITAL"
    },
    "location_id": "{LOCATION_ID}",
    "idempotency_key": "{UNIQUE_KEY}"
  }'
Try in API Explorer

The following example request creates a digital gift card with a custom GAN:

Create Gift Card
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
curl https://connect.squareupsandbox.com/v2/gift-cards \
  -X POST \
  -H 'Square-Version: 2023-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "gift_card": {
      "type": "DIGITAL",
      "gan_source": "OTHER",
      "gan": "I82AWQ4235KIA8"
    },
    "location_id": "{LOCATION_ID}",
    "idempotency_key": "{UNIQUE_KEY}"
  }'
Try in API Explorer

Link to section
Activate the gift card with an initial balance

After creating or registering the gift card, call CreateGiftCardActivity and specify the ACTIVATE type with the corresponding activate_activity_details field. The details you provide depend on how your application processes the gift card order. You can use the gift_card_id or gift_card_gan to activate a gift card.

  • Orders API and Payments API. If your application uses the Orders API and Payments API to process the order, provide the following information for activate_activity_details:

    • order_id with the ID of the gift card order.

    • line_item_uid with the UID of the GIFT_CARD line item. Square reads the order and determines the amount to add to the gift card balance.

    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-03-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}"
      }
    }
  }'
    Try in API Explorer

    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).


  • Non-Square APIs. If your application uses a custom order processing system, provide the following information for activate_activity_details:

    • amount_money with the amount to add to the gift card balance.

    • buyer_payment_instrument_ids with any payment instrument IDs processed for the gift card order, such as a card ID or bank account ID. Square uses this information to perform compliance checks.

    • reference_id (optional) with an ID that associates the activity with an entity in your ordering or payment processing system.

    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: 2023-03-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": [
          "card-id-1",
          "card-id-2"
        ],
        "reference_id": "client-side-example-reference-id"
      }
    }
  }'
    Try in API Explorer

After a gift card is activated, the gift card holder can redeem the gift card for a purchase and add money to the gift card. In addition, gift cards can be linked with customer profiles and used for card-on-file payments.

Note the following considerations when working with physical gift cards:

  • Sellers can order a pack of Square gift cards in the .

  • Testing physical gift cards in the Square Sandbox 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 profiles setting current if the card is reused.

Link to section
Delivering digital gift cards

Buyers can purchase gift cards for themselves or for another recipient.

When digital gift cards are created using the API, the developer is 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.

Note that when digital gift cards are sold using Square products (such as the ), Square emails the digital gift card to both the seller and the gift card recipient. The email provides gift card information, including the redemption code (a 16-digit GAN) that buyers use to make purchases with the gift card, as shown in the following example.

An example digital gift card that Square emails to customers, which includes the 16-digit redemption code that buyers use to make purchases with the gift card.

Link to section
Flow diagram: Selling a gift card (Orders API integration)

The following diagram represents the typical process for selling a gift card when your application integrates with the Orders API and Payments API. After collecting payment for the gift card order, you must create (or register) the gift card and then activate it with an initial balance. Note that you use information from the order to create the payment and activate the gift card.

A diagram showing the typical process flow for the frontend client, backend server, and Square when activating a gift card using Orders API and Payments API integration.

Link to section
Reloading gift cards

Gift cards that are in the ACTIVE state can be loaded with additional funds. Reloading a gift card includes the following high-level steps:

Note

For detailed steps that show how to reload a gift card, see the Add money to the gift card step in Walkthrough 2: Use a Gift Card.

For a diagram that shows the end-to-end process, see Flow diagram: Reloading a gift card (Orders API integration).

Link to section
Process the gift card order

The first step for reloading a gift card is creating an order for the amount to add to the gift card and processing the payment from the buyer. You can use the Square Orders API and Payments API or a custom processing system.

The gift card holder typically provides the GAN and specifies the amount to add. When you obtain the GAN, you can optionally call RetrieveGiftCardFromGAN to get the current gift card balance to display to the buyer.

Link to section
Load the gift card with additional funds

After processing the order for additional gift card funds, call CreateGiftCardActivity and specify the LOAD type with the corresponding load_activity_details field. The details you provide depend on how your application processes the order for the additional funds. You can use the gift_card_id or gift_card_gan to reload a gift card.

  • Orders API and Payments API. If your application uses the Orders API and Payments API to process the order, provide the following information for load_activity_details:

    • order_id with the ID of the gift card order.

    • line_item_uid with the UID of the GIFT_CARD line item. Square reads the order and determines the amount to add to the gift card balance.

    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-03-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": "LOAD",
      "location_id": "{LOCATION_ID}",
      "load_activity_details": {
        "order_id": "{ORDER_ID}",
        "line_item_uid": "{LINE_ITEM_UID}"
      }
    }
  }'
    Try in API Explorer

    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).


  • Non-Square APIs. If your application uses a custom order processing system, provide the following information for load_activity_details:

    • amount_money with the amount to add to the gift card balance.

    • buyer_payment_instrument_ids with any payment instrument IDs processed for the gift card order, such as a card ID or bank account ID. Square uses this information to perform compliance checks.

    • reference_id (optional) with an ID that associates the activity with an entity in your order or payment processing system.

    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: 2023-03-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": "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": [
          "card-id-1",
          "card-id-2"
        ]
      }
    }
  }'
    Try in API Explorer

The gift card activity in the response contains information about the gift card, including the updated balance. You can also retrieve a gift card to check the gift card balance.

A seller can also use Square Point of Sale or the to add money to a gift card. The resulting gift card activity is included in ListGiftCardActivity responses.

Link to section
Flow diagram: Reloading a gift card (Orders API integration)

The following diagram represents the typical process for reloading a gift card when your application integrates with the Orders API and Payments API. After collecting the payment for the gift card order for the amount to add to the gift card, you create a LOAD activity to update the gift card balance. Note that you use information from the order to create the payment and load the gift card.

A diagram showing the typical process flow for the frontend client, backend server, and Square when reloading a gift card using Orders API and Payments API integration.

Link to section
Redeeming gift cards for purchases

Gift cards that are in the ACTIVE state can be redeemed to pay for a purchase. The steps for redeeming a gift card depend on whether the application uses the Square Payments API to process gift card payments.

  • Payments API. If your application uses the Payments API, Square automatically creates a REDEEM activity after the payment is successfully completed, which records the redemption and updates the gift card balance. You do not need to call CreateGiftCardActivity directly. For information about creating gift card payments, see Use a gift card as a payment source in the Payments API.

  • Non-Square API. If your application does not use the Payments API, you must call CreateGiftCardActivity after the payment is successfully completed to create a REDEEM activity. The application is responsible for making this call to ensure that the gift card balance is accurate.

    Provide the following information for redeem_activity_details in the request:

    • amount_money with the amount to remove from the gift card balance. In this example, the gift card was redeemed to pay for a $3 purchase.

    • reference_id (optional) with an ID that associates the activity with an entity in your order or payment processing system.

      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: 2023-03-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"
      }
    }
  }'
      Try in API Explorer

      Note

      You can provide the gift_card_id or gift_card_gan in your CreateGiftCardActivity request.

    The CreateGiftCardActivity response contains a GiftCardActivity object, as shown in the following example:

    • 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_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",
      "status": "COMPLETED"
   }
  }
}

    The gift card activity contains information about the gift card, including the updated balance. You can also retrieve a gift card to check the gift card balance.

    For steps that show how to redeem a gift card, see Walkthrough 2: Use a Gift Card.

Link to section
Use a gift card as a payment source in the Payments API

If your application uses the Payments API to process payments, a Square gift card can be used as the payment source for a CreatePayment request. For the source_id field in the request, you can specify either a gift card ID or a payment token generated from the Web Payments SDK or In-App Payments SDK.

  • Gift card ID. To get a gift card ID and check the gift card balance and state, your application can collect the GAN from the buyer and then call RetrieveGiftCardFromGAN.

    For payments from a gift card on file, call ListGiftCards with the customer_id query parameter to retrieve the customer's gift cards on file. If you need to get the customer ID, call SearchCustomers. For more information, see Manage gift cards on file.

    The following example CreatePayment request specifies a gift card ID as the source_id for a $13.50 gift card payment:

    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-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "gftc:0ade6b80ff7e45f09bebada1bc16e3e5",
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 1350,
      "currency": "USD"
    },
    "order_id": "PVGawfEPg4I5BmPiNT5l8oazyh4F",
    "location_id": "LNCXKAGRF5PWG"
  }'
    Try in API Explorer

  • Payment token. To get a payment token using the frontend/backend model, your frontend application uses the Web Payments SDK or In-App Payments SDK to collect the GAN from the buyer and generate a payment token for the gift card. Your backend service can optionally use the payment token to call RetrieveGiftCardFromNonce and check the gift card balance and state before you call the CreatePayment endpoint. Note that neither the Web Payments SDK, In-App Payments SDK, nor CreatePayment response exposes the gift card ID or full GAN.

    The following example CreatePayment request specifies a payment token as the source_id for a $13.50 gift card payment. Note that this example uses the test payment token that represents a Square gift card in the Sandbox environment.

    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-03-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "source_id": "cnon:gift-card-nonce-ok",
    "idempotency_key": "{UNIQUE_KEY}",
    "amount_money": {
      "amount": 1350,
      "currency": "USD"
    },
    "order_id": "PVGawfEPg4I5BmPiNT5l8oazyh4F",
    "location_id": "LNCXKAGRF5PWG"
  }'
    Try in API Explorer

    Note

    Square also provides the cnon:gift-card-nonce-insufficient-funds and cnon:gift-card-nonce-insufficient-permission test payment tokens for Sandbox testing.

The following is an example CreatePayment response. For gift card payments, Square assigns the following card settings:

  • card_brand is SQUARE_GIFT_CARD

  • card_type is DEBIT

  • prepaid_type is PREPAID

Note that the receipt URL does not work when testing in the Sandbox.

  • 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
  • 45
  • 46
  • 47
  • 48
  • 49
  • 50
  • 51
  • 52
{
  "payment": {
    "id": "l8753iAyu16jip83wkGHTSCNCMTZY",
    "created_at": "2021-09-10T00:11:48.384Z",
    "updated_at": "2021-09-10T00:11:49.311Z",
    "amount_money": {
      "amount": 1350,
      "currency": "USD"
    },
    "status": "COMPLETED",
    "delay_duration": "PT168H",
    "source_type": "CARD",
    "card_details": {
      "status": "CAPTURED",
      "card": {
        "card_brand": "SQUARE_GIFT_CARD",
        "last_4": "2013",
        "exp_month": 12,
        "exp_year": 2099,
        "fingerprint": "sq-1-axn6GGaDl7bZMS5LAPsvaiO63DehyOYFcyo-wAvBCGegIDgthtpC0u8eerS2hi8DWA",
        "card_type": "DEBIT",
        "prepaid_type": "PREPAID",
        "bin": "778332"
      },
      "entry_method": "KEYED",
      "auth_result_code": "0",
      "card_payment_timeline": {
        "authorized_at": "2021-09-10T00:11:48.443Z",
        "captured_at": "2021-09-10T00:11:49.312Z"
      }
    },
    "location_id": "LNCXKAGRF5PWG",
    "order_id": "PVGawfEPg4I5BmPiNT5l8oazyh4F",
    "risk_evaluation": {
      "created_at": "2021-09-10T00:11:48.959Z",
      "risk_level": "NORMAL"
    },
    "total_money": {
      "amount": 1350,
      "currency": "USD"
    },
    "approved_money": {
      "amount": 1350,
      "currency": "USD"
    },
    "receipt_number": "l875",
    "receipt_url": "https://squareup.com/receipt/preview/l8753iAyu16jip83wkGHTSCNCMTZY",
    "delay_action": "CANCEL",
    "delayed_until": "2021-09-17T00:11:48.384Z",
    "version_token": "uv2Q6v5IZqCbUyVWo4TOFziAAzK383Wli9MzGMs2O5C6o"
  }
}

For information about how to configure the accept_partial_authorization and autocomplete payment fields to accept partial payments with gift cards, see Partial Payment Authorizations.

When your application uses the Payments API to process a gift card payment, Square automatically creates the REDEEM activity to update the gift card balance. For more information, see Redeem a gift card for a purchase or Walkthrough 2: Use a Gift Card.

Link to section
Requirements and limitations

The following requirements, limitations, and other considerations apply when working with the Gift Cards API and Gift Card Activities API:

  • Sandbox testing limitations. In the Sandbox environment, you can test gift card payments by providing a gift card ID as the source_id for the CreatePayment request. After the payment is completed, Square updates the gift card balance. For more information, see Use a gift card as a payment source in the Payments API.

    However, you should be aware of the following Sandbox testing limitations:

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

    • To test taking gift card payments with the Web Payments SDK or In-App Payments SDK, you can use a test payment token that represents a Square gift card (for example, cnon:gift-card-nonce-ok) as the source_id for a CreatePayment request. Alternatively, you can generate a payment token using the test card value of 7783 3200 0000 0000.

      Although these test values can be used to complete a payment using the Payments API, they are not tied to any gift cards. Therefore, Square does not update any gift card balance and the payment tokens cannot be used to retrieve a gift card with the RetrieveGiftCardFromNonce endpoint.

  • Gift card orders.

    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).

  • No cross-tender refunds using the Refunds API. Sellers can use Square Point of Sale or the to refund a cross-tender payment (from a credit card or a different gift card) to a gift card, which creates a REFUND activity. However, the Refunds API does not currently support cross-tender refunds to a gift card.

    The Gift Card Activities API does not currently support cross-tender refunds to a gift card for payments processed by Square. Applications that use a custom payment processing system can create an UNLINKED_ACTIVITY_REFUND activity to update the gift card balance for a cross-tender refund.

  • No application fees. Developers cannot collect application fees for gift card payments. The CreatePayment request for a Square gift card payment cannot contain the app_fee_money field.

  • Activity history. ACTIVATE, CLEAR_BALANCE, and IMPORT activities that occurred before March 2, 2016, are not included in ListGiftCardActivities results. This date limit also applies when viewing activity history in the .

  • reporting. When you load or redeem a gift card using the Orders API and Payments API, the reports include these transactions. In contrast, there is no reporting when loading and redeeming gift cards using non-Square APIs.

    All activated gift cards are listed in the regardless of the system used to process the gift card order. However, if the gift card order was processed with non-Square APIs, the Receipt link to the transaction is not available from the gift card's Activity card in the Gift Cards section.

Link to section
Custom GANs

The CreateGiftCard endpoint allows you to specify a custom GAN when you create a gift card. The custom GAN that you provide in the request must meet the following requirements:

  • The custom GAN must be unique for the Square seller account.

  • The custom GAN must contain 8 to 20 alphanumeric characters.

  • The custom GAN cannot start with the same bank identification number (BIN) pattern as major credit cards (such as Visa, Mastercard, and American Express).

Gift cards created with a custom GAN have a gan_source of OTHER. For an example CreateGiftCard request that shows how to create a gift card with a custom GAN, see Create or register the gift card.

Custom GANs can be used to enable scenarios that are not possible with Square-assigned GANs. For example, they can be used to enable gift card redemptions across multiple Square sellers and channels, attach a value to non-gift card items such as tickets, and allow sellers to accept gift cards created from external sites. Gift cards with custom GANs can be redeemed just like gift cards with Square-assigned GANs.

Buyers use GANs to make gift card payments and check the gift card balance. It is the responsibility of the developer to ensure the security of their custom GANs. For example, to mitigate the risk of fraud, avoid using repeatable patterns or GANs that are easy to guess (such as 12345678).

You should be aware of the following limitations for gift cards with custom GANs:

  • After using the LinkCustomerToGiftCard endpoint to add a gift card on file for a customer profile, the customer ID is added to the customer_ids field of the gift_card object. However, linked gift cards that have custom GANs are not currently visible as a card on file for the customer in Square products, such as Square Point of Sale or the .

  • Gift cards with custom GANs cannot receive cross-tender refunds in Square Point of Sale or the . Currently, cross-tender refunds are supported only for gift cards with Square-assigned GANs in Square Point of Sale. (Note that the Refunds API does not support cross-tender refunds for any gift card type.)

Link to section
Third-party gift cards

If a seller previously purchased gift cards 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 cannot be reloaded.

For third-party gift cards, the gan can contain a maximum of 255 characters and gan_source is OTHER.

Link to section
Compliance limits

Square enforces the following compliance limits for gift card activities that load funds onto digital or physical gift cards:

  • Maximum balance amount per gift card. The maximum amount for a gift card balance.

  • Maximum load amount per gift card per day. The maximum amount that can be loaded onto a gift card in a 24-hour period.

  • Maximum load amount per payment card per day. The maximum amount that a single payment card can load onto gift cards in a 24-hour period.

  • Maximum outstanding balance amount per seller. The maximum amount of the total outstanding balance across all gift cards issued for a single seller.

If a limit is exceeded, the CreateGiftCardActivity endpoint returns an error and does not complete the activity.

Link to section
Per-country compliance limits

The following tables contain the per-country limits that are enforced by Square.

Limits for Australia (AU)
Amount in AUD
Maximum balance amount per gift card
The maximum amount for a gift card balance.
$2,000
Maximum load amount per gift card per day
The maximum amount that can be loaded onto a gift card in a 24-hour period.
$2,000
Maximum load amount per payment card per day
The maximum amount that a single payment card can load onto gift cards in a 24-hour period.
$10,000
Maximum outstanding balance amount per seller
The maximum amount of total outstanding balance across all gift cards issued for a single seller.
Not applicable
Limits for Canada (CA)
Amount in CAD
Maximum balance amount per gift card
The maximum amount for a gift card balance.
$2,000
Maximum load amount per gift card per day
The maximum amount that can be loaded onto a gift card in a 24-hour period.
$2,000
Maximum load amount per payment card per day
The maximum amount that a single payment card can load onto gift cards in a 24-hour period.
$10,000
Maximum outstanding balance amount per seller
The maximum amount of total outstanding balance across all gift cards issued for a single seller.
Not applicable
Limits for France (FR) and Ireland (IR)
Amount in EUR
Maximum balance amount per gift card
The maximum amount for a gift card balance.
750 EUR
Maximum load amount per gift card per day
The maximum amount that can be loaded onto a gift card in a 24-hour period.
750 EUR
Maximum load amount per payment card per day
The maximum amount that a single payment card can load onto gift cards in a 24-hour period.
7.500 EUR / 7,500 EUR
Maximum outstanding balance amount per seller
The maximum amount of total outstanding balance across all gift cards issued for a single seller.
Not applicable
Limits for Japan (JP)
Amount in YEN
Maximum balance amount per gift card
The maximum amount for a gift card balance.
¥50,000
Maximum load amount per gift card per day
The maximum amount that can be loaded onto a gift card in a 24-hour period.
¥50,000
Maximum load amount per payment card per day
The maximum amount that a single payment card can load onto gift cards in a 24-hour period.
¥1,000,000
Maximum outstanding balance amount per seller
The maximum amount of total outstanding balance across all gift cards issued for a single seller.
¥10,000,000
Limits for Spain (ES)
Amount in EUR
Maximum balance amount per gift card
The maximum amount for a gift card balance.
250 EUR (card cannot be reloaded)
Maximum load amount per gift card per day
The maximum amount that can be loaded onto a gift card in a 24-hour period.
250 EUR (card cannot be reloaded)
Maximum load amount per payment card per day
The maximum amount that a single payment card can load onto gift cards in a 24-hour period.
7,500 EUR
Maximum outstanding balance amount per seller
The maximum amount of total outstanding balance across all gift cards issued for a single seller.
Not applicable
Limits for the United Kingdom (UK)
Amount in GBP
Maximum balance amount per gift card
The maximum amount for a gift card balance.
£750
Maximum load amount per gift card per day
The maximum amount that can be loaded onto a gift card in a 24-hour period.
£750
Maximum load amount per payment card per day
The maximum amount that a single payment card can load onto gift cards in a 24-hour period.
£7,500
Maximum outstanding balance amount per seller
The maximum amount of total outstanding balance across all gift cards issued for a single seller.
Not applicable
Limits for the United States (US)
Amount in USD
Maximum balance amount per gift card
The maximum amount for a gift card balance.
$2,000
Maximum load amount per gift card per day
The maximum amount that can be loaded onto a gift card in a 24-hour period.
$2,000
Maximum load amount per payment card per day
The maximum amount that a single payment card can load onto gift cards in a 24-hour period.
$10,000
Maximum outstanding balance amount per seller
The maximum amount of total outstanding balance across all gift cards issued for a single seller.
Not applicable

Link to section
Compliance limit errors

Square returns the following errors when compliance limits are exceeded.

  • Maximum load amount per gift card per day:

    • 1
    • 2
    • 3
    • 4
    • 5
    {
  "code": "PAYMENT_LIMIT_EXCEEDED",
  "detail": "The gift card limit for increasing balance reached.",
  "category": "PAYMENT_METHOD_ERROR"
}

  • Maximum balance amount per gift card:

    • 1
    • 2
    • 3
    • 4
    • 5
    {
  "code": "BAD_REQUEST",
  "detail": "Cannot load balance on this giftcard as the card maximum value has been reached",
  "category": "INVALID_REQUEST_ERROR"
}

  • Maximum load amount per payment card per day:

    • 1
    • 2
    • 3
    • 4
    • 5
    {
  "code": "BAD_REQUEST",
  "detail": "Load amount exceeds maximum buyer daily amount.",
  "category": "INVALID_REQUEST_ERROR"
}

  • Maximum outstanding balance amount per seller:

    • 1
    • 2
    • 3
    • 4
    • 5
    {
  "code": "PAYMENT_LIMIT_EXCEEDED",
  "detail": "The merchant cannot accrue any more liability.",
  "category": "PAYMENT_METHOD_ERROR"
}

Link to section
Migration notes

The following migration notes apply to the Gift Cards API or Gift Card Activities API.

Link to section
Activity type is changed from UNLINKED_ACTIVITY_REFUND to REFUND for cross-tender refunds made from Square products

Effective date: 2022-06-16

All cross-tender refunds made from Square Point of Sale or the are now processed as REFUND activities instead of UNLINKED_ACTIVITY_REFUND activities. This type of refund occurs when a gift card is refunded for a payment that was processed by Square and paid for using a credit card or different gift card. The resulting REFUND activity has a payment_id but does not have a redeem_activity_id.

Existing UNLINKED_ACTIVITY_REFUND activities that represent cross-tender refunds made from Square Point of Sale or the are now also returned as REFUND activities for a ListGiftCardActivities request. This change applies to all Square versions.

However, new and existing UNLINKED_ACTIVITY_REFUND activities that are explicitly created by third-party applications continue to be returned as UNLINKED_ACTIVITY_REFUND activities.

Link to section
Related topics

On this page