Reload Square Gift Cards

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:

1. Process the order for the gift card amount.
2. 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'll 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 or gift_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 - Specify LOAD.

• load_activity_details - Details about the LOAD activity. The information you provide depends on how your application processes orders:

  • Orders API
  • Custom order processing

• 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 the GIFT_CARD line item. Square reads the order and determines the amount to add to the gift card balance.

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.

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.

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:

  • 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 the item_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 an ADJUST_DECREMENT activity with the PURCHASE_WAS_REFUNDED reason. Note that the Refunds API does update the balance after refunding a payment from a gift card.

• The ListGiftCardActivities endpoint returns activities that change the gift card balance or state. You can use the type query parameter to filter for LOAD activities.

• Square invokes the gift_card.updated and gift_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.

• Gift Cards API and Gift Card Activities API Overview
• Walkthrough 2: Use a Gift Card
• API Reference: Gift Cards
• API Reference: Gift Card Activities