If you're new to working with JSON, we recommend that you contact us to integrate with your theme.

Abra uses a JSON schema to configure your Abra blocks. You can change your global schema to integrate better with your theme and create richer online store experiences for buyers.

These customizations will apply to every promotion.

Getting started

Before changing your JSON schema, we recommend that you:

1. Create a backup of your schema

2. Validate your changes in a JSON validator

To change your schema, go to the "Settings" page and then select "Edit JSON file". You'll see a default schema in the code editor.

At any point, you can revert to the latest default for your theme by clicking "Revert to default".

The schema uses the outline shown below. You can replace the capitalized placeholders with the values found in the table under the example.

{
  "schema": {
    "TEMPLATE": {
      "BLOCK_ID": {
        "type": "BLOCK_TYPE",
        "PROPERTY_NAME": "PROPERTY_VALUE"
      }
    }
  }
}

Example

A promotion using a popup block in the schema.

{
  "schema" {
    "all" {
      "dd1627cb-428e-4b7d-bc05-dd96cc6cb50a": {
        "type": "popup",
        "persistentState": true,
        "states": [
          {
            "state": "DEFAULT",
            "text": "20% APPLIED"
          }
        ]
      }
    }
  }
}

Blocks

Blocks are the pieces nested within the template in your schema. There are 3 types of blocks:

1. Object block - dynamically access an object and update some HTML

2. Element block - render elements and customize block content from your promotion

3. Method block - manipulate different parts of your storefront with these helpers

Product object block

Only applies when the product is eligible for the active promotion.

The product block allows you to replace a block of HTML with new HTML. You can use the product context in the rendered HTML.

In addition to container and selector, you can use dataAttributes to tell Abra how to locate product information directly from DOM attributes or nearby elements. This is useful for custom storefronts, product cards, headless builds, and page builders where product links are not the only reliable source of product context.

Block properties

Liquid variables

Selected variant and selling plan liquid variables

When using the above liquid variables to update the product price, it is recommend to use them in conjunction with selected variant and selling plan liquid variables to show the price of a specified product variant.

Example: Product template

Change your product detail template .price element to include the final price and a slashed compare at price.

{
  "schema": {
    "all": {
      "main-product-price": {
        "type": "product",
        "selector": ".price",
        "html": "<div class=\"price\"><div class=\"price--sale\">{{ selected_variant.final_price }}</div><div class=\"price--regular\"><s>{{ selected_variant.compare_at_price }}</s></div></div>"
      }
    }
  }
}

Example: Collection template

Change your collection template product card .price element to include the final price and a slashed compare at price.

{
  "schema": {
    "all": {
      "collection-product-price": {
        "type": "product",
        "container": ".product-card",
        "selector": ".product-card .price",
        "html": "<div class=\"price\"><div class=\"price--sale\">{{ selected_variant.final_price }}</div><div class=\"price--regular\"><s>{{ selected_variant.compare_at_price }}</s></div></div>"
      }
    }
  }
}

dataAttributes additional references

dataAttributes

Optional configuration object used to help Abra identify the product, variant, selling plan, or product URL from attributes or nearby elements in the DOM.

Use this when:

• Product cards do not expose all context through the main product link

• Variant or selling plan data is already stored in data-* attributes

• Your theme or page builder outputs custom product markup

selector

DOM selector for the element Abra should update.

In this example:

"selector": ".card .price"

Abra will target the .price element inside .card.

direction

Tells Abra where to look from the matched element when resolving a value.

Example:

"direction": "closest"

This means Abra starts from the matched element and moves upward to find the nearest relevant ancestor.

attr

The name of the DOM attribute Abra should read.

Example:

"attr": "data-replo-variant"

productHandle

Tells Abra how to find the Shopify product handle from the DOM (default Shopify product handle attribute is data-product-handle).

Example:

"productHandle": {
  "attr": "data-replo-product",
  "direction": "closest"
}

This means:

• Look for a data-replo-product attribute

• Search using the closest direction

• Use that attribute’s value as the product handle

If the nearest parent element contains:

<div class="card" data-replo-product="bicycle-helment">

Abra resolves the product handle as bicycle-helment.

