• Example searches: “transaction”, “CreateOrder”, “/v2/locations”, “inventory”, “delete customer”

You are viewing an old version of the API
Create gift card BETA

POST /v2/gift-cards

Creates a digital gift card or registers a physical (plastic) gift card.

After the gift card is created, you must call CreateGiftCardActivity to activate the card with an initial balance before it can be used for payment.

Permissions
GIFTCARDS_WRITE
Guide
Selling gift cards Try in API Explorer

Request Body

Example code
Name Description
idempotency_key
string
Required

A unique identifier for this request, used to ensure idempotency. For more information, see Idempotency.

Min Length 1 Max Length 128
location_id
string
Required

The ID of the location where the gift card should be registered for reporting purposes. Gift cards can be redeemed at any of the seller's locations.

Min Length 1
gift_card
GiftCard
Required

The gift card to create. The type field is required for this request. The gan_source and gan fields are included as follows:

To direct Square to generate a 16-digit GAN, omit gan_source and gan.

To provide a custom GAN, include gan_source and gan.

  • For gan_source, specify OTHER.
  • For gan, provide a custom GAN containing 8 to 20 alphanumeric characters. The GAN must be unique for the seller and cannot start with the same bank identification number (BIN) as major credit cards. Do not use GANs that are easy to guess (such as 12345678) because they greatly increase the risk of fraud. It is the responsibility of the developer to ensure the security of their custom GANs. For more information, see Custom GANs.

To register an unused, physical gift card that the seller previously ordered from Square, include gan and provide the GAN that is printed on the gift card.

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
gift_card
GiftCard

The new gift card.

Examples

You are viewing an old version of the API
POST /v2/gift-cards
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/gift-cards \
  -X POST \
  -H 'Square-Version: 2022-05-12' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "NC9Tm69EjbjtConu",
    "location_id": "81FN9BNFZTKS4",
    "gift_card": {
      "type": "DIGITAL"
    }
  }'
Response JSON 
{
  "gift_card": {
    "id": "gftc:6cbacbb64cf54e2ca9f573d619038059",
    "type": "DIGITAL",
    "gan_source": "SQUARE",
    "state": "PENDING",
    "balance_money": {
      "amount": 0,
      "currency": "USD"
    },
    "gan": "7783320006753271",
    "created_at": "2021-05-20T22:26:54.000Z"
  }
}