Gift Card

Gift Cards are a form of stored value that a customer can redeem at checkout. They hold a certain balance and can be used multiple times until the balance is depleted.

See the gift card fields for more details and options.

Endpoints

POST
/stores/{store.id}/giftcards
GET
/stores/{store.id}/giftcards
GET
/stores/{store.id}/giftcards/{giftcard.id}
PATCH
/stores/{store.id}/giftcards/{giftcard.id}
DELETE
/stores/{store.id}/giftcards/{giftcard.id}

The Gift Card object

Fields
Name
id
Type
flake
Tags
Description
id of the gift card
Name
store_id
Type
flake
Tags
Description
id of the store the gift card belongs to
Name
enabled
Type
boolean
Tags
Description
whether the gift card is enabled and currently usable by customers
Name
code
Type
string
Tags
Description
the code that customers type in at checkout. Code is case insensitive and unique to the store. Limited to alphanumeric characters, spaces and dashes.
Name
balance
Type
integer
Tags
Description
the remaining balance on the gift card. balance is in zero-decimal format (where $10.00 is 1000).
Name
starting_balance
Type
integer
Tags
Description
the starting balance of the gift card. balance is in zero-decimal format (where $10.00 is 1000).
Name
usable_at
Type
timestamp
Tags
Description
timestamp of when the gift card will become usable
Name
expires_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the gift card will expire and become unusable
Name
created_by
Type
user
Tags
Description
the user that created this gift card.
Name
created_at
Type
timestamp
Tags
Description
timestamp of when the gift card was created
Name
updated_by
Type
user
Tags
NULLABLE
Description
the user that most recently updated this gift card.
Name
updated_at
Type
timestamp
Tags
NULLABLE
Description
timestamp of when the gift card was last updated

The Gift Card object

{
	"id": "150580776499843072",
	"store_id": "94688451781206016",
	"enabled": true,
	"code": "GIFT-100",
	"balance": 10000,
	"starting_balance": 10000,
	"usable_at": "2023-04-11T16:42:58.163471Z",
	"expires_at": "2023-06-11T16:43:28.253320Z",
	"created_by": {
		"id": "11084680073842688",
		"first_name": "Example",
		"last_name": "Exampleson"
	},
	"created_at": "2023-04-11T16:42:58.197319Z",
	"updated_by": null,
	"updated_at": null
}

Create Gift Card

Creates a new gift card.

Parameters
Name
enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the gift card is enabled and currently usable by customers
Name
code
Type
string
Tags
REQUIRED
Description
the code that customers type in at checkout. Code is case insensitive and unique to the store. Limited to alphanumeric characters, spaces and dashes.
Name
balance
Type
integer
Tags
REQUIRED
Description
the balance of the gift card. balance is in zero-decimal format (where $10.00 is 1000).
Name
usable_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the gift card will become usable
Name
expires_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the gift card will expire and become unusable

Returns

Returns the newly created gift card.

Request

giftcard_create

POST
/stores/{store.id}/giftcards

Response

{
	"id": "150580776499843072",
	"store_id": "94688451781206016",
	"enabled": true,
	"code": "GIFT-100",
	"balance": 10000,
	"starting_balance": 10000,
	"usable_at": "2023-04-11T16:42:58.163471Z",
	"expires_at": "2023-06-11T16:43:28.253320Z",
	"created_by": {
		"id": "11084680073842688",
		"first_name": "Example",
		"last_name": "Exampleson"
	},
	"created_at": "2023-04-11T16:42:58.197319Z",
	"updated_by": null,
	"updated_at": null
}

Get Gift Cards

Retrieves a paginated list of gift cards.

