How to Setup Gift Card Widget on Your Store

Vanilla JS method:

GiftcardWidget.init({
  container: "#giftcard-container",
  client_id: '<API_KEY_HERE>',
  platform: 'BIGCOMMERCE', // One of SHOPIFY, BIGCOMMERCE, WOOCOMMERCE, WORDPRESS, NONE
  currency: 'USD', // ISO 4217 code. Current active currency in session.
  show_currency_picker: true, // Whether to show currency picker in multi-currency mode.
  single_page: false, // Show only single page
  default_page: 'PURCHASE', // One of PURCHASE, CHECK_BALANCE
  onInit: () => {}, // Callback when the widget is initialized and finished loading.
  beforeAddToCart: (payload, formatted_payload) => {}, // Callback before Add to Cart is done. When provided, the widget does not redirect to cart autmatically.
  onAddToCart: (data) => {}, // Callback when Add to Cart is finished. When provided, the widget does not redirect to cart autmatically.
  onCurrencyChange: (data) => {}, // Callback when currency is changed in widget.
  getCartDetails: () => {}, // Should return a simple object containing current `cart_id`, i.e { cart_id: 'xxxxx' }
  getCurrentCustomer: () => {}, // Should return a simple object containing current logged in customer data, i.e { id: 'xxxxx', email: '[email protected]', name: 'Jhon Doe' }. `id` is required.
  channel_id: 6425, // Should be provided when using multistorefront on Bigcommerce as mentioned here - https://developer.bigcommerce.com/docs/storefront/multi-storefront/guide#cart-and-checkout,
  setLanguages: () => {}, // The setLanguages function is responsible for returning a JSON object that contains translations for various text labels in different languages. The object should use the language prefix (e.g., "en", "es", "fr", "de", "ar") as the root key, with each key holding an object of translated text labels.,
  language: 'en', // For ex, en, fr, de, ar, etc
  // Other options.....
})

Click to check all other options available for the widget ↓

GiftcardWidget.init({
  "layout": "LAYOUT2",
  "show_currency_picker": true, // Whether to show currency picker in multi-currency mode.
  "single_page": false, // Show only single page
  "default_page": 'PURCHASE', // One of PURCHASE, CHECK_BALANCE
  "default_image_url": "https://development-doboz-assets.s3-ap-southeast-1.amazonaws.com/in/giftcards/styles/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b/medium_rectangle_your-themes-5f31a180dd780ea2d5.png",
  "purchase_giftcard_tab_label": "Purchase",
  "check_balance_tab_label": "Check Balance",
  "home_tab_label": "Home",
  "show_themes": true,
  "amount_list": [
      10,
      15,
      20,
      25,
      100
  ],
  "promo_code_flag": true,
  "allow_custom_value": false,
  "allow_send_later": true,
  "name_label": "Your name",
  "email_label": "Your email",
  "send_as_gift_label": "Send as a gift",
  "recipient_name_label": "Recipient name",
  "recipient_email_label": "Recipient email",
  "custom_message_label": "Write my own...",
  "add_to_cart_button_label": "Add to cart",
  "plan": "PREMIUM",
  "primary_color": "#6366F1",
  "secondary_color": "#C4CBD4",
  "text_color": "#000000",
  "invert_text_color": "#FFFFFF",
  "background_color": "FFFFFF",
  "font": "'Lato', sans-serif",
  "shipping_charge": 0,
  "sales_tax": 0,
  "allow_template_messages": true,
  "custom_messages": [{
    "Collegue": ["message 1", "message 2"],
    "Family Member": ["message 3", "message 4"]
  }],
  "allow_photo_video_upload": true,
  "delivery_mode": "DIGITAL", // One of "DIGITAL, PHYSICAL, BOTH
  "digital_giftcard_label": "Send eGift card via Email",
  "physical_giftcard_label": "Send Physical Gift card via Mail",
  "select_delivery_mode_heading": "Select an option to proceed",
  "checkout_mode": "DROP-IN" // One of "INTEGRATED, DROP-IN,
  "check_balance_input_label":"Enter gift card number",
  "deliver_now_label":"Deliver Now",
  "deliver_now_subtitle":"SEND GIFT CARD INSTANTLY",
  "deliver_later_label":"Deliver Later",
  "deliver_later_subtitle":"SEND GIFT CARD ON A FUTURE DATE",
  "select_date_label":"Select Date",
  "deliver_later_info_text":"Gift cards can be delivered up to 3 months from today",
  "tos_text":"I agree that Gift cards are non-refundable"
})

