Applies to: Gift Cards API | Gift Card Activities API | Orders API | Payments API | Refunds API | Customers API | Web Payments SDK | In-App Payments SDK
Use the Gift Cards API and Gift Card Activities API to create and manage Square gift cards.
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 can send gift cards to friends and family to introduce them to a seller's business.
Developers use the Gift Cards API and Gift Card Activities API to integrate gift cards into their applications. Watch the following video to see how the APIs work:
You can also send Square GraphQL queries for read-only access to gift card data and use webhook events to keep track of activities.
Note
Sellers use Square Point of Sale and the Seller Dashboard to sell, redeem, track, or reload Square gift cards. Sellers can publish an eGift Card Order Site where buyers can purchase gift cards.
Buyers can view and manage their gift cards from their Square profile.
The following requirements, limitations, and other considerations apply when working with the Gift Cards API and Gift Card Activities API:
OAuth permissions - Applications using OAuth require
GIFTCARDS_READ
for read operations andGIFTCARDS_WRITE
for write operations.Additional permissions might be required in gift card flows. For example:
CUSTOMERS_READ
- To get a customer ID to link a gift card.PAYMENTS_WRITE
- To charge a gift card on file.PAYMENTS_WRITE
andORDERS_WRITE
- To activate or reload gift cards using Orders API integration.
Learn more about OAuth and endpoint permission requirements.
Gift card delivery - The developer is responsible for delivering information for digital gift cards created using the Gift Cards API.
Security of custom GANs - The developer is responsible for ensuring the security of custom GANs. For example, to mitigate the risk of fraud, don't use repeatable patterns or GANs that are easy to guess (such as 12345678).
No application fees - Developers cannot collect application fees for gift card payments.
CreatePayment
returns aBAD_REQUEST
error if theapp_fee_money
field is included in a request to create a Square gift card payment.
Load fees - Sellers in the following countries pay 2.5% of the amount added to a Square gift card, in addition to standard payment processing rates:
- Australia
- Canada
- United States
Load fees apply to
ACTIVATE
,LOAD
, andADJUST_INCREMENT
activities. There are no fees when a gift card is redeemed or refunded. For more information, see Gift cards pricing.Square deducts or refunds load fees in seller payouts. To see all load fee deductions and refunds for a given payout, call ListPayoutEntries and iterate through the results to find following entry types:
Customer linking limits - When saving gift cards on file:
- 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.
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's 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.
Square API integration - Additional requirements and limitations apply when integrating with other Square APIs.
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.
You can create gift cards, retrieve gift card information, and manage gift cards on file.
The following example CreateGiftCard
request creates a DIGITAL
gift card. You can also use this endpoint to register a PHYSICAL
gift card.
Create gift card
New gift cards have a PENDING
state and zero balance. After creating a gift card, call CreateGiftCardActivity
to activate it with an initial balance before first use. For steps, see Sell Square Gift Cards.
The id
and gan
fields are used in API requests. For example, use:
gan
with the Web Payments SDK or In-App Payments SDK to generate asource_id
for a gift card payment in aCreatePayment
request.id
as thesource_id
for a gift card on file payment in aCreatePayment
request.id
as thedestination_id
when issuing store credit in aCreateRefund
request. This is an alternative method for activating a gift card.
You can activate a gift card with a balance, load additional funds, redeem the gift card for purchases, and create other activities that change the gift card balance or state.
A CreateGiftCardActivity
request defines a specific activity type
and includes a corresponding <activity-type>_activity_details
field that provides the information needed to create the activity. The following example creates an ACTIVATE
type based on the provided activate_activity_details
:
Create gift card activity
Built-in integration with other Square APIs helps simplify activate, reload, redeem, and refund flows.
Gift card activities are used to manage a gift card's balance or state. You can use the CreateGiftCardActivity
endpoint to create the following activity types:
Activity type | Description |
---|---|
| Activates a gift card with a balance. A gift card must be in the Details field: activate_activity_details |
| Loads a gift card with additional funds. For more information, see Reload Square Gift Cards. Details field: load_activity_details |
| 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 Details field: redeem_activity_details |
| 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 |
| 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 |
| 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 Details field: adjust_increment_activity_details |
| 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 Details field: adjust_decrement_activity_details |
| Adds money to a gift card from a refunded transaction. Refunds linked to a Square payment have a If your application uses the Refunds API to refund a payment to a gift card, Square automatically creates a Details field: refund_activity_details |
| Adds money to a gift card from a refunded transaction that wasn't paid with the same gift card. This activity type is used by applications that use a custom processing system for cross-tender gift card refunds. Details field: unlinked_activity_refund_activity_details |
You cannot use CreateGiftCardActivities
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.
However, these activity types are included in ListGiftCardActivities
results and invoke gift_card.activity.created
and gift_card.updated
webhook events.
Note
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.
Square provides integrated gift card workflows for applications that use the Orders API, Payments API, or Refunds API.
With Orders API integration, Square reads information from the order used to sell or reload a gift card. You provide an order_id
and line_item_uid
(of the GIFT_CARD
line item) when you create the ACTIVATE
or LOAD
activity. The following are typical high-level flows:
Selling a gift card - Includes creating an
ACTIVATE
activity:CreateOrder
->CreatePayment
->CreateGiftCard
->CreateGiftCardActivity
Reloading a gift card - Includes creating a
LOAD
activity:CreateOrder
->CreatePayment
->CreateGiftCardActivity
Resulting ACTIVATE
and LOAD
activities include the order_id
and line_item_uid
you provided in the CreateGiftCardActivity
request, as shown in the following examples. The amount of the GIFT_CARD
line item is added to the gift card balance.
{
"gift_card_activity": {
"id": "gcact_c24da663c0d242f5a29837d8e165bf97",
"type": "ACTIVATE",
"location_id": "M8AKAD8160XGR",
"created_at": "2024-08-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"
}
}
}
For more information, see Sell Square Gift Cards and Reload Square Gift Cards.
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.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 to a gift card.
If your application doesn't use the Orders API to process orders, you must call CreateGiftCardActivity
to create the ACTIVATE
or LOAD
activity. Provide the following activity details in the request:
amount_money
buyer_payment_instrument_ids
reference_id
(optional)
With Payments API integration, Square automatically creates a REDEEM
activity that updates the gift card balance after the payment is processed. Your application doesn't need to call CreateGiftCardActivity
.
Resulting REDEEM
activities have a payment_id
, as shown in the following example. The payment amount is deducted from the gift card balance.
{
"gift_card_activity": {
"id": "gcact_d31b4200f5174fc48cb7138aeae197d0",
"type": "REDEEM",
"location_id": "M8AKAD8160XGR",
"created_at": "2024-08-15T15:57:43.000Z",
"gift_card_id": "gftc:065fd3c6e1014c9293bd2d09475ea189",
"gift_card_gan": "7783320009623257",
"gift_card_balance_money": {
"amount": 7450,
"currency": "USD"
},
"redeem_activity_details": {
"amount_money": {
"amount": 2550,
"currency": "USD"
},
"payment_id": "9WIIrJKZXMgSF9dI7SX9pOlWy7DZY",
"status": "COMPLETED"
}
}
}
For more information, see Redeem Square Gift Cards.
For gift card payments, the card_brand
field is SQUARE_GIFT_CARD
. Note that Square supports partial payment flows using gift cards.
{
"payment": {
"id": "JaHoTpbmK8dofR9cUheOJl9dQVcZY",
"created_at": "2024-07-25T17:24:30.345Z",
"updated_at": "2024-07-25T17:24:30.444Z",
"amount_money": {
"amount": 522,
"currency": "USD"
},
"status": "COMPLETED",
"delay_duration": "PT168H",
"source_type": "CARD",
"card_details": {
"status": "CAPTURED",
"card": {
"card_brand": "SQUARE_GIFT_CARD",
"last_4": "1923",
"exp_month": 12,
"exp_year": 2050,
"fingerprint": "sq-1-y_yFcziMlsxVSomRNQZ7xBaW0F1xxE-6TbcGKl7KOoy3GI1mh094CY4_Ox5RzUN7Vg",
"card_type": "DEBIT",
"prepaid_type": "PREPAID",
"bin": "778332"
},
"entry_method": "KEYED",
"auth_result_code": "0",
"card_payment_timeline": {
"authorized_at": "2024-07-25T17:24:30.381Z",
"captured_at": "2024-07-25T17:24:30.444Z"
}
},
"location_id": "M8AKAD8160XGR",
"order_id": "sYr0y9eUZBoXd2dmXhjvDGOW0e4F",
"total_money": {
"amount": 522,
"currency": "USD"
},
"approved_money": {
"amount": 522,
"currency": "USD"
},
"receipt_url": "https://squareupsandbox.com/receipt/preview/JaHoTpbmK8dofR9cUheOJl9dQVcZY",
"delay_action": "CANCEL",
"delayed_until": "2024-08-01T17:24:30.345Z",
"application_details": {
"square_product": "ECOMMERCE_API",
"application_id": "sandbox-sq0idb-ioiyW39PwreFzwXoGyLtYg"
},
"version_token": "4WWgYqa7KXd6rIW82VkYxKF36EYkNyx4MGrq0Vxf5cm6o"
}
}
If your application doesn't use the Payments API to process payments, you must call CreateGiftCardActivity
to create the REDEEM
activity. Provide the following activity details in the request:
amount_money
reference_id
(optional)
With Refunds API integration, you can process same-tender gift card refunds and cross-tender gift card refunds. Square automatically creates a REFUND
activity that updates the gift card balance after the refund is processed. Your application doesn't need to call CreateGiftCardActivity
.
Note
You can issue a cross-tender refund to a new gift card by first calling CreateGiftCard
to create the gift card and then refunding directly to the new gift card. Doing so automatically changes the state from PENDING
to ACTIVE
.
Resulting REFUND
activities include a payment_id
if the refund is linked to a payment processed by Square and a redeem_activity_id
if the payment was redeemed from the same gift card. The refund amount is added to the gift card balance.
{
"gift_card_activity": {
"id": "gcact_5a877a9e75d840e990aae654173ed655",
"type": "REFUND",
"location_id": "M8AKAD8160XGR",
"created_at": "2024-08-15T15:59:45.000Z",
"gift_card_id": "gftc:065fd3c6e1014c9293bd2d09475ea189",
"gift_card_gan": "7783320009623257",
"gift_card_balance_money": {
"amount": 10000,
"currency": "USD"
},
"refund_activity_details": {
"redeem_activity_id": "gcact_d31b4200f5174fc48cb7138aeae197d0",
"amount_money": {
"amount": 2550,
"currency": "USD"
},
"payment_id": "9WIIrJKZXMgSF9dI7SX9pOlWy7DZY"
}
}
}
The refund flow determines whether gift card details are included in the refund. For gift card transactions, the card_details.card.card_brand
field is set to SQUARE_GIFT_CARD
.
Gift card details aren't included in a same-tender refund. To get details about the gift card that made the payment and received the refund, call GetPayment
using the payment_id
from the refund and check the card_details
field.
{
"refund": {
"id": "9WIIrJKZXMgSF9dI7SX9pOlWy7DZY_JnAde8lQt5pt9MLAMZ4UgaXt0sN3ZGqr62Ohx23tGGH",
"status": "COMPLETED",
"amount_money": {
"amount": 1500,
"currency": "USD"
},
"payment_id": "9WIIrJKZXMgSF9dI7SX9pOlWy7DZY",
"order_id": "kayuaH6E5v63RuuaXLSyJa8Qrc4F",
"created_at": "2024-08-15T15:59:30.564Z",
"updated_at": "2024-08-15T15:59:45.590Z",
"location_id": "M8AKAD8160XGR",
"destination_type": "CARD"
}
}
Refunds to the SQUARE_GIFT_CARD
card brand don't affect a seller's payment processing balance. Note that a refund might take up to 14 days to complete. For more information about refund flows, see Refund Payments.
- Square API version 2024-08-21 or later is required for the following features related to cross-tender refunds:
- Using
RefundPayment
to create cross-tender gift card refunds. - Using
GetRefund
orListRefunds
to retrieve cross-tender gift card refunds. When using earlier Square API versions,GetRefund
returns anAPI_VERSION_INCOMPATIBLE
error andListRefunds
omits cross-tender gift card refunds from the results. - Using
GetPayment
orListPayments
to getrefunded_money
orrefund_ids
details related to the refund. When using earlier Square API versions, this information is omitted from the returned payments. Therefore, the payment IDs in correspondingREFUND
activity details aren't useful for tracking refund activity.
- Using
- Refunding to a new gift card activates the card by changing the
PENDING
state toACTIVE
and adding an initial balance equal to the refund amount. This process creates aREFUND
activity but doesn't create anACTIVATE
activity. - Gift cards with custom GANs cannot receive cross-tender refunds using the Refunds API.
If your application doesn't use the Refunds API to process refunds, you must call CreateGiftCardActivity
to create the REFUND
or UNLINKED_ACTIVITY_REFUND
activity.
- For same-tender gift card refunds - Create a
REFUND
activity and provide the following activity details in the request:amount_money
redeem_activity_id
reference_id
(optional)
- For cross-tender gift card refunds - Create an
UNLINKED_ACTIVITY_REFUND
activity and provide the following activity details in the request:amount_money
reference_id
(optional)
REFUND
and UNLINKED_ACTIVITY_REFUND
activities created by custom processing systems don't have a payment_id
because they aren't linked to a Square payment.