GiftCards

Retrieves and creates gift card records in Square, including card type, balance, state, account details, and associated customers.

Table Specific Information

Select

The provider uses the Square API to filter the results by the following columns and operators. All other filters are processed client-side.


Column	Supported Operators
Id	`=`
Type	`=`
State	`=`
CustomerIds	`=`
GiftCardAccountNumber	`=`
Nonce	`=`

Id, GiftCardAccountNumber, and Nonce each retrieve a single gift card through a distinct Square API endpoint. Therefore, only one of these columns can be pushed to the Square API per query.

When you specify more than one, the provider pushes the highest-priority column in the following order: Nonce, GiftCardAccountNumber, then Id. The provider evaluates the remaining conditions client-side.

Retrieve all gift cards:

SELECT * FROM GiftCards

Retrieve a gift card using the gift card Id:

SELECT * FROM GiftCards WHERE Id = 'gftc:3c0c38e043a742c58431e3cca603c5b9'

Retrieve gift cards by customer Id. Pass one customer Id at a time:

SELECT * FROM GiftCards WHERE CustomerIds = 'DP6XW98QK78CVK76S65A4GBXK8'

Retrieve a gift card using the gift card account number (GAN):

SELECT * FROM GiftCards WHERE GiftCardAccountNumber = '7783320339333007'

Retrieve a gift card using a payment nonce:

SELECT * FROM GiftCards WHERE Nonce = 'cnon:7783322135245171'

Insert

To create a gift card, you must specify the LocationId and gift card type. LocationId is a pseudocolumn used only when creating a gift card:

INSERT INTO GiftCards(LocationId, Type) VALUES ('92BYHNBR6W77E', 'DIGITAL')

The LocationId column is only allowed for Insert operations.

Columns


Name	Type	ReadOnly	Description
Id [KEY]	String	True	The Square-assigned Id of the gift card.
Type	String	False	The gift card type (for example, physical or digital). The allowed values are PHYSICAL, DIGITAL.
GiftCardAccountNumberSource	String	False	The source that generated the gift card account number (GAN). The default value is SQUARE. The allowed values are SQUARE, OTHER.
State	String	True	The current status of the gift card (for example, active, inactive, redeemed, or deactivated). The allowed values are ACTIVE, DEACTIVATED, BLOCKED, PENDING.
BalanceMoneyAmount	Int64	True	The current gift card balance amount. This balance is always greater than or equal to zero.
BalanceMoneyCurrency	String	True	The currency code for the balance amount, in ISO 4217 format (for example, USD or CAD).
GiftCardAccountNumber	String	False	The gift card account number (GAN). Buyers can use the GAN to make purchases or check the gift card balance.
CreatedAt	Datetime	True	The timestamp when the gift card was created, in RFC 3339 format. In the case of a digital gift card, it is the time when you create a card (using the Square Point of Sale application, Seller Dashboard, or Gift Cards API).
CustomerIds	String	True	The Ids of the customer profiles to whom this gift card is linked.

Pseudocolumns

Pseudo column fields are used in the WHERE clause of SELECT statements (unless stated otherwise) and offer a more granular control over the tuples that are returned from the data source.