JavaScript API

Omake exposes a JavaScript API on every page where the Omake theme block is active. Use it to trigger custom promotions, select gift variants, manage state, or build a fully custom UI in headless mode.

Accessing the API

The API is available at window.Omake. Before calling any methods, wait for the omake:ready event:

document.addEventListener('omake:ready', function() {
  // Omake API is now available
  const state = Omake.getState();
  console.log('Unlocked tiers:', state.tiers.filter(t => t.unlocked).length);
});

Do not call Omake methods before the omake:ready event fires. The object may not exist yet.

Methods

getConfig()

Returns the current Omake configuration object, or null if not loaded yet. Contains tiers, gift mode, widget configuration, and other settings.

const config = Omake.getConfig();

Useful for reading your tier setup on the client without making additional API calls.

getState()

Returns the current state object:

const state = Omake.getState();

The returned object has this shape:

Property	Type	Description
`triggers`	`string[]`	Currently active custom trigger events
`tiers`	`TierState[]`	All configured tiers with progress info
`giftValue`	`number`	Total value of unlocked gifts, in cents
`omakeProductId`	`number \| null`	The gift bag product ID
`ready`	`boolean`	`true` when no API calls are in-flight

Each tier in the tiers array has:

Property	Type	Description
`unlocked`	`boolean`	Whether the customer has met this tier's threshold
`passed`	`boolean`	Whether the customer has passed this tier
`progress`	`number`	Current progress toward the threshold
`remaining`	`number`	How much more is needed to unlock
`lockedText`	`string`	Display text for the locked state
`gifts`	`GiftState[]`	Gifts available at this tier

Each gift in gifts has:

Property	Type	Description
`name`	`string`	Gift product name
`variantId`	`string`	Default variant ID
`variantGid`	`string`	Default variant GID
`quantity`	`number`	Quantity of this gift
`eligibleVariantIds`	`string[] \| null`	Available variant options, or `null` if single-variant
`selectedVariantGid`	`string \| undefined`	Currently selected variant GID (multi-variant gifts only)

trigger(event)

Triggers a custom event, unlocking any tiers that use this event name as their condition.

await Omake.trigger('loyalty_member');

The event string accepts alphanumeric characters, underscores, hyphens, dots, and equals signs. Maximum 100 characters.

The trigger is persisted in localStorage and synced to the cart metafield on the server. It expires after 14 days.

Returns a Promise that resolves with the server response.

Custom triggers are perfect for loyalty programs, email opt-ins, quiz completions, or any event-driven promotion. Pair them with the "Custom trigger" tier type in the Omake admin.

revoke(event)

Removes a previously triggered event. Clears it from both localStorage and the cart metafield.

await Omake.revoke('loyalty_member');

Returns a Promise.

selectGift(tierId, variantId)

Selects a specific variant for a multi-variant gift. Use this when a gift product has multiple options (e.g., size or color) and you want to let the customer choose.

await Omake.selectGift(
  'gid://shopify/ProductVariant/12345',  // tier ID (default variant GID)
  'gid://shopify/ProductVariant/67890'   // selected variant GID
);

Parameter	Type	Description
`tierId`	`string`	The variant GID of the gift's default variant, used as an identifier
`variantId`	`string`	The variant GID of the variant to select

The selection is persisted in localStorage and synced to the server. Returns a Promise.

ready()

Returns a Promise that resolves when all pending API calls (triggers, selections, etc.) are complete.

await Omake.ready();
// All API calls are done — safe to read state or proceed

isReady()

Synchronous version of ready(). Returns true if no API calls are in-flight, false otherwise.

if (Omake.isReady()) {
  // Safe to read state
}

addOmake()

Adds the gift bag product to the cart if it's not already present. Used in headless mode when auto-add is disabled.

await Omake.addOmake();

Returns a Promise.

Headless mode

For full control over the gift-with-purchase experience, you can disable Omake's built-in UI and manage everything through the API.

To enable headless mode, go to Settings > Advanced in the Omake admin and disable both:

Auto-add gift bag — you'll call addOmake() yourself
Show widget — you'll build your own UI using getState()

Example: headless flow

document.addEventListener('omake:ready', async function() {
  // 1. Trigger a custom promotion
  await Omake.trigger('vip_customer');

  // 2. Check state and build your UI
  const state = Omake.getState();
  state.tiers.forEach(function(tier) {
    if (tier.unlocked) {
      // Render unlocked tier UI
      tier.gifts.forEach(function(gift) {
        console.log('Gift unlocked:', gift.name);
      });
    }
  });

  // 3. Add the gift bag to the cart
  await Omake.addOmake();
});

In headless mode, Omake's Cart Transform still runs at checkout. You control the storefront experience — Omake handles the gift swap behind the scenes.

State storage

Omake persists state in two places to keep things in sync between the browser and the server.

localStorage (client-side):

Key	Format	Description
`_omake_t`	`{ t: string[], exp: number }`	Active triggers with a 14-day expiry timestamp
`_omake_g`	`{ [variantGid]: { variant: variantGid } }`	Gift variant selections

Cart metafield (server-side):

Both triggers and gift selections are also written to the cart metafield. This is what the Cart Transform reads at checkout to validate and apply gifts. The localStorage values and cart metafield are kept in sync automatically.

If a customer clears their browser storage, triggers and selections are re-synced from the cart metafield on the next page load.