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

# Overview

> Flexible addon system for value-added services

The Addon Management API enables merchants to offer value-added services like warranties, protection plans, and special services. Addons are defined by the merchant system and can apply to different scopes within the cart.

## Addon System Overview

<CardGroup cols={3}>
  <Card title="Cart-Level Addons" icon="shopping-cart">
    **Apply to entire order**

    * Order-wide services
    * Shipping protection
    * General fees or services
  </Card>

  <Card title="Item-Level Addons" icon="box">
    **Apply to specific items**

    * Extended warranties
    * Protection plans
    * Item-specific services
  </Card>

  <Card title="Group-Level Addons" icon="folder">
    **Apply to item groups**

    * Services for multiple related items
    * Group-specific options
  </Card>
</CardGroup>

## How Addons Work

### 1. Addon Offers

When you retrieve a cart, the merchant system returns available addons based on:

* Cart contents and business rules
* Item eligibility
* Merchant configuration

### 2. Addon Selection

Customers can select addons using the [Add Addon](/api-reference/addon-management/add-addon) endpoint:

* Specify the addon ID and line item IDs
* Select child addons if applicable
* System updates the cart with selections

### 3. Pricing & Application

* **Cart-level**: Single price for the entire order
* **Item-level**: Price per item or group of items
* **Group-level**: Price for a predefined group

## Key Features

<AccordionGroup>
  <Accordion title="Merchant-Defined Eligibility">
    Addons are offered based on merchant rules:

    * Item-specific eligibility
    * Business logic and thresholds
    * Product categories
    * Merchant configuration
  </Accordion>

  <Accordion title="Hierarchical Addons">
    Some addons can have child options:

    ```json theme={null}
    {
      "addon_id": "installation_service",
      "child_offers": [
        {
          "addon_id": "white_glove_service",
          "price": { "value": 75.00 }
        },
        {
          "addon_id": "assembly_included",
          "price": { "value": 50.00 }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Constraints & Rules">
    * **Required addons**: Must be selected before checkout
    * **Single selection**: Only one addon from a group
    * **Multiple selection**: Allow multiple addons
    * **Quantity limits**: Min/max quantities per addon
  </Accordion>
</AccordionGroup>

## API Endpoints

<CardGroup cols={2}>
  <Card title="Add Addon" href="/api-reference/addon-management/add-addon">
    Apply addon services with flexible scoping options
  </Card>

  <Card title="Remove Addon" href="/api-reference/addon-management/remove-addon">
    Remove previously selected addons from the cart
  </Card>
</CardGroup>

## Implementation Guide

### Example: Multi-Tier Addon Selection

Here's how addons appear in a typical cart response:

```json theme={null}
{
  "addons": {
    "offers": [
      {
        "addon_id": "shipping_protection",
        "display": {
          "name": "Shipping Protection",
          "description": "Protect your entire order"
        },
        "scope": "CART",
        "price": { "value": 4.99 }
      },
      {
        "addon_id": "remove-mattress123",
        "display": {
          "name": "Remove Mattress",
          "description": "Remove old mattress"
        },
        "scope": "GROUP",
        "coverage_mode": "PREDEFINED_GROUP",
        "eligible_line_item_ids": ["item-1", "item-2"],
        "price": { "value": 0 }
      },
      {
        "addon_id": "extended_warranty",
        "display": {
          "name": "3-Year Extended Warranty",
          "description": "Comprehensive protection"
        },
        "scope": "ITEM",
        "eligible_line_item_ids": ["item-1", "item-2"],
        "line_item_pricing": {
          "item-1": { "price": { "value": 89.99 } },
          "item-2": { "price": { "value": 29.99 } }
        }
      }
    ],
    "selections": []
  }
}
```

### Frontend Integration Tips

<Note>
  When displaying addons in your UI:

  1. Group addons by scope for clarity
  2. Show pricing clearly (per-order vs per-item)
  3. Indicate required vs optional addons
  4. Display savings or value propositions
  5. Handle hierarchical selections intuitively
</Note>

## Common Use Cases

<Tabs>
  <Tab title="E-commerce Protection">
    ```json theme={null}
    {
      "addon_id": "order_protection",
      "scope": "CART",
      "display": {
        "name": "Order Protection",
        "description": "Coverage for damage, loss, or theft"
      },
      "price": { "value": 12.99 },
      "constraints": {
        "min_subtotal": 50.00,
        "max_subtotal": 2000.00
      }
    }
    ```
  </Tab>

  <Tab title="Protection Plans">
    ```json theme={null}
    {
      "addon_id": "protection-sofa-001",
      "scope": "ITEM",
      "display": {
        "name": "Furniture Protection Plan",
        "description": "Comprehensive protection coverage"
      },
      "eligible_line_item_ids": ["item-1"],
      "child_offers": [
        {
          "addon_id": "FPP-2YR",
          "display": { "name": "2 Year Protection" },
          "price": { "value": 79.99 }
        },
        {
          "addon_id": "FPP-3YR",
          "display": { "name": "3 Year Protection" },
          "price": { "value": 99.99 }
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Gift Options">
    ```json theme={null}
    {
      "addon_id": "gift_wrap",
      "scope": "ITEM",
      "display": {
        "name": "Gift Wrapping",
        "description": "Beautiful gift presentation"
      },
      "price": { "value": 5.99 },
      "metadata_schema": {
        "properties": {
          "message": {
            "type": "string",
            "maxLength": 200
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Best Practices

<Warning>
  **Important Considerations:**

  * Always validate addon eligibility before selection
  * Handle addon pricing in cart totals correctly
  * Clear selections when items are removed
  * Respect single vs multiple selection constraints
  * Show addon impact on delivery times if applicable
</Warning>

## Next Steps

Ready to implement addons? Start with these endpoints:

1. [Add Addon](/api-reference/addon-management/add-addon) - Apply addon services
2. [Remove Addon](/api-reference/addon-management/remove-addon) - Remove selections
3. [Get Cart](/api-reference/cart-management/get-cart) - View addon offers and selections