Skip to main content

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.

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

Addons are offered based on merchant rules:
  • Item-specific eligibility
  • Business logic and thresholds
  • Product categories
  • Merchant configuration
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 }
    }
  ]
}
  • 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:
  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

​
Common Use Cases

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

​
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:
  1. Add Addon - Apply addon services
  2. Remove Addon - Remove selections
  3. Get Cart - View addon offers and selections