Cardigan.js

If your store's theme doesn't support Online Store 2.0 features like theme app extensions, or if you want complete control over how your gift card integration appears and functions, you can build a completely custom integration.

Cardigan.js

Cardigan.js is a Javascript library that targets the browser.

It provides client-side functionality that makes it easier to build custom theme integrations with Cardigan, wrapping functionality like configuration loading and API calls into a simple Javascript API. The source code is available on GitHub, and the compiled and minified browser library is served from the hosted Cardigan CDN.

To use Cardigan.js, you can copy the following code into the bottom of your theme.liquid:

<script id="cardigan-config" type="application/json">
  {{ shop.metafields.cardigan.config }}
</script>
{{ shop.metafields.cardigan.config.value.cardigan_js_uri | default: shop.metafields.cardigan.config.cardigan_js_uri | script_tag }}

Cardigan.js will initialise itself, from which point you can make calls to the Cardigan API like so:

cardigan.api.getBalance({
  number: '394285729834572920394',
  pin: '3424',
  onSuccess: (card) => {
    // this method will run if the API call succeeds, with `card` populated as:
    // {
    //   "currency": "CAD",
    //   "balance": "100.00",
    //   "expires_at": null
    // }
  },
  onError: (error) => {
    // this method will run if the API call fails, with `error` populated as:
    // {
    //   "errors": [
    //     "Invalid PIN"
    //   ]
    // }
  },
  onComplete: () => {
    // this method will always run regardless of result
  }
});

Library version

The snippet above deliberately takes the script URI from your store's Cardigan configuration metafield rather than naming a version.

Your store is pinned to a specific version of Cardigan.js, and the metafield always resolves to that version. Loading it this way means your integration picks up upgrades when your store is moved to a newer release, with no theme change required.

Your pinned version is set by the Cardigan team. If you need to move to a newer release - or hold on a specific one while you test - get in touch.

Debug mode

Cardigan.js can be run in debug mode, which logs its configuration and API activity to the browser console. This is usually the fastest way to see why a custom integration isn't behaving as expected.

Debug mode is enabled per store by the Cardigan team, so contact support if you'd like it switched on while you're building.

Balance checker

To implement a balance checker in a custom theme integration, you have the option of including Cardigan.js on the page as described above, adding the HTML form elements to collect card information, and then wiring up the form to the Cardigan.js API calls with your own script logic.

While you're welcome to do this (and in some situations, this could be the preferred option), Cardigan.js also supports automatically hooking into a HTML <form> element present on the page and adding sensible default behaviour.

To that end, if you add the following HTML to your theme in a custom page template or similar, you should get an out-of-the box balance checking experience similar to the drag and drop balance checker block, but with the ability to fully customise the appearance of the form.

<form data-cardigan-balance-checker="form" method="get" target="_blank">
  <div data-cardigan-balance-checker="result"></div>

  <label>
    Number
    <input data-cardigan-balance-checker="number" type="tel" name="number" value="" />
  </label>

  <label>
    PIN
    <input data-cardigan-balance-checker="pin" type="tel" name="pin" value="" />
  </label>

  <button data-cardigan-balance-checker="submit" type="submit">
    Submit
  </button>
</form>

<script id="cardigan-config" type="application/json">
  {{ shop.metafields.cardigan.config }}
</script>
{{ shop.metafields.cardigan.config.value.cardigan_js_uri | default: shop.metafields.cardigan.config.cardigan_js_uri | script_tag }}

Product form

To implement a product form in a custom theme integration, you simply need to ensure that you're presenting customers with the desired additional information inputs and that they are attached as line item properties when a digital gift card product is added to the cart.

The simplest implementation (capturing all currently supported pieces of additional information) would look like this within your product form:

<div data-cardigan-product-form="form">
  <label>
    Recipient name
    <input data-cardigan-product-form="recipient-name" type="text" name="properties[{{ shop.metafields.cardigan.config.value.property_names.recipient_name }}]" value="" />
  </label>

  <label>
    Recipient email
    <input data-cardigan-product-form="recipient-email" type="email" name="properties[{{ shop.metafields.cardigan.config.value.property_names.recipient_email }}]" value="" />
  </label>

  <label>
    Sender name
    <input data-cardigan-product-form="sender-name" type="text" name="properties[{{ shop.metafields.cardigan.config.value.property_names.sender_name }}]" value="" />
  </label>

  <label>
    Greeting
    <input data-cardigan-product-form="greeting" type="text" name="properties[{{ shop.metafields.cardigan.config.value.property_names.greeting }}]" value="" />
  </label>

  <label>
    Delivery date
    <input data-cardigan-product-form="delivery-date" type="text" name="properties[{{ shop.metafields.cardigan.config.value.property_names.delivery_date }}]" value="" />
  </label>
</div>

Product form association

For the captured values to be attached to the line item, the inputs need to be submitted along with your theme's product form.

Nesting them inside the <form> element achieves this, and is the simplest approach in a custom integration. Where that isn't possible - because your theme's markup doesn't allow the inputs to sit inside the form, or the form is rendered by a section you don't control - associate them explicitly using the HTML form attribute, pointing at the form's id:

<input
  data-cardigan-product-form="recipient-name"
  name="properties[_recipient_name]"
  form="product-form-template--1234__main"
  type="text"
/>

This is also what the product form block does. Because a theme's form id is typically generated from its section and product IDs, the block exposes a Product form ID pattern setting rather than a fixed value, accepting [SECTION_ID] and [PRODUCT_ID] placeholders that are substituted at render time. The theme presets set an appropriate pattern for the themes they target.

If gift cards are reaching the cart without their recipient details attached, this association is the first thing to check. Inspect your product page markup, find the id on the <form> element that submits to the cart, and make sure your inputs are either nested inside it or reference it via the form attribute.

Note that a theme using Ajax add to cart will only submit the inputs the browser considers part of the form - which is precisely what this association establishes, so getting it right resolves most cases where properties go missing.