All options configurable from the dashboard can also be passed as inline options.

Adding widget to an HTML page.

Change the script URL as per the environment:

Environment	URL
PRODUCTION	https://assets.99minds.io/live/giftcard/bundle.js
ENTERPRISE1	https://assets.99minds.io/enterprise1/giftcard/bundle.js
STAGING	https://assets.99minds.io/staging/giftcard/bundle.js
QA	https://assets.99minds.io/qa/giftcard/bundle.js
DEV	https://assets.99minds.io/dev/giftcard/bundle.js

After that Generate API key from Settings > API with scope STOREFRONT.GIFTCARDS and copy the Key ID to client_id below:

<div id="giftcard-container"></div>
<script type="text/javascript" src="https://assets.99minds.io/live/giftcard/bundle.js"></script>
<script type="text/javascript">
  GiftcardWidget.init({
    container: "#giftcard-container",
    client_id: '<API_KEY_HERE>',
    platform: 'NONE'
  })
</script>

Callback: onAddToCart

Sample payload returned by onAddToCart

{
  "delivery_channel": "EMAIL",
  "delivery_mode": "DIGITAL",
  "currency_code": "USD",
  "currency_symbol": "$",
  "amount": "20.00",
  "quantity": 1,
  "sender_name": "Mrudul",
  "sender_email": "[email protected]",
  "message": "Here's your gift card...",
  "isGift": false,
  "scheduled": false,
  "deliver_at": null,
  "deliver_at_timezone": null,
  "style_id": "image_a2990f72fd39758e88",
  "style_image_url": "https://99minds-staging-assets.s3.amazonaws.com/in/giftcards/styles/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b/medium_square_your-themes-f60d5b8491206e1775.png",
  "id": "4875a74-06c8-cfc4-8af-f17655ddc2fc"
}

Callback: beforeAddToCart

Sample payload returned by beforeAddToCart

Note: beforeAddToCart is only applicable for Shopify storefronts.

This payload is identical to what we send to the Shopify Ajax Cart API, as detailed here - Storefront Cart APIs. The id parameter represents the variant ID of the product generated by 99minds.

You will need to transform this returned object into a GraphQL mutation for managing the cart, as outlined in the Shopify documentation here - Manage Cart. The key element to focus on is the 'merchandiseId'.

You can use the cartCreate mutation to create a new cart and add a line item to the cart. In the input, include the line item quantity (quantity) and the product variant ID (merchandiseId), and specify any attributes (attributes) associated with the cart.

{
  "items": [
    {
      "id": 48687818670399,
      "quantity": 1,
      "properties": {
        "_delivery_mode": "DIGITAL",
        "_sender_name": "Mrudul",
        "_sender_email": "[email protected]",
        "_is_gift": false,
        "_scheduled": false,
        "_deliver_at": null,
        "_deliver_at_timezone": null,
        "_style_id": "image_8d90c7320ac51d8ab6",
        "Recipient Email": "[email protected]",
        "Delivery": "Instant"
      }
    }
  ]
}

Using a custom product page template on Shopify

When a customer purchases a gift card from your theme's default product page, 99minds retrieves the buyer's details from the billing address at checkout and delivers the card directly to them. Without customizing the product template, customers can only purchase gift cards for themselves.

To allow customers to send gift cards to others, you need to modify the template. Before making any changes, be sure to duplicate your existing product template.

The additional properties required by 99minds are:

Name	Key	Data Type	Required	Note
Delivery Mode	_delivery_mode	String	Required	Harcoded - 'DIGITAL' for digital gift card. 'PHYSICAL' for physical gift card
Sender Name	_sender_name	String	Optional	Input
Sender Email	_sender_email	String	Optional	Input - Email
Is Gift	_is_gift	Boolean	Optional	Input - Checkbox
Receiver Name	_receiver_name	String	Required when Is Gift	Input
Receiver Email	_receiver_email	String	Required when Is Gift	Input - Email
Greeting Message	_message	String	Optional	Input - Email
Scheduled	_scheduled	Boolean	Optional	Input - Checkbox
Deliver At	_deliver_at	String	Optional	ISO8601 formatted date Input - DateTime
Deliver At Timezone	_deliver_at_timezone	String	Optional	Ex. US/Eastern. Input - Hidden

These properties needs to be added to the line_item properties of Shopify. This is also mentioned in Shopify documentation.

There is also a UI tool which helps to generate code for inputs.

