# SubscriptionToggle

> Subscribe & Save toggle for PDP. Emits subscription:changed events for BuyBox.

Canonical URL: https://fa7e86e3d553:3005/islands/commerce/subscription-toggle

> Subscribe & Save toggle for PDP. Emits subscription:changed events for BuyBox. Place above or beside BuyBox. BuyBox with listenForEvents:true picks up the selling plan automatically.

## Preview

**Category**: Commerce

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| oneTimePrice | string | Yes | - | One-time purchase price (e.g., "$40") |
| plans | array | Yes | - | Array of subscription plan objects with id, frequency, discount, price |
| benefits | array | No | - | Array of benefit strings (e.g., ["Free shipping on every order", "Cancel anytime"]) |
| defaultMode | enum | No | "one-time" | Default selection: "one-time" or "subscribe" |
| label | string | No | - | Optional label above toggle (e.g., "Purchase Options") |

## Embed Example

```html
<lx-island name="SubscriptionToggle">
  <script type="application/json">
{
  "oneTimePrice": "example-oneTimePrice",
  "plans": [
    {
      "id": "example-id",
      "frequency": "example-frequency",
      "discount": "example-discount",
      "price": "example-price"
    }
  ]
}
  </script>
</lx-island>
```

## Usage Patterns

**Standard placement (above or beside BuyBox):**

```html
<lx-island name="SubscriptionToggle">
  <script type="application/json">
{
  "oneTimePrice": "example-oneTimePrice",
  "plans": [
    {
      "id": "example-id",
      "frequency": "example-frequency",
      "discount": "example-discount",
      "price": "example-price"
    }
  ]
}
  </script>
</lx-island>
```

**Single plan (most common):**

```html
<lx-island name="SubscriptionToggle">
  <script type="application/json">
{
  "oneTimePrice": "example-oneTimePrice",
  "plans": [
    {
      "id": "example-id",
      "frequency": "example-frequency",
      "discount": "example-discount",
      "price": "example-price"
    }
  ]
}
  </script>
</lx-island>
```

**Multiple plans (30/60/90 day options):**

```html
<lx-island name="SubscriptionToggle">
  <script type="application/json">
{
  "oneTimePrice": "example-oneTimePrice",
  "plans": [
    {
      "id": "example-id",
      "frequency": "example-frequency",
      "discount": "example-discount",
      "price": "example-price"
    }
  ]
}
  </script>
</lx-island>
```

## Events

| Event | Direction | Payload |
|-------|-----------|---------|
| subscription:changed | Emits | `{mode: 'one-time' or 'subscribe', planId?: string, frequency?: string, price: string, discount?: string}` when toggle switched |

## Tips

- Place directly above or beside [BuyBox](/islands/commerce/buy-box) for visibility
- Always set [BuyBox](/islands/commerce/buy-box) `listenForEvents:true` when using SubscriptionToggle
- `plans` array can have 1-3 options (30/60/90 day frequencies are common for consumables)
- Each plan needs a Shopify SellingPlan `id` (e.g., `"gid://shopify/SellingPlan/123"`)
- `defaultMode:"subscribe"` pre-selects subscription (higher LTV, lower churn)
- `defaultMode:"one-time"` pre-selects one-time (better for trial customers or high-ticket items)
- Include `benefits` array for trust (e.g., "Free shipping", "Cancel anytime", "Skip or pause")
- Shows discount badge ("Save 15%") automatically based on `discount` field
- Best for consumables (supplements, skincare, pet food, coffee) — not for one-time purchases
- Subscription discounts stack with volume discounts (use with [QuantityBreaks](/islands/commerce/quantity-breaks) for max AOV)

## Stylable Parts

Target internal elements via `data-part` selectors in section CSS:

| Part | Description |
|------|-------------|
| `root` | Outermost container |

```css
/* Example: custom styling */
[data-section-id='SECTION'] [data-part='root'] {
  border-radius: 1rem;
  box-shadow: 0 4px 12px rgba(0,0,0,0.08);
}
```

## Related Islands

- [BuyBox](/islands/commerce/buy-box) — Listens to `subscription:changed`; set `listenForEvents:true`
- [QuantityBreaks](/islands/commerce/quantity-breaks) — Can combine subscription discount + volume discount for max savings