Skip to main content
The Gift Cards API allows you to create digital gift cards, register physical gift cards, and manage gift card relationships with customers. Gift cards can be used across all of a seller’s locations.

​
Client Initialization

Access the Gift Cards client through the main Square client: 
import (
    "context"
    "github.com/square/square-go-sdk/v3"
)

client := square.NewClient(
    square.WithAccessToken("YOUR_ACCESS_TOKEN"),
)

// Access the Gift Cards API
giftCardsClient := client.GiftCards

​
Core Methods

​
List

Retrieve a paginated list of gift cards with optional filters. 
request := &square.ListGiftCardsRequest{
    Limit: square.Int(50),
    Cursor: square.String("cursor-from-previous-call"),
}

response, err := client.GiftCards.List(context.TODO(), request)
if err != nil {
    // Handle error
}

for _, giftCard := range response.GiftCards {
    fmt.Printf("Gift Card: %s, Balance: %d\n",
        *giftCard.ID,
        *giftCard.BalanceMoney.Amount)
}
​
type
*string
Filter by gift card type: PHYSICAL or DIGITAL.
​
state
*string
Filter by gift card state: ACTIVE, DEACTIVATED, BLOCKED, or PENDING.
​
limit
*int
Maximum results per page (1-200, default 30).
​
cursor
*string
Pagination cursor from a previous response.
​
customerID
*string
Filter by linked customer ID.
​
giftCards
[]*square.GiftCard
Array of gift card objects.
​
cursor
*string
Pagination cursor for the next page.

​
Create

Create a new digital gift card or register a physical gift card. 
request := &square.CreateGiftCardRequest{
    IdempotencyKey: "unique-key-" + time.Now().String(),
    LocationID: "LOCATION_ID",
    GiftCard: &square.GiftCard{
        Type: square.GiftCardTypeDigital,
    },
}

response, err := client.GiftCards.Create(context.TODO(), request)
if err != nil {
    // Handle error
}

fmt.Printf("Created gift card: %s\n", *response.GiftCard.ID)
fmt.Printf("GAN: %s\n", *response.GiftCard.Gan)
​
idempotencyKey
string
required
Unique key for idempotent operations.
​
locationID
string
required
Location ID for reporting purposes. Gift cards work at all locations.
​
giftCard.type
square.GiftCardType
required
Gift card type: DIGITAL or PHYSICAL.
​
giftCard.ganSource
*square.GiftCardGanSource
GAN source: SQUARE (default) or OTHER for custom GANs.
​
giftCard.gan
*string
Gift card account number (8-20 alphanumeric characters for custom GANs).
​
giftCard
*square.GiftCard
The newly created gift card object.

​
Get

Retrieve a gift card by its Square-issued ID. 
request := &square.GetGiftCardsRequest{
    ID: "GIFT_CARD_ID",
}

response, err := client.GiftCards.Get(context.TODO(), request)
if err != nil {
    // Handle error
}

fmt.Printf("Balance: $%.2f\n", 
    float64(*response.GiftCard.BalanceMoney.Amount) / 100.0)
​
id
string
required
The Square-issued gift card ID.
​
giftCard
*square.GiftCard
The requested gift card object.

​
GetFromGan

Retrieve a gift card using its account number (GAN). 
request := &square.GetGiftCardFromGanRequest{
    Gan: "7783320001001635",
}

response, err := client.GiftCards.GetFromGan(context.TODO(), request)
if err != nil {
    // Handle error
}
​
gan
string
required
The gift card account number (up to 255 digits for imported GANs, 16 for Square-issued).

​
GetFromNonce

Retrieve a gift card using a secure payment token. 
request := &square.GetGiftCardFromNonceRequest{
    Nonce: "cnon:7783322135245171",
}

response, err := client.GiftCards.GetFromNonce(context.TODO(), request)
if err != nil {
    // Handle error
}
​
nonce
string
required
Payment token from Web Payments SDK or In-App Payments SDK.

​
LinkCustomer

Link a customer to a gift card (add card on file). 
request := &square.LinkCustomerToGiftCardRequest{
    GiftCardID: "GIFT_CARD_ID",
    CustomerID: "CUSTOMER_ID",
}

response, err := client.GiftCards.LinkCustomer(context.TODO(), request)
if err != nil {
    // Handle error
}

fmt.Printf("Linked customers: %v\n", 
    response.GiftCard.CustomerIDs)
​
giftCardID
string
required
The ID of the gift card to link.
​
customerID
string
required
The ID of the customer to link.
​
giftCard
*square.GiftCard
The gift card with updated customer_ids field.

​
UnlinkCustomer

Unlink a customer from a gift card (remove card on file). 
request := &square.UnlinkCustomerFromGiftCardRequest{
    GiftCardID: "GIFT_CARD_ID",
    CustomerID: "CUSTOMER_ID",
}