Once the properties are set correctly in the line items, 99minds will pick it up and deliver the gift card to the receipient along with other details like message, schedule time, etc.

Hiding line item properties from shopify cart

By default, Shopify's themes, including Dawn, hide cart line item properties that start with an underscore _. However, this behavior may vary depending on the theme you are using or if you have a custom theme. If your theme does not automatically hide these properties, you can implement the same functionality by using the code snippet provided in Shopify's default theme (Dawn) to hide such properties from the cart page.

Here's the code snippet:

{%- for property in item.properties -%}
  {%- assign property_first_char = property.first | slice: 0 -%}
  {%- if property.last != blank and property_first_char != '_' -%}
    <div class="product-option">
      <dt>{{ property.first }}:</dt>
      <dd>
        {%- if property.last contains '/uploads/' -%}
          <a href="{{ property.last }}" class="link" target="_blank">
            {{ property.last | split: '/' | last }}
          </a>
        {%- else -%}
          {{ property.last }}
        {%- endif -%}
      </dd>
    </div>
  {%- endif -%}
{%- endfor -%}

This snippet simply prints line item properties that don’t start with an underscore (_).

Multiple Currency Support

99minds makes it easy to offer gift cards in multiple currencies. Customers can purchase and redeem gift cards in their preferred currency, with each currency managed in its own campaign. While this isn't available in Shopify by default, 99minds handles all currency conversions automatically using Shopify's current rates.

Follow these steps to set up multi-currency gift cards on your Shopify store:

Setup Instructions

Cut the HTML code from the gift card page which 99minds create when app is installed.
Save the page (Yes, it will be empty for now)
Open the gift card page in the Customize theme section
Click Add Section and choose Custom Liquid
Paste the code from Step 1 into the custom liquid section on the right
Add multi-currency options:
- show_currency_picker: false
- currency: '{{localization.country.currency.iso_code}}'
Save and refresh the page
Verify prerequisites:
- Campaigns for each currency are created in 99minds
- Markets have been configured in the Shopify integrations section on 99minds

Final Code Example

<div id="giftcard-container"></div>

<script src="https://assets.99minds.io/qa/giftcard/bundle.js" type="text/javascript"></script>

<script type="text/javascript">
  GiftcardWidget.init({
    container: '#giftcard-container',
    client_id: '<API_KEY>',
    platform: 'SHOPIFY',
    myshopify_domain: 'your-store.myshopify.com',
    currency: '{{localization.country.currency.iso_code}}',
    show_currency_picker: false
  });
</script>

Note: Replace <API_KEY> with your actual 99minds API key and update myshopify_domain with your store's domain.

The gift card widget will now show prices in the customer's local currency based on their region selection.

Multiple Language Support

The widget allows you to customize labels in your preferred language. There are two methods for supplying translations:

Passing the labels directly through the widget's init method.
Implementing a languages object.

1. Direct usage

You can pass the labels directly when initializing the widget using GiftcardWidget.init({}). The available labels include:

Label

home_tab_label

purchase_giftcard_tab_label

check_balance_tab_label

name_label

email_label

send_as_gift_label

recipient_name_label

recipient_email_label

custom_message_label

add_to_cart_button_label

digital_giftcard_label

physical_giftcard_label

select_delivery_mode_heading

check_balance_input_label

check_balance_button_label

deliver_now_label

deliver_now_subtitle

deliver_later_label

deliver_later_subtitle

select_date_label

deliver_later_info_text

tos_text

2. setLanguages method

The languages object is responsible for returning a JSON object that contains translations for various text labels in different languages. The object should use the language prefix (e.g., "en", "es", "fr", "de", "ar") as the root key, with each key holding an object of translated text labels.

Then pass language with the appropriate language prefix.

