The Givy Storefront API enables the creation of advanced redemption flows and check balance pages.
Accessing the Storefront API
Before you can use the Storefront API, you will need to create a Shop identifier and enable the API. In Givy, go to Settings > API Access, then click Enable in the Storefront API section, and Save to generate your access information.
Take note of the Shop identifier, and Access token, which will be used in all requests to the Storefront API.
Checking a Gift Card Balance
The simplest call to the Storefront API involves sending a gift card code, and returning the current balance.
Givy's check balance endpoint can check balances for any gift card on your store, not only cards created via Givy
The endpoint to check a gift card's current balance is a GET to:
https://api.givy.ai/storefront/v1/shops/<shop-id>/balance?code=<code>
<shop-id> = the Shop Identifier from Givy
<code> = the actual gift card code
If the code is valid, the following data will be returned:
{
"data": {
"amount": 12345,
"amount_formatted": "CA$123.45"
}
}If the code is invalid, the following data will be returned:
{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found"
}
}
Querying a Gift
Now that you have your Shop Identifier and Storefront API, you can look up a Gift Identifier to retrieve information about that gift. The Gift Identifier is automatically appended to the URL of a Custom Redemption Link, in the format:
https://www.customlink.com?giftId=<giftIdentifier>
Givy appends the giftId as a URL parameter, which can be used to fetch additional information about the gift.
Get a Gift
The get endpoint allows you to preview information about a gift before redeeming the gift card code, or the checkout URL for merchandise gifts.
Redeem a Gift
The redeem endpoint allows you to retrieve the gift card code, or the checkout URL for merchandise gifts. In many cases, you may want to use the Redeem endpoint instead of the Get endpoint.
The redeem endpoint uses the following format:
Type: POST
URL: https://api.givy.ai/storefront/v1/shops/<shop-id>/gifts/<public-identifier>/redeem
<shop-id> = the Shop Identifier from Givy
<public_identifier> = the giftId from the URL
When successful, the following data will be returned.
Gift Card Payload
{
"data": {
"public_identifier": "ofna56v1b9sk4pe",
"type": "GIFT_CARD",
"redeemed": true,
"recipient_name": "Jenny",
"purchaser_name": "Frederick",
"gif_url": null,
"video_message_url": null,
"message": "Happy birthday! This is a custom message",
"gift_card": {
"code": "afdh8c9d45e76h7c",
"code_last_four": "6h7c",
"gift_card_image_url": "https:\/\/store.com\/gift_card.jpg",
"start_shopping_url": "https:\/\/store.com",
"balance": {
"amount": 999,
"amount_formatted": "CA$9.99"
}
}
}
}
Merchandise Gift Payload
{
"data": {
"public_identifier": "arssofdbml4wbqc",
"type": "GIFTED_MERCHANDISE",
"redeemed": true,
"recipient_name": "Jane",
"purchaser_name": "Frederick",
"gif_url": null,
"video_message_url": null,
"message": "Happy birthday!",
"merchandise": {
"used": false,
"checkout_url": "https:\/\/garret-2024.myshopify.com\/cart\/c\/Z2NwLXVzLXdlc3QxOjAxSlE3MEY5MjNBNTREMEMyM0NFWkVRODRN?key=7c7bc0e8203508553c2664be2f701aba",
"items": [
{
"index": 0,
"type": "ONE_TIME_PRODUCT",
"product_id": "gid:\/\/shopify\/Product\/7476455473292",
"variant_id": "gid:\/\/shopify\/ProductVariant\/42030736769164",
"product_title": "The Collection Snowboard: Liquid",
"variant_name": "blue - no shipping",
"image_url": "https:\/\/cdn.shopify.com\/s\/files\/1\/0633\/0151\/7452\/products\/Main_b13ad453-477c-4ed1-9b43-81f3345adfd6.jpg?v=1704752048",
"quantity": 1,
"recurrence_count": null,
"selling_plan_name": null
}
]
}
}
}
Convert Merchandise to Gift Card
If you would like to allow recipients to convert their gift to a gift card, use the convert endpoint.
The Convert endpoint only works with merchandise gifts, not gift cards
The convert endpoint uses the following format:
Type: POST
URL: https://api.givy.ai/storefront/v1/shops/<shop-id>/gifts/<public-identifier>/convert
<shop-id> = the Shop Identifier from Givy
<public_identifier> = the giftId from the URL
When successful, the following data will be returned. You will then need to redeem this gift card to retrieve the gift card code.
{
"data": {
"public_identifier": "0flzejle4o0rhvi",
"type": "GIFT_CARD",
"redeemed": false,
"recipient_name": "Fred",
"purchaser_name": "Bob",
"gif_url": null,
"video_message_url": null,
"message": null,
"gift_card": {
"code": null,
"code_last_four": "8646",
"gift_card_image_url": "https://app.staging.givy.ai/static/media/grey_gift_card.jpg",
"start_shopping_url": "https://mystore.myshopify.com",
"balance": {
"amount": 10000,
"amount_formatted": "CA$100.00"
}
}
}
}
Swap Merchandise
If you would like to allow recipients to swap their gift to a new variant, use the swap endpoint.
The Swap endpoint allows updating variants with ones of equal value
The swap endpoint uses the following format:
Type: POST
URL: https://api.givy.ai/storefront/v1/shops/<shop-id>/gifts/<public-identifier>/swap
Form Data
item_index: <item_index>
selected_variant_id: <variant_id>
<shop-id> = the Shop Identifier from Givy
<public_identifier> = the giftId from the URL
<item_index> = the position of the item in the gift. Starts at 0
<variant_id> = the new variant replacing the existing variant
When successful, the following data will be returned. You will then need to redeem this gift to retrieve the checkout URL.
{
"data": {
"public_identifier": "9kstaxwjfs5trok",
"type": "GIFTED_MERCHANDISE",
"redeemed": false,
"recipient_name": "Jane",
"purchaser_name": "Frederick",
"gif_url": null,
"video_message_url": null,
"message": null,
"merchandise": {
"used": false,
"checkout_url": null,
"items": [
{
"index": 0,
"type": "ONE_TIME_PRODUCT",
"product_id": "gid://shopify/Product/7333688967234",
"variant_id": "gid://shopify/ProductVariant/41601434976322",
"product_title": "My Product Name",
"variant_name": "Medium / Blue",
"image_url": "https://cdn.shopify.com/s/files/1/0565/8145/5938/files/81e5e07b-1eb3-44ed-aa36-03999333fad56.jpg?v=1708457176",
"quantity": 1,
"recurrence_count": null,
"selling_plan_name": null
}
]
}
}
}