Beta Release
This is pre-release documentation for an API in public beta and is subject to change.
Gift Cards API

Walkthrough 2: Use a Gift Card

This walkthrough assumes that you have completed Walkthrough 1: Sell a Gift Card and you have an activated gift card. In this walkthrough, you explore the Gift Cards API operations (such as redeem the card for purchases and add more money to the gift card) and the Gift Card Activities API operations (such as get a list of gift card activities).

Step 1: Redeem the gift card for a purchase Permalink Get a link to this section

Gift cards can be redeemed in two ways:

  • Using the Payments API. If your application uses the Square Payments API (CreatePayment endpoint) to take a payment, you can provide a gift card as the payment source. In this case, the API automatically redeems the amount from the gift card.

  • Using the Gift Cards API. Instead of using the Payments API, if your application uses a non-Square API after processing a payment, you explicitly call the CreateGiftCardActivity endpoint (with REDEEM as the activity type) to redeem the amount.

Note

In the Square Sandbox, the Payments API currently only supports using a token that represents a test Square gift card. It does not accept a gift card created using the Gift Cards API. This is not an issue in the production environment.

For example, suppose a buyer wants to pay $3 for a purchase and wants to redeem the gift card. Assume that the payment is processed. You can explicitly call CreateGiftCardActivity (Gift Card Activities API) to redeem the gift card.

Create Gift Card Activity
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
  • 17
  • 18
  • 19
  • 20
  • 21
curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "{UNIQUE_KEY}",
    "gift_card_activity": {
      "gift_card_id": "{GIFT_CARD_ID}",
      "type": "REDEEM",
      "location_id": "{LOCATION_ID}",
      "redeem_activity_details": {
        "amount_money": {
          "amount": 300,
          "currency": "USD"
        },
        "payment_id": "client-side-example-payment-id",
        "reference_id": "client-side-example-reference-id"
      }
    }
  }'

The following is an example response. The response shows the amount redeemed and the gift card balance.

{
  "gift_card_activity": {
    "id": "gcact_e303d6390aae4573a38e8a7027c3f51a",
    "type": "REDEEM",
    "location_id": "S8GWD5R9QB376",
    "created_at": "2021-04-11T19:12:08.000Z",
    "gift_card_id": "gftc:012440e514754c42990f3de4527498dc",
    "gift_card_gan": "7783320002382646",
    "gift_card_balance_money": {
      "amount": 2200,
      "currency": "USD"
    },
    "redeem_activity_details": {
      "amount_money": {
        "amount": 300,
        "currency": "USD"
      },
      "reference_id": "client-side-example-reference-id"
    }
  }
}

You can optionally call RetrieveGiftCard to review the gift card information. You can also call RetrieveGiftCard (Gift Cards API) to verify the status change.

Retrieve Gift Card
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/gift-cards/{id} \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

For more information about redeeming a gift card, see Redeem a gift card for a purchase.

Step 2: Add money to the gift card Permalink Get a link to this section

The Gift Card Activities API also supports the CreateGiftCardActivity endpoint to add money to an existing gift card. In the request, you set LOAD as the activity type.