variantId

Tells Abra how to find the selected or relevant Shopify variant ID (default Shopify variant ID attribute is data-variant-id).

Example:

"variantId": {
  "attr": "data-replo-variant"
}

sellingPlanId

Tells Abra how to find the selected selling plan ID from the DOM (default Shopify selling plan ID attribute is data-selling-plan-id).

Example:

"sellingPlanId": {
  "attr": "data-custom-plan"
}

productUrl

Tells Abra how to resolve the product URL from a nearby element.

Example:

"productUrl": {
  "selector": "a.product-link",
  "attr": "href",
  "direction": "querySelector"
}

This means:

• Find the first a.product-link

• Use querySelector to search within the current context

• Read its URL as the product URL

Use this when the product link is still the best source for the URL, but other product data comes from attributes.

Example: Custom page builder

{
  "schema": {
    "all": {
      "replo-card-product-price": {
        "type": "product",
        "selector": ".card .price",
        "container": ".card",
        "dataAttributes": {
          "direction": "closest",
          "productHandle": {
            "attr": "data-replo-product",
            "direction": "closest"
          },
          "variantId": {
            "attr": "data-replo-variant"
          },
          "sellingPlanId": {
            "attr": "data-custom-plan"
          },
          "productUrl": {
            "selector": "a.product-link",
            "attr": "href",
            "direction": "querySelector"
          }
        },
        "html": "<div class=\"price\"><div class=\"price--sale\">{{ selected_variant.final_price }}</div><div class=\"price--regular\"><s>{{ selected_variant.compare_at_price }}</s></div></div>"
      }
    }
  }
}

Announcement bar element block

The announcement-bar block allows you to show and update the content of your announcement bar.

Block properties

Block state properties

A block state allows you to show different content based on the state of the promotion and discount.

Liquid variables

Example

Showing an announcement bar with a gift icon and some text.

{
  "schema": {
    "all": {
      "gift-announcement-bar": {
        "type": "announcement-bar",
        "persistentState": true,
        "states": [
          {
            "icon": "gift",
            "state": "DEFAULT",
            "text": "FREE GIFT ON ORDERS OVER $50"
          }
        ]
      }
    }
  }
}

Banner element block

The banner block allows you to show and update the content of your banner.

Block properties

Block state properties

A block state allows you to show different content based on the state of the promotion and discount.

Liquid variables

Example

Showing a banner with a discount icon and some text.

{
  "schema": {
    "all": {
      "gift-banner": {
        "type": "banner",
        "name": "default",
        "persistentState": true,
        "states": [
          {
            "icon": "discount",
            "state": "DEFAULT",
            "text": "FREE GIFT ON ORDERS OVER $50"
          }
        ]
      }
    }
  }
}

Popup element block

The popup block allows you to show and update the content of your popup.

Block properties

Block state properties

A block state allows you to show different content based on the state of the promotion and discount.

Liquid variables

Example

Showing a popup with some text

{
  "schema": {
    "all": {
      "custom-popup": {
        "type": "popup",
        "persistentState": true,
        "states": [
          {
            "state": "DEFAULT",
            "text": "{{ code }} APPLIED"
          }
        ]
      }
    }
  }
}

Hide method block

The hide block allows you to hide an element when the promotion is active.

Block properties

Example

Hiding your footer element.

{
  "schema": {
    "all": {
      "hide-footer": {
        "type": "hide",
        "selector": ".footer"
      }
    }
  }
}

Add class method block

The add-class block allows you to add a class to an element when the promotion is active.

Block properties

Example

Adding a vip-customer class to the body element.

{
  "schema": {
    "all": {
      "vip-customer-style": {
        "type": "add-class",
        "selector": "body",
        "value": "vip-customer"
      }
    }
  }
}

Remove class method block

The remove-class block allows you to remove a class to an element when the promotion is active.

Block properties

Example

Removing a hidden class from a navigation item.

{
  "schema": {
    "all": {
      "show-special-nav-item": {
        "type": "remove-class",
        "selector": ".nav .nav-item--vip",
        "value": "hidden"
      }
    }
  }
}

Theme examples

See our GitHub repository for more examples.