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>
Authorization: Bearer <token>
<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.
The get endpoint uses the following format:
Type: POST
URL: https://api.givy.ai/storefront/v1/shops/<shop-id>/gifts/<public-identifier>
Authorization: Bearer <token>
<shop-id> = the Shop Identifier from Givy
<public_identifier> = the giftId from the URL
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
Authorization: Bearer <token>
<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
Authorization: Bearer <token>
<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. If the new variant is more expensive than the gifted variant, the recipient will be required to pay the difference at checkout.
The Swap endpoint can only be used on a gift that has not been redeemed ("redeemed": false). It is also incompatible with products which have different prices per Market using Shopify's Catalogs.
The swap endpoint uses the following format:
Type: POST
URL: https://api.givy.ai/storefront/v1/shops/<shop-id>/gifts/<public-identifier>/swap
Authorization: Bearer <token>
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
}
]
}
}
}
Upsell on Redemption Page
Sometimes it's nice to give recipients a chance to add a product to their cart alongside their gifted product. This is where Givy's upsell endpoint can help.
The upsell (additions) endpoint uses the following format to add a product to the recipient's cart:
Type: POST
URL: https://api.givy.ai/storefront/v1/shops/<shop-id>/gifts/<public-identifier>/additions
Authorization: Bearer <token>
application/json
{
additions: {
shopify_variant_id: <variant_id>,
quantity: 1,
discount_code: <discount_code> // optional - contact Givy to set up
}
}
To delete an addition that has already been added:
Type: DELETE
URL: https://api.givy.ai/storefront/v1/shops/<shop-id>/gifts/<public-identifier>/additions
Form Data
item_index: <item_index>
<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
<discount_code> = a Givy-specific discount that is created upon request
Note that the recipient will have their gifted product, along with the added variant, in their cart, and will only be charged for the added variant.
Troubleshooting
The Storefront API will return a 422 error message for a variety of reasons. If you encounter one of these message, see the detailed message for additional information.
Example message:
application/json
{
error: {
code: 'VARIANT_NOT_FOUND',
message: 'A variant no longer exists in Shopify'
}
}