Suppose the gift card holder wants to add $10 to the gift card. Your application must first process the order. Your application has the option to use the Square Orders API or your own custom client-side API.

  • Using a custom client-side API. Assuming that your application processed $10 using a custom client-side API, you are now ready to add the amount to the card. Call CreateGiftCardActivity with the type set to LOAD and provide load_activity_details as follows:

    • amount_money specifies the amount to add to the gift card. In this case, you add $10.

    • buyer_payment_instrument_ids specifies the payment instrument IDs for the payment that your application processed using the custom client-side API.

    • Optional reference_id to associate the load activity to a client-side object.

    Create Gift Card Activity
    • 1
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
    • 9
    • 10
    • 11
    • 12
    • 13
    • 14
    • 15
    • 16
    • 17
    • 18
    • 19
    • 20
    • 21
    • 22
    • 23
    • 24
    curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
      -X POST \
      -H 'Square-Version: 2021-09-15' \
      -H 'Authorization: Bearer {ACCESS_TOKEN}' \
      -H 'Content-Type: application/json' \
      -d '{
        "idempotency_key": "{UNIQUE_KEY}",
        "gift_card_activity": {
          "gift_card_id": "{GIFT_CARD_ID}",
          "type": "LOAD",
          "location_id": "{LOCATION_ID}",
          "load_activity_details": {
            "amount_money": {
              "amount": 1000,
              "currency": "USD"
            },
            "reference_id": "client-side-example-reference-id",
            "buyer_payment_instrument_ids": [
              "example-id-1",
              "example-id-2"
            ]
          }
        }
      }'

    The following is an example response. You should verify that the giftcard_balance_money has increased by the amount you added.

    {
      "gift_card_activity": {
        "id": "gcact_7003b1adf7b042b19499280e2bf82e83",
        "type": "LOAD",
        "location_id": "S8GWD5R9QB376",
        "created_at": "2021-04-11T20:48:51.000Z",
        "gift_card_id": "gftc:01696eaf3d5141bfb4c7869494257bb6",
        "gift_card_gan": "7783320005719034",
        "gift_card_balance_money": {
          "amount": 3200,
          "currency": "USD"
        },
        "load_activity_details": {
          "amount_money": {
            "amount": 1000,
            "currency": "USD"
          },
          "reference_id": "client-side-example-reference-id",
          "buyer_payment_instrument_ids": [
            "example-id-1",
            "example-id-2"
          ]
        }
      }
    }
    
  • Using the Square Orders API. The following steps show how to create an order using the Orders API, take payment using the Payments API, and use the Gift Cards API to add money to the card.

    • Create an order for $10. In the CreateOrder request body, make sure that the line_items specify the item_type field and set its value to GIFT_CARD because you are creating this order to add money to the gift card.

      Create Order
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      • 14
      • 15
      • 16
      • 17
      • 18
      • 19
      • 20
      • 21
      • 22
      curl https://connect.squareupsandbox.com/v2/orders \
        -X POST \
        -H 'Square-Version: 2021-09-15' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "idempotency_key": "{UNIQUE_KEY}",
          "order": {
            "location_id": "{LOCATION_ID}",
            "line_items": [
              {
                "name": "eGiftCard via API",
                "quantity": "1",
                "item_type": "GIFT_CARD",
                "base_price_money": {
                  "amount": 1000,
                  "currency": "USD"
                }
              }
            ]
          }
        }'

      Review the order returned in the response. Note the following:

      • order_id. You provide the order ID when taking the payment.

      • line_item_uid. When loading money using CreateGiftCardActivity, you provide both the order ID and line item ID.

    • Take the payment for the order by calling CreatePayment.

      Create Payment
      • 1
      • 2
      • 3
      • 4
      • 5
      • 6
      • 7
      • 8
      • 9
      • 10
      • 11
      • 12
      • 13
      • 14
      • 15
      curl https://connect.squareupsandbox.com/v2/payments \
        -X POST \
        -H 'Square-Version: 2021-09-15' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'Content-Type: application/json' \
        -d '{
          "source_id": "cnon:card-nonce-ok",
          "idempotency_key": "{UNIQUE_KEY}",
          "amount_money": {
            "amount": 1000,
            "currency": "USD"
          },
          "order_id": "{ORDER_ID}",
          "location_id": "{LOCATION_ID}"
        }'

      Verify the payment returned in the response. Make sure the payment status is CAPTURED.

      • Call CreateGiftCardActivity to add $10 to the gift card. In the request, set LOAD as the activity type.

        Create Gift Card Activity
        • 1
        • 2
        • 3
        • 4
        • 5
        • 6
        • 7
        • 8
        • 9
        • 10
        • 11
        • 12
        • 13
        • 14
        • 15
        • 16
        • 17
        curl https://connect.squareupsandbox.com/v2/gift-cards/activities \
          -X POST \
          -H 'Square-Version: 2021-09-15' \
          -H 'Authorization: Bearer {ACCESS_TOKEN}' \
          -H 'Content-Type: application/json' \
          -d '{
            "idempotency_key": "{UNIQUE_KEY}",
            "gift_card_activity": {
              "gift_card_id": "{GIFT_CARD_ID}",
              "type": "LOAD",
              "location_id": "{LOCATION_ID}",
              "load_activity_details": {
                "order_id": "{ORDER_ID}",
                "line_item_uid": "{LINE_ITEM_UID}"
              }
            }
          }'

        The following is an example response. You should verify that gift_card_balance_money shows the $10 added to the amount.

        {
          "gift_card_activity": {
            "id": "gcact_add1aab7693e4fa6891d0597ee3f63dd",
            "type": "LOAD",
            "location_id": "S8GWD5R9QB376",
            "created_at": "2021-04-11T19:21:59.000Z",
            "gift_card_id": "gftc:012440e514754c42990f3de4527498dc",
            "gift_card_gan": "7783320002382646",
            "gift_card_balance_money": {
              "amount": 3200,
              "currency": "USD"
            },
            "load_activity_details": {
              "amount_money": {
                "amount": 1000,
                "currency": "USD"
              },
              "order_id": "UXEmEo3X5XYPyfKIrB4tde4LupGZY",
              "line_item_uid": "m2nFRgmD4AhdUmDxmDhRBC"
            }
          }
        }
        

Step 3: List the gift card activities Permalink Get a link to this section

Call ListGiftCardActivities (Gift Cards API) to retrieve a list of all the gift card activities. You specify the giftcard_id as a query parameter.

List Gift Card Activities
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareupsandbox.com/v2/gift-cards/activities?gift_card_id={{GIFT_CARD_ID}} \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json'

A seller can also review gift card activities in the Seller Dashboard. Because you are testing this walkthrough using Square Sandbox, review the gift card activities in the Sandbox Seller Dashboard.

  1. Open the Developer Dashboard.

  2. In the Sandbox Test Accounts section, choose Open next to Default Test Account. This opens the Sandbox Seller Dashboard associated with the default test account.

  3. Choose Gift Cards in the left pane.

  4. Search for the gift card by providing the GAN in the Search by gift card number box.

  5. Choose the gift card. This opens a pane on the right showing the gift card details and list of activities.