---
title: "Understanding custom extensions"
slug: "understanding-custom-embedded-blocks-1"
updated: 2026-09-09T05:08:53Z
published: 2026-09-09T05:08:53Z
canonical: "help.skio.com/understanding-custom-embedded-blocks-1"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.skio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding custom extensions

## Before you start

- **Developer required:** Custom extensions must be implemented by a developer. Skio support does not assist with writing or debugging custom code.
- **API access needed:** You can use any query or mutation currently available in [Skio's API](https://code.skio.com/). If you need an unsupported mutation, reach out and we'll explore adding it.
- **Customer context:** The Skio Customer Portal displays all subscriptions for the logged-in customer (`storefrontUser`). Make sure your custom code supports this structure.
- **Formerly custom embedded blocks:** This feature was previously called **custom embedded blocks** and only supported a single block. If you set one up before, it now appears in your extensions list.

> [!CAUTION]
> Each extension adds more code for the Customer Portal to load and run. Heavy scripts, large images, or excessive API calls can slow things down for your customers, so keep extensions as lightweight as possible.

## What are custom extensions?

A **custom extension** is a component you can add anywhere in your Customer Portal's layout, built from your own HTML, CSS, and JavaScript. This feature was previously called **custom embedded blocks** and only supported a single block; extensions let you create and save as many as you need, then place each one exactly where it fits in your layout.

With a custom extension, you can:

- Display personalized or dynamic content
- Run API queries or trigger mutations (e.g., swap a product, update shipping)
- Add branded functionality that fits your subscription strategy
- Build multiple blocks at once and control the order each one appears in

For example, you could:

- Show a message when a customer has multiple subscriptions and offer to merge them
- Add a custom button that lets subscribers swap a product *and* change their shipping frequency at the same time (e.g., "Buy more, ship less, save more!")
- Run a loyalty or rewards block above your Products section and a support-links block below it, each managed independently

Custom extensions are ideal for merchants looking to create deeper subscriber engagement and operational efficiency through tailored, modular portal experiences.

## How do I set up a custom extension?

> [!NOTE]
> Extensions live in your Customer Portal's **Layout** section, alongside built-in sections like Products and Summary.

1. In your **Skio Dashboard**, go to **Storefront > Customer Portal**, click the **Branding** tab, then scroll to **Layout**.
2. At the bottom of the Layout list, click **Add custom extension**, then click **Add extension** on the Custom extensions page.
3. Give the extension a **Name**, then use the **Code editor** to add your custom **HTML**, **CSS**, and **JavaScript**. Extensions run after the Customer Portal mounts.
4. Click **Save**, then click the **+** symbol to add it to your layout.
5. Click **Back to customization** and reorder the custom extension where you want it to appear. Extensions that not added to Layout are saved but stay hidden from customers.

In the top right corner of the portal editor, click **Publish** and test with a **test subscription** to confirm everything works as expected.

> [!WARNING]
> Some JavaScript may not render in Preview mode but will still work correctly on your live site (e.g., third-party app code).