Gift Cards API and Gift Card Activities API Overview
Square gift cards allow sellers to offer a complete gifting program that can boost sales and attract new customers. Gift cards can be purchased online or in person and redeemed at all of the seller's locations. Buyers might choose to send digital cards to friends or family and introduce them to the seller's business.
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, and link or unlink customers with gift cards to manage gift cards on file. The core component of the Gift Cards API is the
GiftCard
object.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. The Gift Card Activities API provides built-in integration with the Orders API and the Payments API. The core component of the Gift Card Activities API is the
GiftCardActivity
object.
Developers can also subscribe to webhook notifications about gift card events.
Sellers use Square Point of Sale and the Seller Dashboard to sell, redeem, track, or reload Square gift cards. In addition, sellers can publish an eGift Card Order Site where buyers can purchase gift cards and buyers can view and manage their gift cards from their Square profile.
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, as shown in the following example:
All gift cards have both an ID and a gift card number (GAN), which is referred to as a redemption code. 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 the gift card is 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 redeemed for a purchase, it must be activated with a balance, which sets the state to ACTIVE
. For more information, see Sell Square Gift Cards or Redeem Square Gift Cards.
You can use the gift card ID to save gift cards on file for customers. If a gift card is linked to one or more customer profiles, the gift card includes a customer_ids
field that lists the IDs of the linked profiles.
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, as shown in the following example:
Note the following about this example gift card activity:
The
ACTIVATE
type indicates thatCreateGiftCardActivity
was called to activate a gift card.The
activate_activity_details
field contains information related to theACTIVATE
activity, such as theamount_money
associated with the activity.The
gift_card_balance_money
field shows the updated gift card balance resulting from the activity.
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 activity details.
All CreateGiftCardActivity
requests specify the activity type
and include an <activity-type>_activity_details
field that corresponds to the specified type. For example, an ACTIVATE
activity contains an activate_activity_details
field and a LOAD
activity contains a load_activity_details
field.
You can use the CreateGiftCardActivity
endpoint to create the following activity types:
Activity type | Description |
---|---|
ACTIVATE | Activates a gift card with a balance. A gift card must be in the ACTIVE state to be used for any other activity. For more information, see Sell Square Gift Cards.Details field: activate_activity_details |
LOAD | Loads a gift card with additional funds. For more information, see Reload Square Gift Cards. Details field: load_activity_details |
REDEEM | Redeems 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 Square Gift Cards.Details field: redeem_activity_details |
CLEAR_BALANCE | Sets 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 |
DEACTIVATE | Permanently blocks 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_INCREMENT | Increases a gift card balance when the adjustment isn't 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_DECREMENT | Decreases a gift card balance when the adjustment isn't 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 |
REFUND | Adds 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 Seller Dashboard. 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 don't 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 don't have a payment_id .Details field: refund_activity_details |
UNLINKED_ACTIVITY_REFUND | Adds money to a gift card from a refunded transaction that wasn't 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 isn't being refunded to the same gift card used for payment. Details field: unlinked_activity_refund_activity_details |
Note
The CreateGiftCardActivity
endpoint doesn't support all activity types. For more information, see Unsupported gift card activities.
To track activities, you can call ListGiftCardActivities
to view all activities or a filtered set of activities. The response includes gift card activities initiated by sellers and buyers using Square products, third-party applications calling Square APIs, and Square. For more information, see List gift card activities.
Sellers use Square Point of Sale or the Seller Dashboard 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 Seller Dashboard. Buyers can view and manage their gift cards from their Square profile.
For applications that use the Orders API and Payments API to process orders and payments, Square provides integrated gift card workflows.
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 API | order_id line_item_uid |
Custom (non-Square APIs) | amount_money buyer_payment_instrument_ids reference_id (optional) |
For more information, see Sell Square Gift Cards and Reload Square Gift Cards.
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 API | No 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 Redeem Square Gift Cards.
The following requirements, limitations, and other considerations apply when working with the Gift Cards API and Gift Card Activities API:
OAuth permissions - Applications that use OAuth require OAuth permissions to integrate with the Gift Cards API and Gift Card Activities API. The permissions needed depend on your application's functionality.
GIFTCARDS_READ
to perform the following tasks:GIFTCARDS_WRITE
to perform the following tasks:PAYMENTS_WRITE
andORDERS_WRITE
to activate gift cards or reload gift cards using Orders API integration.CUSTOMERS_READ
to charge a gift card on file.
To integrate with other Square APIs, your application might need additional permissions. For a list of permissions required for each Square API endpoint, see OAuth Permissions Reference.
Gift card delivery - It's the responsibility of the developer to deliver information for digital gift cards created using the API. For more information, see Delivering digital gift cards.
Unsupported gift card activities - The
CreateGiftCardActivity
endpoint cannot be used to create the following activity types:BLOCK
orUNBLOCK
- Square manages these activities while processing chargeback transactions for disputed payments.IMPORT
orIMPORT_REVERSAL
- Sellers must work with Square Support to import third-party gift cards or reverse previously imported gift cards.TRANSFER_BALANCE_TO
orTRANSFER_BALANCE_FROM
- Square creates these activities when a buyer transfers money between gift cards linked to their Square profile.
These activity types are included in
ListGiftCardActivities
results and invokegift_card.activity.created
andgift_card.updated
webhook events.Ensure the security of custom GANs - When using custom GANs, it's the responsibility of the developer to ensure the security of the custom GANs. For example, to mitigate the risk of fraud, avoid using repeatable patterns or GANs that are easy to guess (such as 12345678). For information about using custom GANs, see Custom GANs.
Customer linking limits - The following limits apply when saving gift cards on file for customers:
The maximum number of gift cards you can link to a customer profile is 50.
The maximum number of customer profiles you can link to a gift card is 10.
Sandbox testing limitations - The following testing limitations apply to testing gift card payments in the Square Sandbox:
Creating and managing physical gift cards isn't supported.
The Virtual Terminal doesn't accept gift card payments.
The Web Payments SDK and In-App Payments SDK only accept Sandbox test values provided by Square. These values aren't tied to any gift cards in your account, so you cannot check whether the balance of the gift card is updated.
For more information, see Testing gift card payments in the Sandbox.
Gift card orders - The following considerations apply when using Orders API integration to create
ACTIVATE
andLOAD
activities:The order must be in the
COMPLETED
state before you can activate or load the gift card.The line item with the gift card amount must specify
GIFT_CARD
as theitem_type
. Otherwise, the order isn't processed as a gift card sale and you cannot use Orders API integration to activate or load the gift card.If a gift card order is later refunded, the Refunds API doesn't automatically update the gift card balance. To deduct the funds from the balance, call
CreateGiftCardActivity
and create anADJUST_DECREMENT
activity with thePURCHASE_WAS_REFUNDED
reason. Note that the Refunds API does update the balance after refunding a payment from a gift card.
No cross-tender refunds using the Refunds API - Sellers can use Square Point of Sale or the Seller Dashboard 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 doesn't currently support cross-tender refunds to a gift card.The Gift Card Activities API doesn't 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 theapp_fee_money
field.Seller Dashboard reporting - When third-party applications use Orders API or Payments API integration to reload or redeem a gift card, the Seller Dashboard reports include these transactions. In contrast, there is no reporting when reloading and redeeming gift cards using non-Square APIs.
All activated gift cards are listed in the Seller Dashboard 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 isn't available from the gift card's Activity card in the Gift Cards section.
Physical (plastic) gift card considerations - Note the following when working with physical gift cards:
Physical gift cards are imprinted with a 16-digit GAN and a barcode. The GAN is numeric only and starts with 778273.
To sell physical gift cards, the seller must have previously ordered the gift card from Square and the gift card must be unused. Sellers can order a pack of Square gift cards in the Seller Dashboard.
Testing physical gift cards in the Square Sandbox isn't 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.
Activity history -
ACTIVATE
,CLEAR_BALANCE
, andIMPORT
activities that occurred before March 2, 2016, aren't included inListGiftCardActivities
results or when viewing the activity history in the Seller Dashboard.
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).
A BIN used by Square gift cards: 778273 (physical) or 778332 (digital).
For an example CreateGiftCard
request that shows how to create a gift card with a custom GAN, see Create or register the gift card. Gift cards created with a custom GAN have a gan_source
of OTHER
.
Custom GANs can enable scenarios that aren't possible with Square-assigned GANs. For example, they can be used for gift card redemptions across multiple Square sellers and channels, to attach a value to non-gift-card items such as tickets, and to allow sellers to accept gift cards created by 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's 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 thecustomer_ids
field of thegift_card
object. However, linked gift cards that have custom GANs aren't currently visible as a card on file for the customer in Square products, such as Square Point of Sale or the Seller Dashboard.Gift cards with custom GANs cannot receive cross-tender refunds in Square Point of Sale or the Seller Dashboard. Currently, cross-tender refunds are supported only for gift cards with Square-assigned GANs in Square Point of Sale. Note that the Refunds API doesn't support cross-tender refunds for any gift card type.
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
field can contain a maximum of 255 characters and gan_source
is OTHER
.
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 doesn't complete the activity.
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 |
Square returns the following errors when compliance limits are exceeded.
Maximum load amount per gift card per day:
Maximum balance amount per gift card:
Maximum load amount per payment card per day:
Maximum outstanding balance amount per seller:
The following migration notes apply to the Gift Cards API or Gift Card Activities API.
Effective date: 2022-06-16
All cross-tender refunds made from Square Point of Sale or the Seller Dashboard 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 doesn't have a redeem_activity_id
.
Existing UNLINKED_ACTIVITY_REFUND
activities that represent cross-tender refunds made from Square Point of Sale or the Seller Dashboard 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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.