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

You are viewing an old version of the API
List gift cards

GET /v2/gift-cards

Lists all gift cards.

You can specify optional filters to retrieve a subset of the gift cards. Results are sorted by created_at in ascending order.

Permissions
GIFTCARDS_READ
 Try in API Explorer

Query Parameters

Example code
Name Description
type
string

If a type is provided, the endpoint returns gift cards of the specified type. Otherwise, the endpoint returns gift cards of all types.
state
string

If a state is provided, the endpoint returns the gift cards in the specified state. Otherwise, the endpoint returns the gift cards of all states.
limit
integer (32-bit)

If a limit is provided, the endpoint returns only the specified number of results per page. The maximum value is 50. The default value is 30. For more information, see Pagination.
cursor
string

A pagination cursor returned by a previous call to this endpoint. Provide this cursor to retrieve the next set of results for the original query. If a cursor is not provided, the endpoint returns the first page of the results. For more information, see Pagination.
customer_id
string

If a customer ID is provided, the endpoint returns only the gift cards linked to the specified customer.

Response Fields
Name Description
errors
Error [ ]

Any errors that occurred during the request.
gift_cards
GiftCard [ ]

The requested gift cards or an empty object if none are found.
cursor
string

When a response is truncated, it includes a cursor that you can use in a subsequent request to retrieve the next set of gift cards. If a cursor is not present, this is the final response. For more information, see Pagination.

Examples

You are viewing an old version of the API
GET /v2/gift-cards
cURL
  • cURL
  • Ruby
  • Python
  • C#
  • Java
  • PHP
  • Node.js 
curl https://connect.squareup.com/v2/gift-cards?type=DIGITAL&state=ACTIVE&cursor=Jj0rA9-rrDW5k-PsorOq-m4BiGf \
  -H 'Square-Version: 2023-01-19' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
Response JSON 
{
  "gift_cards": [
    {
      "id": "gftc:00113070ba5745f0b2377c1b9570cb03",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "ACTIVE",
      "balance_money": {
        "amount": 3900,
        "currency": "USD"
      },
      "gan": "7783320008524605",
      "created_at": "2021-06-09T22:26:54.000Z"
    },
    {
      "id": "gftc:00128a12725b41e58e0de1d20497a9dd",
      "type": "DIGITAL",
      "gan_source": "SQUARE",
      "state": "ACTIVE",
      "balance_money": {
        "amount": 2000,
        "currency": "USD"
      },
      "gan": "7783320002692465",
      "created_at": "2021-05-20T22:26:54.000Z"
    }
  ],
  "cursor": "JbFmyvUpaNKsfC1hoLSA4WlqkgkZXTWeKuStajR5BkP7OE0ETAbeWSi6U6u7sH"
}