🔒
Requires write_gift_cards access scope. More access scope

Creates a new gift card for a specific customer or store, including details such as initial value, expiration date, and custom templates.

This API is especially useful for:

Generating new gift cards for customers
Setting up promotional gift cards for marketing campaigns
Creating gift cards with specific values and expiration dates

Request Parameters

Public Request Parameters

📘
Public Request Parameters

Body Parameters

📘
Public Request Parameters

Body Parameters

Parameter	Type	Required	Description	Example
`gift_card.code`	string	Yes	The gift card code, which is a string of alphanumeric characters. Must be between 8 and 20 characters.	`"GIFT123456"`
`gift_card.initial_value`	string	Yes	The initial value of the gift card when it was created. e.g. 200.00	`"100.00"`
`gift_card.expires_on`	string	No	The expiration date of the gift card in ISO-8601 format. e.g. 2022-11-01T00:00:00Z	`"2025-12-31T23:59:59Z"`
`gift_card.note`	string	No	An optional note that a merchant can attach to the gift card that isn't visible to customers.	`"Birthday gift for John"`
`gift_card.customer_id`	string	No	The ID of the customer associated with this gift card.	`"cust_12345"`
`gift_card.template_suffix`	string	No	The suffix of the Liquid template that's used to render the gift card online.	`"birthday"`
`gift_card.send_email`	boolean	No	Send notification email to customer, true is default.	`true`

Response Explanation

Public Response Parameters

📘
Public Response Parameters

Successful Response

Parameter	Type	Example	Description
`code`	string	`"200"`	The status code of the response
`message`	string	`"success"`	The message describing the response status
`data.gift_card.id`	string	`"gc_123456"`	Unique identifier for the gift card
`data.gift_card.last_characters`	string	`"456"`	Last characters of the gift card code
`data.gift_card.balance`	string	`"100.00"`	Current balance of the gift card
`data.gift_card.initial_value`	string	`"100.00"`	The initial value of the gift card
`data.gift_card.note`	string	`"Birthday gift for John"`	Note attached to the gift card
`data.gift_card.expires_on`	string	`"2025-12-31T23:59:59Z"`	Expiration date of the gift card in ISO-8601 format
`data.gift_card.disabled_at`	string	`null`	Timestamp when the gift card was disabled (null if active)
`data.gift_card.enabled`	boolean	`true`	Whether the gift card is currently enabled
`data.gift_card.created_at`	string	`"2025-06-01T10:00:00Z"`	Timestamp of when the gift card was created
`data.gift_card.updated_at`	string	`"2025-06-01T10:00:00Z"`	Timestamp of when the gift card was last updated
`data.gift_card.status`	string	`"enabled"`	Status of the gift card (enable or disable)
`data.gift_card.currency`	string	`"USD"`	Currency in which the gift card is denominated
`data.gift_card.line_item_id`	string	`"li_123"`	ID of the line item associated with the gift card
`data.gift_card.order_id`	string	`"order_456"`	ID of the order associated with the gift card
`data.gift_card.user_id`	string	`"user_789"`	User ID of the creator or owner of the gift card
`data.gift_card.template_suffix`	string	`"birthday"`	Suffix of the template used to render the gift card online
`data.gift_card.customer_id`	string	`"cust_12345"`	Customer ID associated with the gift card
`data.gift_card.code`	string	`"GIFT123456"`	The gift card code, consisting of alphanumeric characters

Error Response

Field	Type	Example	Description
`code`	string	`InvalidParameter`	Error http message
`message`	string	``	Error message

200OK

400InvalidParameter

500ServerError