Query Parameters
Name
limit
Type
integer?
Tags
OPTIONAL
Description
the max number of results to return (1 - 100)
Name
after
Type
flake?
Tags
OPTIONAL
Description
an ID flake, after which to start returning results
Name
before
Type
flake?
Tags
OPTIONAL
Description
an ID flake, before which to start returning results
Name
include_canceled
Type
boolean?
Tags
OPTIONAL
Description
whether the response should include canceled giftcards
Name
code
Type
string?
Tags
OPTIONAL
Description
filter the giftcards by a code

Returns

Returns a list of gift cards.

Request

giftcard_read

GET
/stores/{store.id}/giftcards

Response

[
	{
		"id": "150580776499843072",
		"store_id": "94688451781206016",
		"enabled": true,
		"code": "GIFT-100",
		"balance": 10000,
		"starting_balance": 10000,
		"usable_at": "2023-04-11T16:42:58.163471Z",
		"expires_at": "2023-06-11T16:43:28.253320Z",
		"created_by": {
			"id": "11084680073842688",
			"first_name": "Example",
			"last_name": "Exampleson"
		},
		"created_at": "2023-04-11T16:42:58.197319Z",
		"updated_by": null,
		"updated_at": null
	}
]

Get Gift Card

Retrieves a specific gift card by ID.

Returns

Returns the requested gift card.

Request

giftcard_read

GET
/stores/{store.id}/giftcards/{giftcard.id}

Response

{
	"id": "150580776499843072",
	"store_id": "94688451781206016",
	"enabled": true,
	"code": "GIFT-100",
	"balance": 10000,
	"starting_balance": 10000,
	"usable_at": "2023-04-11T16:42:58.163471Z",
	"expires_at": "2023-06-11T16:43:28.253320Z",
	"created_by": {
		"id": "11084680073842688",
		"first_name": "Example",
		"last_name": "Exampleson"
	},
	"created_at": "2023-04-11T16:42:58.197319Z",
	"updated_by": null,
	"updated_at": null
}

Update Gift Card

Updates a specific gift card by ID.

Parameters
Name
enabled
Type
boolean?
Tags
OPTIONAL
Description
whether the gift card is enabled and currently usable by customers
Name
code
Type
string?
Tags
OPTIONAL
Description
the code that customers type in at checkout. Code is case insensitive and unique to the store. Limited to alphanumeric characters, spaces and dashes.
Name
balance
Type
integer?
Tags
OPTIONAL
Description
the remaining balance on the gift card. balance is in zero-decimal format (where $10.00 is 1000).
Name
usable_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the gift card will become usable
Name
expires_at
Type
timestamp?
Tags
OPTIONAL
Description
timestamp of when the gift card will expire and become unusable

Returns

Returns the updated gift card.

Request

giftcard_update

PATCH
/stores/{store.id}/giftcards/{giftcard.id}

Response

{
	"id": "150580776499843072",
	"store_id": "94688451781206016",
	"enabled": true,
	"code": "GIFT-100",
	"balance": 10000,
	"starting_balance": 10000,
	"usable_at": "2023-04-11T16:42:58.163471Z",
	"expires_at": "2023-06-11T16:43:28.253320Z",
	"created_by": {
		"id": "11084680073842688",
		"first_name": "Example",
		"last_name": "Exampleson"
	},
	"created_at": "2023-04-11T16:42:58.197319Z",
	"updated_by": {
		"id": "11084680073842688",
		"first_name": "Example",
		"last_name": "Exampleson"
	},
	"updated_at": "2023-04-11T17:42:58.197319Z"
}

Delete Gift Card

Deletes a specific gift card by ID.

Returns

Returns a 204 No Content response upon successful deletion.

Request

giftcard_delete

DELETE
/stores/{store.id}/giftcards/{giftcard.id}

Gift Card

Endpoints

The Gift Card object

Fields

The Gift Card object

Create Gift Card

Parameters

Returns

Request

Response

Get Gift Cards

Query Parameters

Returns

Request

Response

Get Gift Card

Returns

Request

Response

Update Gift Card

Parameters

Returns

Request

Response

Delete Gift Card

Returns

Request