Applies to: Gift Cards API | Gift Card Activities API | Orders API | Locations API | Payments API | Web Payments SDK
Learn how to reload Square gift cards with additional funds using the Gift Card Activities API.
Developers can use Square APIs to reload Square gift cards with additional funds. A gift card must be in the ACTIVE
state to add more funds to the balance.
Reloading a gift card includes the following high-level steps:
- Process the order for the gift card amount.
- Load the gift card with additional funds by calling
CreateGiftCardActivity
.
The first step for reloading a gift card is to create an order for the amount to add to the gift card and then collect the payment from the buyer.
If your application uses the Orders API to process orders, make sure to include a GIFT_CARD
line item in your CreateOrder
request (see an example). You use the order ID, line item GUID, and location ID in your CreateGiftCardActivity
request.
After the gift card order is paid, call CreateGiftCardActivity and provide the following information for gift_card_activity
in the request:
gift_card_id
orgift_card_gan
- The gift card ID or GAN. Applications typically collect the GAN from the buyer or use a card on file. Otherwise, you can retrieve the gift card.type
- SpecifyLOAD
.load_activity_details
- Details about theLOAD
activity. The information you provide depends on how your application processes orders:location_id
- The location where the activity occurred.
If your application uses the Orders API to process orders, provide the following information for load_activity_details
in the request:
order_id
- The ID of the gift card order.line_item_uid
- The UID of theGIFT_CARD
line item. Square reads the order and determines the amount to add to the gift card balance.
Create gift card activity
If your application uses a custom order processing system, provide the following information for load_activity_details
:
amount_money
- The amount to add to the gift card balance.buyer_payment_instrument_ids
- 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
- An optional ID that associates the activity with an entity in your ordering or payment processing system.
Create gift card activity
If the CreateGiftCardActivity
request is successful, Square returns a gift card activity similar to the following example. The activity contains information about the gift card, including the updated balance.
{
"gift_card_activity": {
"id": "gcact_3a777d41a9cb40b5b00ecddf505ceab9",
"type": "LOAD",
"location_id": "LNCXKAEXAMPLE",
"created_at": "2023-07-26T23:47:04.000Z",
"gift_card_id": "gftc:0cded29ae32b4e5591b2d6c8dEXAMPLE",
"gift_card_gan": "7783320030000000",
"gift_card_balance_money": {
"amount": 6172,
"currency": "USD"
},
"load_activity_details": {
"amount_money": {
"amount": 5000,
"currency": "USD"
},
"order_id": "gsIEmrXRvrlm9JovSp2J5EXAMPLE",
"line_item_uid": "iWftNgaqX7P07nEXAMPLE"
}
}
}
Applications that create and manage orders using the Orders API can provide information from the gift card order when creating a LOAD
activity.
The following diagram represents the typical process of reloading a gift card for applications that integrate with the Orders API and Payments API. The application uses the Orders API to create a gift card order (with a GIFT_CARD
line item that specifies the gift card amount) and the Web Payments SDK and Payments API to collect payment for the gift card order. The application then calls the Gift Card Activities API to update the gift card balance.
In this integrated flow, information from the order is used to create the payment and reload the gift card. Square updates the gift card balance using the amount of the GIFT_CARD
line item.
Note
Applications that use a custom ordering processing system (instead of the Orders API) provide different information in the CreateGiftCardActivity
request. For more information, see Reloading gift cards when using custom order processing.
The following considerations apply to reloading gift cards:
You can retrieve a gift card if you want to check the gift card balance and state before reloading the gift card.
When creating a
LOAD
activity using Orders API integration:order_id
- The specified order must be in theCOMPLETED
state before you can activate or load the gift card.line_item_uid
- The specified line item with the gift card amount must explicitly setGIFT_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.
The ListGiftCardActivities endpoint returns activities that change the gift card balance or state. You can use the
type
query parameter to filter forLOAD
activities.Square invokes the
gift_card.updated
andgift_card.activity.created
webhook events after a gift card is reloaded.Square enforces compliance limits for activities that add funds to gift cards.
Sellers can reload gift cards using Square Point of Sale. Buyers can reload their gift cards from their Square profile.