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

# How to create an add-on listing

> A listing sold alongside another — insurance, delivery, fees, consumables — including percentage-of-parent pricing and attaching it to the listings that offer it.

<Card title="Open in TWICE Admin" icon="external-link" href="https://admin.twicecommerce.com/catalog/listings" horizontal>
  catalog/listings
</Card>

An add-on listing is one bought alongside something else rather than on its own. Insurance, delivery, a cleaning fee, a tube of sealant at the counter, or anything else that can meaningfully complement the main product.

It is an ordinary listing with two extra decisions: whether it can be found by itself, and whether its price is its own or a share of whatever it is attached to. Both live on the **Add-on** tab.

This guide is the add-on-specific path. The tab-by-tab walkthrough common to every listing is [create and publish a listing](/docs/guides/catalog/create-and-publish-a-listing).

## Prerequisites

<Warning>
  **Required permissions:** listing create and manage rights. All four system roles hold them.
</Warning>

<Info>
  **Decide two things before you start.**

  * **Is it worth buying alone?** A tube of sealant is. A damage waiver is not. That decides *Only available as add-on*.
  * **Does its price depend on what it is attached to?** Delivery costs the same whatever is in the van. Insurance scales with the value being covered. That decides the pricing mode, and it is not changeable without re-pricing.
</Info>

## The Walkthrough

<Steps>
  <Step title="Create it as an ordinary listing">
    An add-on is a listing. Give it a name, a purchase option and a price like any other — **Sales** for a fee or a consumable, **Bookings** if it is genuinely taken for a period.

    Name it as the customer will read it in a checkout list, next to the thing it attaches to. *Damage waiver* rather than *Insurance product 2*.
  </Step>

  <Step title="Leave the stock rules empty if nothing physical backs it">
    On the **Fulfilment** tab, the **Stock items** card decides what is reserved or deducted when this listing is bought. For anything with no unit behind it — delivery, insurance, a service fee — **add no rule at all**. The card reads *No stock items reserved or deducted when the listing is purchased*, and the listing stays sellable regardless of stock.

    There is no switch for this. An empty rule list *is* the setting.

    **Add a rule for a consumable.** Sealant, wax and spare tubes are real things you can run out of, and they need a rule like any sales listing.
  </Step>

  <Step title="Hide it from browsing, if it makes no sense alone">
    On the **Add-on** tab, **Visibility** → **Sales visibility** → **Only available as add-on**: *when enabled, this listing is hidden from storefront browsing and only appears as an add-on on other listings.*

    Turn it on for a waiver or a cleaning fee. Leave it off for something a customer might reasonably come looking for on its own — a consumable often belongs in both places.

    This hides the listing without unpublishing it, which matters: an unpublished listing cannot be offered as an add-on either.
  </Step>

  <Step title="Choose how it is priced when attached">
    Still on the **Add-on** tab, **Pricing when sold as add-on** → **When sold as add-on** offers two modes:

    * **Use this listing's own price tables** — a flat price, whatever it is attached to. Right for delivery, a fixed service fee, a consumable.
    * **Percentage of parent listing price** — a whole number from 1 to 200, *applied to parent listing's subtotal*. Right for insurance and damage waivers, which should scale with what is being covered.

    A damage waiver at 10 % of the order is the percentage mode. That is how the insurance product is built — there is no separate insurance feature to look for.

    Percentage-priced add-ons are always sold as a purchase, never as a booking.
  </Step>

  <Step title="Attach it to the listings that offer it">
    Attachment happens from the **parent** listing, not from the add-on. On the parent's **Recommendations** tab, under **Add-ons** — *items offered as add-ons on this listing* — use **Add add-on**.

    Each attachment carries its own settings, so the same add-on behaves differently on different parents:

    * **Quantity mode** — **Selectable** lets the customer choose how many; **Fixed** does not.
    * **Default quantity** — what it starts at.
    * **Offer as** — **Book** or **Buy**.
    * **Required** — *customers cannot uncheck this add-on.*

    **Required** is how a mandatory cleaning fee or compulsory helmet works. Use it sparingly: a required add-on is a price increase the customer cannot decline, and it is better shown as such than buried.
  </Step>

  <Step title="Repeat the attachment wherever it applies">
    An add-on attached to one listing is offered on that listing only. There is no catalog-wide add-on.

    For something that should appear on everything — a waiver, a delivery option — that means attaching it to each parent. Worth knowing before you build a set of thirty listings and then decide they all need insurance.
  </Step>
</Steps>

## How do I know it worked?

* **The add-on does not appear in storefront browsing** when *Only available as add-on* is on. Looking for it in the catalog and not finding it is the setting working.
* **It appears on the parent listing's page**, in the add-ons the customer can pick.
* **A percentage-priced add-on changes with the parent.** Price the parent for two days and then for a week — the waiver should move. If it does not, it is on the flat mode.
* **A required add-on cannot be unticked**, and shows in the total from the start.

## Troubleshooting / Common Pitfalls

<AccordionGroup>
  <Accordion title="The add-on shows up as its own listing in the storefront">
    **Cause:** **Only available as add-on** is off.

    **What to do:** turn it on from the add-on listing's **Add-on** tab. Do not unpublish the listing instead — an unpublished listing cannot be offered as an add-on either.
  </Accordion>

  <Accordion title="The insurance price does not scale with the order">
    **Cause:** the add-on is on **Use this listing's own price tables**, which is a flat price whatever it is attached to.

    **What to do:** switch to **Percentage of parent listing price** and set the percentage. It applies to the parent's subtotal, so it moves with duration and quantity automatically.
  </Accordion>

  <Accordion title="The add-on is configured but never appears at checkout">
    **Cause:** it is not attached to the parent. Configuring the Add-on tab makes a listing *able* to be an add-on; it does not attach it to anything.

    **What to do:** open the parent listing's **Recommendations** tab and add it there.
  </Accordion>

  <Accordion title="A service add-on stopped being sellable">
    **Cause:** it has a stock rule that matches nothing. A service has no stock items, so any rule at all filters everything out and leaves availability at zero.

    **What to do:** delete the rule. An empty **Stock items** card is what "nothing physical backs this" looks like — there is no separate switch to turn off.
  </Accordion>

  <Accordion title="We attached it everywhere and now want to change the price">
    **Change it once, on the add-on listing.** The price lives on the add-on, not on each attachment — what each attachment carries is quantity, offer mode and whether it is required.

    **What to do:** edit the add-on's own price or percentage. Every parent picks up the change.
  </Accordion>

  <Accordion title="Customers are being charged for an add-on they did not choose">
    **Cause:** the attachment is marked **Required**, or pre-selected with a default quantity.

    **What to do:** decide deliberately. A required add-on is legitimate for a genuine mandatory fee, and a support ticket when it is a surprise.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create a rental listing" icon="calendar-days" href="/docs/guides/catalog/create-a-rental-listing">
    The parent this might attach to, when it comes back.
  </Card>

  <Card title="Create a sales listing" icon="cart-shopping" href="/docs/guides/catalog/create-a-sales-listing">
    The parent this might attach to, when it does not.
  </Card>

  <Card title="Add-ons" icon="puzzle-piece" href="/docs/catalog/listings/addons">
    The Add-on tab reference, field by field.
  </Card>

  <Card title="Recommendations" icon="thumbs-up" href="/docs/catalog/listings/recommendations">
    Where attachments and related listings are managed.
  </Card>
</CardGroup>