response, err := client.GiftCards.UnlinkCustomer(context.TODO(), request)
if err != nil {
    // Handle error
}
​
giftCardID
string
required
The ID of the gift card.
​
customerID
string
required
The ID of the customer to unlink.

​
Complete Example

package main

import (
    "context"
    "fmt"
    "log"
    "time"
    
    "github.com/square/square-go-sdk/v3"
)

func main() {
    client := square.NewClient(
        square.WithAccessToken("YOUR_ACCESS_TOKEN"),
    )

    ctx := context.TODO()

    // 1. Create a digital gift card
    createReq := &square.CreateGiftCardRequest{
        IdempotencyKey: fmt.Sprintf("gift-%d", time.Now().Unix()),
        LocationID: "LOCATION_ID",
        GiftCard: &square.GiftCard{
            Type: square.GiftCardTypeDigital,
        },
    }

    createResp, err := client.GiftCards.Create(ctx, createReq)
    if err != nil {
        log.Fatal(err)
    }

    giftCardID := *createResp.GiftCard.ID
    fmt.Printf("Created gift card: %s\n", giftCardID)

    // 2. Link to a customer
    linkReq := &square.LinkCustomerToGiftCardRequest{
        GiftCardID: giftCardID,
        CustomerID: "CUSTOMER_ID",
    }

    linkResp, err := client.GiftCards.LinkCustomer(ctx, linkReq)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Linked to customers: %v\n", 
        linkResp.GiftCard.CustomerIDs)

    // 3. Retrieve gift card details
    getReq := &square.GetGiftCardsRequest{
        ID: giftCardID,
    }

    getResp, err := client.GiftCards.Get(ctx, getReq)
    if err != nil {
        log.Fatal(err)
    }

    gc := getResp.GiftCard
    fmt.Printf("Gift Card Status:\n")
    fmt.Printf("  GAN: %s\n", *gc.Gan)
    fmt.Printf("  State: %s\n", *gc.State)
    fmt.Printf("  Balance: $%.2f\n", 
        float64(*gc.BalanceMoney.Amount) / 100.0)

    // 4. List all gift cards for customer
    listReq := &square.ListGiftCardsRequest{
        CustomerID: square.String("CUSTOMER_ID"),
    }

    listResp, err := client.GiftCards.List(ctx, listReq)
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Customer has %d gift card(s)\n", 
        len(listResp.GiftCards))
}

​
Types

​
GiftCard

The main gift card object. 
type GiftCard struct {
    ID           *string
    Type         GiftCardType
    GanSource    *GiftCardGanSource
    State        *GiftCardStatus
    BalanceMoney *Money
    Gan          *string
    CreatedAt    *string
    CustomerIDs  []string
}

​
GiftCardType

Gift card type enumeration. 
const (
    GiftCardTypePhysical GiftCardType = "PHYSICAL"
    GiftCardTypeDigital  GiftCardType = "DIGITAL"
)

​
GiftCardStatus

Gift card state enumeration. 
const (
    GiftCardStatusActive      GiftCardStatus = "ACTIVE"
    GiftCardStatusDeactivated GiftCardStatus = "DEACTIVATED"
    GiftCardStatusBlocked     GiftCardStatus = "BLOCKED"
    GiftCardStatusPending     GiftCardStatus = "PENDING"
)

​
GiftCardGanSource

GAN source enumeration. 
const (
    GiftCardGanSourceSquare GiftCardGanSource = "SQUARE"
    GiftCardGanSourceOther  GiftCardGanSource = "OTHER"
)

​
Gift Card States

Newly created gift card that hasn’t been activated yet. Create a gift card activity to activate it.

​
Best Practices

Newly created gift cards have a PENDING state. You must create a gift card activity (ACTIVATE) or refund a payment to the card to activate it for use.
When using custom GANs with GiftCardGanSourceOther, ensure they:
  • Are 8-20 alphanumeric characters
  • Don’t start with major credit card BINs
  • Aren’t easily guessable (avoid 12345678)
  • Are unique per seller
While gift cards are registered to a specific location for reporting, they can be redeemed at any of the seller’s locations.
Link gift cards to customers to enable features like viewing cards on file and tracking usage patterns.
The balance_money field is always >= 0. To load or adjust balances, use the Gift Card Activities API.

​
Use Cases

Digital Gift Cards

Create digital gift cards that customers can receive via email or text and redeem using their phone.

Physical Card Registration

Register physical gift cards ordered from Square by providing the printed GAN.

Customer Loyalty Integration

Link gift cards to customer profiles for seamless tracking and enhanced customer experience.

Balance Inquiry

Allow customers to check their gift card balance using GetFromGan or GetFromNonce.

Build docs developers (and LLMs) love

Get started for freeTalk to us