> For the complete documentation index, see [llms.txt](https://hthcapital.gitbook.io/izigift-help-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hthcapital.gitbook.io/izigift-help-docs/basics/edit-send-as-gift-button/custom-gift-modal.md).

# Custom Gift Card Modal

If you want full control over the look and feel of your gift card sending experience, you can build your own custom modal or form and use iziGift's helper API to handle the cart and fulfillment logic.

This is ideal for merchants who want their gift card UI to match their brand exactly, or who have an existing custom checkout flow they want to integrate with.

## Prerequisites

1. **iziGift app installed** with at least one gift card product configured
2. **Theme app extensions enabled** in your Shopify admin

## Setup

### Step 1: Enable Custom Modal Mode

1. From your Shopify admin, go to **Online Store > Themes** and click **Customize**
2. Find the **Send as gift button** block (from iziGift)
3. Change **Modal mode** to **"Merchant custom modal"**
4. Click **Save**

This tells iziGift to stop injecting its built-in modal and stop hiding your native add-to-cart button. The helper API (`window.iziGift`) is still loaded and ready to use from your own code.

### Step 2: Build Your Form

Create your own form however you like — in a theme section, a snippet, or plain HTML/JS. Your form needs to collect the following from the customer:

| Field                | Required                        | Description                                                   |
| -------------------- | ------------------------------- | ------------------------------------------------------------- |
| Recipient first name | At least one of first/last name | Recipient's first name                                        |
| Recipient last name  | At least one of first/last name | Recipient's last name                                         |
| Recipient email      | Yes (unless sending to self)    | Where the gift card is delivered                              |
| Sender name          | Yes (unless sending to self)    | Shown in the gift card email                                  |
| Message              | No                              | Personal message to the recipient                             |
| Scheduled date       | No                              | Delivery date (`YYYY-MM-DD`). Leave empty to send immediately |

### Step 3: Use the Helper API

Once your form collects the data, pass it to the iziGift helper API. It validates the input, formats everything correctly for the backend, and adds the gift card to the Shopify cart.

## Helper API Reference

### `window.iziGift.validateGiftCardPayload(payload)`

Checks a payload before submitting. Useful if you want to show your own error messages.

**Returns:** `{ valid: boolean, errors: string[] }`

### `window.iziGift.addGiftCardToCart(payload, options)`

Validates the payload, adds the gift card to cart with the correct line-item properties, and returns a Promise.

**Payload:**

| Field                | Type          | Required              | Description                                                      |
| -------------------- | ------------- | --------------------- | ---------------------------------------------------------------- |
| `recipientFirstName` | string        | At least one name     | Recipient's first name                                           |
| `recipientLastName`  | string        | At least one name     | Recipient's last name                                            |
| `recipientEmail`     | string        | Unless `sendToMyself` | Recipient's email                                                |
| `senderName`         | string        | Unless `sendToMyself` | Sender's name                                                    |
| `message`            | string        | No                    | Personal message                                                 |
| `scheduledDate`      | string        | No                    | `YYYY-MM-DD` format                                              |
| `sendToMyself`       | boolean       | No                    | If `true`, email and sender name are optional                    |
| `variantId`          | number/string | No                    | Shopify variant ID. Defaults to the current product page variant |

**Options:**

| Option         | Type    | Default | Description                               |
| -------------- | ------- | ------- | ----------------------------------------- |
| `goToCheckout` | boolean | `false` | Redirect to checkout after adding to cart |

## Example

Here's a simple form that collects gift card details and adds the gift card to cart:

```html
<form id="my-gift-form">
  <input type="text" id="gift-first-name" placeholder="Recipient first name" required>
  <input type="text" id="gift-last-name" placeholder="Recipient last name" required>
  <input type="email" id="gift-email" placeholder="Recipient email" required>
  <input type="text" id="gift-sender" placeholder="Your name" required>
  <textarea id="gift-message" placeholder="Write a message (optional)"></textarea>
  <input type="date" id="gift-date">
  <button type="submit">Send Gift Card</button>
  <p id="gift-error" style="color: red; display: none;"></p>
</form>

<script>
  document.getElementById('my-gift-form').addEventListener('submit', function(e) {
    e.preventDefault();
    var errorEl = document.getElementById('gift-error');
    errorEl.style.display = 'none';

    var payload = {
      recipientFirstName: document.getElementById('gift-first-name').value,
      recipientLastName: document.getElementById('gift-last-name').value,
      recipientEmail: document.getElementById('gift-email').value,
      senderName: document.getElementById('gift-sender').value,
      message: document.getElementById('gift-message').value,
      scheduledDate: document.getElementById('gift-date').value
    };

    // Validate first to show your own errors
    var result = window.iziGift.validateGiftCardPayload(payload);
    if (!result.valid) {
      errorEl.textContent = result.errors.join(' ');
      errorEl.style.display = 'block';
      return;
    }

    // Add to cart and go to checkout
    window.iziGift.addGiftCardToCart(payload, { goToCheckout: true })
      .catch(function(err) {
        errorEl.textContent = err.message;
        errorEl.style.display = 'block';
      });
  });
</script>
```

## Important Notes

* **The helper API is only available on iziGift product pages** — products with the product type set to `iziGift` in Shopify.
* **Bulk purchases are not supported** through the helper API. The bulk flow requires server-side validation via iziGift's internal endpoints.
* **Send-to-self** is supported: set `sendToMyself: true` and the email/sender fields become optional. The customer will receive the gift card at their own checkout email.

## Troubleshooting

### `window.iziGift` is undefined

* Make sure you're on an iziGift product page (the product type must be `iziGift` in Shopify)
* Make sure the iziGift **Send as gift button** block is enabled in your theme

### Gift cards not being fulfilled after purchase

* Double-check that you're using `window.iziGift.addGiftCardToCart()` to add items to the cart
* Check that your gift card product has type `iziGift` in Shopify

### Native add-to-cart button still hidden

* Confirm **Modal mode** is set to **"Merchant custom modal"** in the theme editor
* Save your theme and refresh the page

## Support

If you need help setting up a custom modal:

1. Check this documentation first
2. Contact iziGift support through the app dashboard

***

*Note: Custom modal mode is available for all iziGift plans and requires theme app extensions to be enabled.*