Module: Core-03

Theme integration

SaveLayer ships a theme app extension that loads the storefront SDK on your shop. Use it for wishlist-style flows without building your own proxy client: the SDK talks to SaveLayer through Shopify’s signed app proxy. Customer-scoped data lives in app-owned metaobjects; read and write it through the API, not by listing every metaobject in Liquid.

01 / APP EMBED

Theme app extension

SaveLayer Onsite Script

In the theme editor, open App embeds and enable SaveLayer Onsite Script. That injects assets/savelayer.js and sets window.SaveLayer, which calls your app proxy under a configurable base path (default /apps/savelayer/api). Ensure that path matches the app proxy subpath configured for SaveLayer in Shopify Partners (i.e. /apps/<subpath>/api). Metaobject types $app:save_list and $app:save_item hold canonical data; the theme does not need to map them manually in the customizer for basic save flows.

Enable the embed
Turn on the SaveLayer app embed so the script runs on every storefront page where the theme loads app embeds.
Match the API base
The default <code class="hl-dt-ref-inline-code">/apps/savelayer/api</code> matches production. Only change “SaveLayer API base” if the app is installed under a different proxy subpath (e.g. staging as <code class="hl-dt-ref-inline-code">/apps/savelayer-1/api</code>).
Logged-in customers
Save, remove, toggle, and list require a logged-in customer; the proxy returns AUTH_REQUIRED (401) otherwise. Use is-saved and list to drive UI state.

App embed

SaveLayer Onsite Script

02 / LIQUID & SCRIPTS

Custom theme code

sections or snippets / your-template.liquid

{% comment %}
  Requires the SaveLayer app embed. Uses window.SaveLayer (same endpoints as
{% endcomment %}

<button type="button" class="sl-example-save"
  data-context="wishlist"
  data-entity-type="product"
  data-entity-gid="gid://shopify/Product/{{ product.id }}"
>Save</button>

<script>
  document.querySelector('.sl-example-save')?.addEventListener('click', async function () {
    if (!window.SaveLayer) return;
    const el = this;
    await window.SaveLayer.save({
      context: el.dataset.context,
      entityType: el.dataset.entityType,
      entityGid: el.dataset.entityGid,
      source: 'theme-custom',
    });
  });
</script>

03 / EVENTS & OTHER CHANNELS

Analytics and headless

Storefront SDK methods

The embed exposes save, remove, toggle, list, and isSaved (see API reference ). Requests use fetch to the configured API base; Shopify signs app proxy requests from the storefront. Batch is not exposed on this lightweight SDK yet—call POST /batch via your own client if your plan allows it. Headless and Customer Account stores use the direct API and JWT exchange instead—see Authorization .

await window.SaveLayer.toggle({ context: 'wishlist', entityType: 'product', entityGid: 'gid://shopify/Product/123', source: 'theme', });

Customer Events

After successful saves, removes, toggles, and list views, the SDK publishes Shopify Customer Events you can consume in web pixels (savelayer:item_saved, savelayer:item_removed, savelayer:item_toggled, savelayer:list_viewed). Subscribe with window.SaveLayer.on(event, handler) in theme code, or use Shopify.analytics.publish from subscribed pixels.

window.SaveLayer.on('savelayer:item_saved', (payload) => { // entityGid, entityType, context, listHandle });

How it fits together

Online Store → signed app proxy → SaveLayer

Shopify storefront

App proxy API

window.SaveLayer