> For the complete documentation index, see [llms.txt](https://subscriptions-docs.tech-arms.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://subscriptions-docs.tech-arms.io/features/customization.md).

# Widgets

Show one-time and subscription purchase options on your product pages, add the widget to your theme, and manage which widget each product uses.

The **subscription widget** is the purchase box on your product pages. Customers use it to choose **One-time purchase** or a subscription plan before they add the product to the cart. It also shows the subscription price, the savings badge, and extra details about the subscription.

The widget appears only on products that have a selling plan created in this app. To create one, see [Create a selling plan](https://subscriptions-docs.tech-arms.io/features/subscription/how-to-create-a-subscription-plan.md).

You can create up to **10 widgets** and give each one its own design and its own products. Three kinds of templates are available:

| Template              | What it looks like                                                                                                                                                                      |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default templates** | A clean dropdown for customers to pick a subscription plan in a simple layout.                                                                                                          |
| **Grid templates**    | A grid that compares plans side by side and highlights the savings.                                                                                                                     |
| **Special templates** | Premium designs with their own styles and colors. See [Create your Special Templates](https://subscriptions-docs.tech-arms.io/features/customization/create-your-special-templates.md). |

![The Widgets page with the widget list, the Status column, and the Create Widget button](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2FXKoKxS1NYeJYCAyeRkJC%2Fwidgets-list.png?alt=media)

## Add the widget to your theme

The widget needs the app embed to be turned on in your theme. Adding an app block is optional.

| Theme element                      | Required | What it does                                                                                                                      |
| ---------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
| App embed **TA Subscriptions App** | Yes      | Loads the widget and all subscription features on your store. Without it, no widget appears.                                      |
| App block **Subscriptions Widget** | No       | Places the widget exactly where you want it in the product section. Without it, the widget appears right below the product price. |
| App block **Discount Price**       | No       | Places the subscription price block where you want it. Without it, the widget adds the price block itself.                        |

{% stepper %}
{% step %}

### Turn on the app embed

Open the app home page. In the **App Embed** card, click **Configure**. The theme editor opens with the app embed selected. Turn on **TA Subscriptions App**, then click **Save** in the theme editor.

Back in the app, the **App Embed** card shows **Active**.

![The App Embed and App Blocks cards on the app home page](https://3752025337-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F479XnzvtVA5dDE3Rt2Uh%2Fuploads%2F7t92WBr9MtY2JQrFURR2%2Fwidgets-app-embed-card.png?alt=media)
{% endstep %}

{% step %}

### Add the app block (optional)

On the app home page, in the **App Blocks** card, click **More info**. Next to **Subscriptions Widget**, click **Add**. The theme editor opens on your product template with the block added. Drag the block to the position you want inside the product section, then click **Save**.

You can add **Price Element** the same way to place the subscription price.

{% hint style="warning" %}
Keep the **Subscriptions Widget** block inside the product information section. A block placed outside the product form shows an empty widget and doesn't add the subscription to the cart.
{% endhint %}
{% endstep %}

{% step %}

### Check your product page

Open a product that has a selling plan on your storefront. You should see **One-time purchase** and your subscription options.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
The **Title** and **One time purchase** settings of the **Subscriptions Widget** block in the theme editor don't change the widget. Change the widget text in the app's widget editor instead. See [Create Your Own Widget](https://subscriptions-docs.tech-arms.io/features/customization/how-to-customize-the-subscription-widget.md).
{% endhint %}

The **Subscriptions Widget** block can also be added to your home page and to custom pages. On those pages, pick the product to show in the block's **product** setting.

The other app blocks, **Box Button** and **Portal link**, are explained in [Build-A-Box](https://subscriptions-docs.tech-arms.io/features/build-a-box.md) and [Customer Portal](https://subscriptions-docs.tech-arms.io/features/customer-portal.md).

## The widget list

In the app menu, click **Widgets**. Each row is one widget. Special widgets are listed at the end under **Special widgets**.

| Column            | What it shows                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------ |
| **ID**            | The widget's number.                                                                             |
| **Name**          | The name you gave the widget. Only you see it.                                                   |
| **Template type** | The template the widget is built on, for example **Default** or **Grid**.                        |
| **Priority**      | A number from 0 to 100. When several widgets apply to the same product, the highest number wins. |
| **Status**        | Two badges. See the table below.                                                                 |
| **Date created**  | When the widget was created.                                                                     |
| **Action**        | **Edit**, and **More actions** with **Duplicate** and **Delete**.                                |

### Status badges

| Badge           | Meaning                                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Active**      | The widget is turned on.                                                                                                         |
| **Deactive**    | The widget is turned off. Once you publish it in this state, it is removed from your storefront.                                 |
| **Published**   | Your storefront shows the latest saved version.                                                                                  |
| **Unpublished** | The widget has saved changes that are not on your storefront yet, or it has never been published. Open it and click **Publish**. |

A widget shows on your storefront only when it is **Active** and has been published.

## Which widget a product shows

Each widget has an **Apply to resources** setting: **All**, **Specific products**, **Specific collections**, or **Specific tags**. For each product, the app picks the widget this way:

1. It takes the published, active widgets that apply to the product.
2. If more than one applies, it uses the widget with the highest **Priority**.
3. If none applies, the product shows the app's built-in default widget. This built-in widget doesn't include any text or style changes you made in the editor.

For example: widget A applies to **All** products with priority 0, and widget B applies to your "Coffee" collection with priority 10. Products in "Coffee" show widget B. All other products show widget A.

{% hint style="info" %}
To use one design for most products and another for a few, give the general widget **All** with a low priority, and give the specific widget a higher priority.
{% endhint %}

## Manage widgets

From the widget list, use **More actions** on a row:

* **Duplicate**: makes a copy named " copy". The copy starts **Deactive** and **Unpublished**, so it doesn't change your storefront until you activate and publish it.
* **Delete**: removes the widget from the app and from your storefront right away. This can't be undone.

To edit, activate, or deactivate a widget, click its row to open the editor. See [Create Your Own Widget](https://subscriptions-docs.tech-arms.io/features/customization/how-to-customize-the-subscription-widget.md).

## Good to know

* You can have up to 10 widgets. Delete one you don't use to create a new one.
* The widget shows only selling plans created in this app. Plans from other subscription apps and Build-A-Box plans don't appear in it.
* After you publish, changes can take 1 to 3 minutes to appear on your storefront.
* If the widget doesn't appear on one product, check that the product has an active selling plan from this app, and that the app embed is on in your **published** theme.
* To translate the widget text, see [Multilingual widget](https://subscriptions-docs.tech-arms.io/features/translation/multilingual-widget.md).

*If you need help, feel free to reach out to us via in-app* [***Live chat***](https://go.crisp.chat/chat/embed/?website_id=c4ae10a3-f762-4968-b35a-c931caf62a96)***,*** [***Book a call***](https://calendly.com/ta-subscription-app-support/30min) *or at* [***support@tech-arms.io***](mailto:support@tech-arms.io)***.***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://subscriptions-docs.tech-arms.io/features/customization.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