{
  "de": {
    "purchase_giftcard_tab_label": "Kaufen",
    "check_balance_tab_label": "Guthaben überprüfen",
    "name_label": "Ihr Name",
    "email_label": "Ihre E-Mail",
    "send_as_gift_label": "Als Geschenk senden",
    "recipient_name_label": "Name des Empfängers",
    "recipient_email_label": "E-Mail des Empfängers",
    "custom_message_label": "Eigene Nachricht schreiben...",
    "add_to_cart_button_label": "In den Warenkorb",
    "digital_giftcard_label": "eGeschenkkarte per E-Mail senden",
    "physical_giftcard_label": "Physische Geschenkkarte per Post senden",
    "select_delivery_mode_heading": "Wählen Sie eine Option, um fortzufahren",
    "check_balance_input_label": "Geschenkkartennummer eingeben",
    "deliver_now_label": "Sofort liefern",
    "deliver_now_subtitle": "GESCHENKKARTE SOFORT SENDEN",
    "deliver_later_label": "Später liefern",
    "deliver_later_subtitle": "GESCHENKKARTE AN EINEM SPÄTEREN DATUM SENDEN",
    "select_date_label": "Datum auswählen",
    "deliver_later_info_text": "Geschenkkarten können bis zu 3 Monate im Voraus geliefert werden",
    "tos_text": "Ich stimme zu, dass Geschenkkarten nicht erstattungsfähig sind",
    "home_tab_label": "Startseite",
    "check_balance_button_label": "Guthaben prüfen"
  },
  "fr": {},
  "es": {}
}

Using different theme images on different stores

Just pass the images option to the initialization code to overwrite the default images:

images: [
  {
    "style_id": "image_587c6e26d97360c15f",
    "style_code": null,
    "default_image": true,
    "sort_order": 0,
    "giftcard_type": "DIGITAL",
    "medium": "https://s3.amazonaws.com/99minds.giftcard.production.assets/in/giftcards/styles/e81d47bc1914daacdfe3670959ae7f749fd47976471fc68ed00041f6150c80b6/medium_square_your-themes-c0eb8bc05590cc11a7.png",
    "thumb": "https://s3.amazonaws.com/99minds.giftcard.production.assets/in/giftcards/styles/e81d47bc1914daacdfe3670959ae7f749fd47976471fc68ed00041f6150c80b6/thumb_square_your-themes-c0eb8bc05590cc11a7.png"
  },
  {
    "style_id": "image_a29276f3be42c433a6",
    "style_code": null,
    "default_image": false,
    "sort_order": 0,
    "giftcard_type": "DIGITAL",
    "medium": "https://s3.amazonaws.com/99minds.giftcard.production.assets/in/giftcards/styles/e81d47bc1914daacdfe3670959ae7f749fd47976471fc68ed00041f6150c80b6/medium_square_your-themes-4c1f6b4b9538b3f58b.png",
    "thumb": "https://s3.amazonaws.com/99minds.giftcard.production.assets/in/giftcards/styles/e81d47bc1914daacdfe3670959ae7f749fd47976471fc68ed00041f6150c80b6/thumb_square_your-themes-4c1f6b4b9538b3f58b.png"
  },
  {
    "style_id": "image_e82e3c032375ddcc17",
    "style_code": null,
    "default_image": false,
    "sort_order": 0,
    "giftcard_type": "DIGITAL",
    "medium": "https://s3.amazonaws.com/99minds.giftcard.production.assets/in/giftcards/styles/e81d47bc1914daacdfe3670959ae7f749fd47976471fc68ed00041f6150c80b6/medium_square_your-themes-3a49d3f8840aa0d07f.png",
    "thumb": "https://s3.amazonaws.com/99minds.giftcard.production.assets/in/giftcards/styles/e81d47bc1914daacdfe3670959ae7f749fd47976471fc68ed00041f6150c80b6/thumb_square_your-themes-3a49d3f8840aa0d07f.png"
  }
]

Sample usage in React based frameworks:

import React, { useEffect } from 'react';

const WidgetComponent = ({ apiKey }) => {
  
  useEffect(() => {
    // Load the external script
    const script = document.createElement("script");
    
    // The below url will changes as per environment. Contact support for more details.
    script.src = "https://assets.99minds.io/live/giftcard/bundle.js";
    script.async = true;
    script.onload = () => {
      if (window.GiftcardWidget) {
        window.GiftcardWidget.init({
          container: "#giftcard-container",
          client_id: apiKey,
          platform: 'NONE'
          // Add more options as needed.
        });
      }
    };
    document.body.appendChild(script);
    return () => {
      document.body.removeChild(script);
    }
  }, [apiKey]);

  return <div id="giftcard-container"></div>;
}

export default WidgetComponent;

// Usage in your page:
import WidgetComponent from './WidgetComponent';

function App() {
  return (
    <div>
      <WidgetComponent apiKey='<API_KEY_HERE>' />
    </div>
  );
}

export default App;

What is a Gift Card?

Shopify Multi-Currency Gift Card Setup

How to use 99minds Loyalty SDK

How To Setup 99minds Loyalty Page On Your Website

How To Add 99minds Loyalty Widget On Your Website