Overview

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

Cart-Level Addons

Apply to entire order

Order-wide services
Shipping protection
General fees or services

Item-Level Addons

Apply to specific items

Extended warranties
Protection plans
Item-specific services

Group-Level Addons

Apply to item groups

Services for multiple related items
Group-specific options

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 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

Merchant-Defined Eligibility

Addons are offered based on merchant rules:

Item-specific eligibility
Business logic and thresholds
Product categories
Merchant configuration

Hierarchical Addons

Some addons can have child options:

{
  "addon_id": "installation_service",
  "child_offers": [
    {
      "addon_id": "white_glove_service",
      "price": { "value": 75.00 }
    },
    {
      "addon_id": "assembly_included",
      "price": { "value": 50.00 }
    }
  ]
}

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

API Endpoints

Add Addon

Apply addon services with flexible scoping options

Remove Addon

Remove previously selected addons from the cart

Implementation Guide

Example: Multi-Tier Addon Selection

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

{
  "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

When displaying addons in your UI:

Group addons by scope for clarity
Show pricing clearly (per-order vs per-item)
Indicate required vs optional addons
Display savings or value propositions
Handle hierarchical selections intuitively

Common Use Cases

E-commerce Protection
Protection Plans
Gift Options

{
  "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
  }
}

{
  "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 }
    }
  ]
}

{
  "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
      }
    }
  }
}

Best Practices

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

Next Steps

Ready to implement addons? Start with these endpoints:

Add Addon - Apply addon services
Remove Addon - Remove selections
Get Cart - View addon offers and selections

Home

Core Concepts

Implementation Guides

Ask Agent SDK

API Reference

firmly Connect

Resources

Addon System Overview

Cart-Level Addons

Item-Level Addons

Group-Level Addons

How Addons Work

1. Addon Offers

2. Addon Selection

3. Pricing & Application

Key Features

API Endpoints

Add Addon

Remove Addon

Implementation Guide

Example: Multi-Tier Addon Selection

Frontend Integration Tips

Common Use Cases

Best Practices

Next Steps

​Addon System Overview

Cart-Level Addons

Item-Level Addons

Group-Level Addons

​How Addons Work

​1. Addon Offers

​2. Addon Selection

​3. Pricing & Application

​Key Features

​API Endpoints

Add Addon

Remove Addon

​Implementation Guide

​Example: Multi-Tier Addon Selection

​Frontend Integration Tips

​Common Use Cases

​Best Practices

​Next Steps

Addon System Overview

How Addons Work

1. Addon Offers

2. Addon Selection

3. Pricing & Application

Key Features

API Endpoints

Implementation Guide

Example: Multi-Tier Addon Selection

Frontend Integration Tips

Common Use Cases

Best Practices

Next Steps