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

Additional Gift Cards API Considerations

This topic provides additional information related to working with Square gift cards. This includes additional Gift Cards API features (such as checking the gift card balance and adding gift cards on file) and gift card related reports available in the Seller Dashboard.

Check gift card balance Permalink Get a link to this section

The Gift Cards API provides endpoints to retrieve a gift card using the ID, gift card number (GAN), or payment token. The balance_money field in the returned GiftCard object represents the gift card balance.

Retrieve a gift card by ID Permalink Get a link to this section

Use the RetrieveGiftCard endpoint if you know the gift card ID. You provide the ID as a path parameter.

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'

Retrieve a gift card by GAN Permalink Get a link to this section

Use the RetrieveGiftCardFromGAN endpoint if you know the GAN. You provide the GAN in the request body.

Retrieve Gift Card From G A N
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/gift-cards/from-gan \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "gan": "{GIFT_CARD_GAN}"
  }'

Retrieve a gift card by payment token Permalink Get a link to this section

Use the RetrieveGiftCardFromNonce endpoint if your application has a secure payment token (nonce) that represents the gift card as the payment source. You provide the token in the request body.

Retrieve Gift Card From Nonce
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/gift-cards/from-nonce \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "nonce": "{SECURE_TOKEN}"
  }'

Manage gift cards on file Permalink Get a link to this section

The Gift Cards API provides endpoints to add or remove gift cards on file for a customer profile in the seller's Customer Directory. This action is also referred to as linking customers to gift cards.

Note

This functionality replaces the deprecated CreateCustomerCard and DeleteCustomerCard endpoints and deprecated Customer.cards field in the Customers API.

Add a gift card on file Permalink Get a link to this section

The Gift Cards API provides the LinkCustomerToGiftCard endpoint to link a gift card to a customer profile in the seller's Customer Directory. The following is an example LinkCustomerToGiftCard request:

Link Customer To Gift Card
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/gift-cards/{gift_card_id}/link-customer \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "{CUSTOMER_ID}"
  }'

The request specifies the gift card ID as a path parameter and the customer profile ID in the request body. In response, Square updates the GiftCard object by adding the customer_ids field with the customer ID, as shown in the following example:

{
   "gift_card":{
      "id":"gftc:73df43542ef447f0905c2f21b38480b0",
      "type":"DIGITAL",
      "gan_source":"SQUARE",
      "state":"NOT_ACTIVE",
      "balance_money":{
         "amount":0,
         "currency":"USD"
      },
      "gan":"7783320008367013",
      "created_at":"2021-04-08T20:17:25Z",
      "customer_ids":[
         "7TPK262NN0SP5CC4ZNMFXPY808"
      ]
   }
}

Linking a gift card to a customer profile enables the following features:

  • Simplified payment process. Sellers can easily redeem a linked gift card when performing a transaction with a customer using Square first-party applications (such as the Square Point of Sale (POS) application or Seller Dashboard) or third-party applications that use the Gift Cards API.

  • Seller Dashboard enhancement. In the Customers section, the details pane shows credit cards and gift cards that are linked to the selected customer profile.

  • For developers using the CreatePayment endpoint in the Payments API, in addition to specifying a gift card as a payment source, developers can specify the optional customer ID to associate the purchase with a customer (this customer need not be linked to the gift card).

The following constraints apply when linking a customer to a gift card:

  • A gift card can be linked to a maximum of 10 customer profiles.

  • A customer profile can be linked to a maximum of 50 gift cards.

Remove a gift card on file Permalink Get a link to this section

The Gift Cards API also provides the UnlinkCustomerFromGiftCard endpoint to remove the customer association from the gift card.

Unlink Customer From Gift Card
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
curl https://connect.squareupsandbox.com/v2/gift-cards/{gift_card_id}/unlink-customer \
  -X POST \
  -H 'Square-Version: 2021-09-15' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "{CUSTOMER_ID}"
  }'

List gift cards on file Permalink Get a link to this section

To retrieve the gift cards that are linked to a customer, call ListGiftCards and specify the customer_id query parameter.

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

Seller reports Permalink Get a link to this section

The Reports section in the Seller Dashboard includes the following gift card related reports:

  • Sales Summary report. Shows a summary of everything that occurred using the POS application, Seller Dashboard, and transactions made using the Orders API and Payments API. This report includes a section for gift card sales, but does not include redemptions.

  • Gift Cards report. Shows gift card specific activities.

When your application uses the Orders API and Payments API, these reports are Square-backed and accurately reflect the activities. For example:

  • When you redeem a gift card using the Payments API, Square automatically creates the corresponding REDEEM gift card activity.

  • When you activate a gift card and provide an order ID, Square reads the order and determines the amount to add to the card as the initial balance.

When an application uses a custom solution to create an order and process a payment, the activity does not appear in the Sales Summary report. Only the Gift Card report tracks this activity.

Related topics Permalink Get a link to this section