You can enhance customer experience by integrating Regios Automatic Discounts deeply with your theme.

To do this, use the DOPP (discount on product page) API. It's a combination of event listeners (which you can fire to trigger updates to our app blocks), and public objects/functions (which you can use to handle the results of calculations yourself).

Public API TypeScript Definition

We highly recommend using TypeScript when working with the API.

You can paste this TypeScript definition into your project as a .d.ts file.

Every single export, including functions, classes, and all their parameters, has a useful documentation comment.

Pro tip: You can paste the contents of this TypeScript file into ChatGPT or Copilot for instant assistance in coding your custom integration.

Public API Example

For a collection of real-world examples, check this article out.

Waiting for the API to Initialize

You may have multiple apps and scripts on your site. This makes it a challenge to predict exactly when the "Discounts Embed" will load, and therefore, it's hard to know when window.RegiosDOPP.api.v0 will be available. Use the following snippet to reliably wait to run your integration code until the API is initialized:

const updateWishlistPrices = (api) => {
  console.log("DOPP API initialized", { api });
  // TODO: Add your code here...
};

if (window.RegiosDOPP?.api?.v0) {
  updateWishlistPrices(window.RegiosDOPP.api.v0);
} else {
  window.addEventListener("regios-dopp:api-initialized", (e) => {
    updateWishlistPrices(e.detail.api);
  });
}

You might want to go one step further and hook into document.readyState / DOMContentLoaded event to wait until the page has finished loading to set these listeners up.

On Product Pages

It's easiest to use the API on the product page, where you don't need to provide a product ID or variant ID by default:

const {salePrice, regularPrice} = await window.RegiosDOPP.api.v0.productPage.calculateDiscountedPrices();
const discountAmount = regularPrice.amount - salePrice.amount;
console.log('Your discounted price: ' + salePrice.formatted);
console.log('Discount amount: ' + discountAmount);

You can also pass a specific variant ID, and/or quantity:

const {salePrice, regularPrice} = await window.RegiosDOPP.api.v0.productPage.calculateDiscountedPrices({
  variantId: 0123456789,
  quantity: 1234,
});

You can also get the discount description/badge content, and CSS:

const {description, badge} = await window.RegiosDOPP.api.v0.productPage.calculateDiscountedPrices();
document.querySelector('.discount-description').innerHTML = description.html;
document.querySelector('.discount-description').style.cssText = description.css;
document.querySelector('.badge').innerHTML = badge.html;

You can also override the customer for a calculation. Set to null to calculate as if no customer is logged in. See the "DOPPCustomer" object type in the Public API TypeScript definition linked above to understand the structure.

const {salePrice, regularPrice} = await window.RegiosDOPP.api.v0.productPage.calculateDiscountedPrices({
  variantId: 0123456789,
  quantity: 1234,
  customer: {
    tags: ["b2b", "wholesale"]
  },
  collectionIds: [1234], // If your discount is based on collections, provide this
});

On Other Pages

On all other pages, use window.RegiosDOPP.api.v0.calculateDiscountedPrices instead of window.RegiosDOPP.api.v0.productPage.calculateDiscountedPrices.

You must provide:
productId - Numeric product ID
variantId - Numeric variant ID
regularPriceInCents - The variant's price, before discounts are applied.

Optional arguments:
collectionIds - An array of numerical IDs of all collections the product belongs to. It's optional, but if your discount depends on knowing a product's collections, you must provide this.
compareAtPriceInCents - The variant's "compare at" price.
handle - The product's handle.
vendor - The product's vendor. If your discount depends on knowing a product's vendor, you must provide this.
url - The product's URL. Example /products/foo
quantity - The quantity of the product being discounted. Defaults to 1.
customer - Override the customer for this calculation. Set to null to calculate as if no customer is logged in. See the "DOPPCustomer" object type in the Public API TypeScript definition linked above to understand the structure.

const {salePrice, regularPrice} = await window.RegiosDOPP.api.v0.calculateDiscountedPrices({
  productId: 0123456789,
  variantId: 0123456789,
  regularPriceInCents: 1234,
  collectionIds: [1234], // If your discount is based on collections, provide this
});
const discountAmount = regularPrice.amount - salePrice.amount;
console.log('Your discounted price: ' + salePrice.formatted);
console.log('Discount amount: ' + discountAmount);

Just like in the productPage API, you can override the customer identity for a single calculation.

const {salePrice, regularPrice} = await window.RegiosDOPP.api.v0.calculateDiscountedPrices({
  variantId: 0123456789,
  quantity: 1234,
  customer: {
    tags: ["b2b", "wholesale"]
  },
  collectionIds: [1234], // If your discount is based on collections, provide this
});

Events

Our app listens to the following events on the window:

Variant Change Event

In case your theme has complex behavior about selecting variants on the product page, you can manually trigger a discount calculation by firing a regios-dopp:variant-change event.

Example

window.dispatchEvent(new CustomEvent("regios-dopp:variant-change", {
    detail: {
        selectedVariant: {
            id: 0123456789,
            price: 3000,
        },
        quantity: 1,
    }
}))

// For example, you can refresh the discount on the *product page* with the following:
window.dispatchEvent(new CustomEvent("regios-dopp:variant-change", {
    detail: {
        selectedVariant: RegiosDOPP_ProductPage.variants[0],
        quantity: 1,
    }
}))

Parameters

All parameters are optional unless stated otherwise.
selectedVariant.id: Required. A product variant's numerical ID.
selectedVariant.price: The variant's price, in cents. You can optionally provide this to change the number we base discount calculations on.
quantity: The quantity of the product to calculate the discount based on. Useful for volume discounts.

Collection Page: New Items Event

When new items are loaded on a collection page, you can manually trigger a discount calculation by firing a regios-dopp:collection-page:new-items event.

This is useful if your theme has a "Load More" button or infinite scrolling instead of traditional pagination.

Example

window.dispatchEvent(new CustomEvent("regios-dopp:collection-page:new-items", {
    detail: {
        uniqueKey: "collection-unique-key", // Default is "default". Or you can omit this if you only have one "Collection Page Discount" block on the page.
        newItems: [
            {
                productId: 123456,
                variantId: 654321,
                regularPriceInCents: 2000,
                compareAtPriceInCents: 2500,
                handle: "example-product",
                vendor: "example-vendor",
                url: "/products/example-product",
                tags: ["new", "sale"]
            },
        ]
    }
}));

// For example, you can refresh the discounts on the *collection page* with the following:
window.dispatchEvent(new CustomEvent("regios-dopp:collection-page:new-items", {
    detail: {
        newItems: []
    }
}));

Parameters

To view the parameters for the regios-dopp:collection-page:new-items event, view the DOPPCollectionPageNewItemsEventDetail type in our TypeScript definition file we provided at the start of this article.

Displaying Discounts in Other Places

If you want to display discounts in:
Wishlists
Custom product grids
Anywhere not supported out-of-the-box by our app

You can use the DOPP Theme Interop APIs to easily update on-page prices and automatically show strikethroughs, badges, etc.

Have any feedback for us?

We want to hear about your experience with our app! Leave a review on the Shopify App Store.

Updated on: 03/01/2025