---
title: "Understanding custom embedded blocks"
slug: "understanding-custom-embedded-blocks-1"
updated: 2026-02-27T16:42:50Z
published: 2026-02-27T16:42:50Z
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 embedded blocks

## Before you start

- **Developer required:** Custom embedded blocks 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.
- **Check your Customer Portal version**: For guidance in creating a custom embedded block in Customer Portal v2, [see our CPv2 guide here](/help/docs/customer-portal-v2-settings#h_01K8KKNE2EMZWJF1AW01G0C5D9). For Customer Portal v3, [see our CPv3 guide here instead](/help/docs/customizing-customer-portal-branding).

## What is a custom embedded block?

A **custom embedded block** is a component that appears at the top of the Skio Customer Portal. It lets you enhance the default portal experience with dynamic, interactive features powered by [Skio’s API](https://code.skio.com/).

With a custom block, 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

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!")

These blocks are ideal for merchants looking to create deeper subscriber engagement and operational efficiency through tailored portal experiences.

## How does the custom embedded block feature work?

The **Custom block** input in your customer portal settings lets you add developer-built content directly to the top of the Customer Portal.

- The block functions like a standard web page. Enter your custom **HTML** and **JavaScript** directly into the input field.
- To add styling, include a `<style>` tag in your HTML to define custom **CSS**.
- A live preview appears next to the input so you can see exactly how the block will look to subscribers.

Click **Save**and test with a **test subscription** to confirm everything works as expected.