Gift Cards API and Gift Card Activities API

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.

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 and GIFTCARDS_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 and ORDERS_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 a BAD_REQUEST error if the app_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, and ADJUST_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:

  • GIFT_CARD_LOAD_FEE
  • GIFT_CARD_LOAD_FEE_REFUND
  • UNDO_GIFT_CARD_LOAD_FEE_REFUND

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

• Square Dashboard reporting - When third-party applications use Orders API or Payments API integration to reload or redeem a gift card, the Square 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 Square 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, and IMPORT activities that occurred before March 2, 2016, aren't included in ListGiftCardActivities results or when viewing the activity history in the Square 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.

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 a source_id for a gift card payment in a CreatePayment request.
• id as the source_id for a gift card on file payment in a CreatePayment request.
• id as the destination_id when issuing store credit in a CreateRefund 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:

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:

Square provides integrated gift card workflows for applications that use the Orders API, Payments API, or Refunds API.

{
  "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"
    }
  }
}

{
  "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"
    }
  }
}

{
  "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"
  }
}

{
  "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"
    }
  }
}

{
  "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"
  }
}

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:
  • A bank identification number (BIN) pattern used by major credit cards (such as Visa, Mastercard, and American Express).
  • A BIN used by Square gift cards: 778273 (physical) or 778332 (digital).

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 the customer_ids field of the gift_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 Square Dashboard.

• Gift cards with custom GANs cannot receive cross-tender refunds in the Square Dashboard, Square Point of Sale, or Refunds API.

Note the following when working with physical (plastic) gift cards:

• Physical gift cards are imprinted with a 16-digit GAN and a barcode. The GAN is numeric only and starts with 778273. The GAN is stored in the gan field of the GiftCard object.

• 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 Square 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.

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.

You can create and manage Square gift cards in the Square Sandbox. In addition, Square provides a test value that you can use to test gift card payments. For more information, see Testing gift card payments in the Sandbox.

The following limitations apply to testing gift card payments in the Sandbox:

• Creating, managing, and testing with 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.

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:

Square returns the following errors when compliance limits are exceeded:

• Maximum balance amount per gift card:

  {
    "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 gift card per day:

  {
    "code": "PAYMENT_LIMIT_EXCEEDED",
    "detail": "The gift card limit for increasing balance reached.",
    "category": "PAYMENT_METHOD_ERROR"
  }

• Maximum load amount per payment card per day:

  {
    "code": "BAD_REQUEST",
    "detail": "Load amount exceeds maximum buyer daily amount.",
    "category": "INVALID_REQUEST_ERROR"
  }

• Maximum outstanding balance amount per seller:

  {
    "code": "PAYMENT_LIMIT_EXCEEDED",
    "detail": "The merchant cannot accrue any more liability.",
    "category": "PAYMENT_METHOD_ERROR"
  }

• Video: Sandbox 101: Gift Cards API
• Sample Application: Gift Card API Sample App
• Video: Gift Card API Sample App Overview
• API Reference: Gift Cards API
• API Reference: Gift Card Activities API