Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. Addon Management

Addon Management

The Addon Management API selects or removes merchant-defined add-on (addon) services on a cart (warranties, protection plans, gift wrap, installation services, etc.). The set of available offers, their pricing, and any constraints come from the merchant — Firmly exposes them on cart.addons.offers and applies the buyer’s choices to cart.addons.selections.

​​ Available Endpoints

Method Path Description
POST /api/v2/domains/{domain}/cart/addons Set the desired addon selections (add / replace).
POST /api/v2/domains/{domain}/cart/addons/_remove Remove a specific addon (whole, per-item, or per-child).
Add Addons Set the desired addon selections on the cart. Remove Addon Remove a specific addon (whole, per-item, or per-child).

​​ Cart Addons Shape

cart.addons is an object with two arrays:

  • offers — what the merchant is offering for this cart.
  • selections — what the buyer has currently selected.

​​ Offer fields

Field Type Description
addon_id string Stable id used to select / remove the offer.
platform_addon_id string (optional) Merchant-side identifier.
display { name, description?, long_description?, image_url?, links? } Render-ready content.
scope ITEM | GROUP | CART | INHERIT Where the addon applies.
coverage_mode PER_ITEM | PREDEFINED_GROUP | FREE_GROUPING How a selection maps onto line items.
price Amount Headline price. Always present; hide_price: true only suppresses display — the value is still returned.
hide_price boolean (optional) Suppress price in the UI.
eligible_line_item_ids string[] (optional) Line items the offer can attach to.
line_item_pricing object keyed by line_item_id (optional) Per-item override of price / hide_price.
constraints { exclusive_group_id?, requires_addon_ids? } (optional) Selection rules.
child_offers array of nested offers (optional) For tiered or hierarchical addons.

​​ Selection fields

Field Type Description
addon_id string The offer’s addon_id.
selected_line_item_ids string[] (optional) Items the selection applies to (for PER_ITEM and FREE_GROUPING modes).
selected_child_ids string[] (optional) Chosen child offer ids when the offer has child_offers.
hide_price boolean (optional) Mirror of the offer flag.
price Amount (optional) Calculated server-side.
line_item_pricing object keyed by line_item_id (optional) Per-item calculated price.
metadata object (optional) Arbitrary merchant-specific metadata returned with the selection.

​​ Constraint Semantics

The constraints block on an offer has only two fields, both optional:

  • exclusive_group_id — when multiple offers share the same exclusive_group_id, selecting one of them deselects the others (e.g. mutually exclusive warranty tiers).
  • requires_addon_ids — selecting this offer requires the listed addon_ids to also be selected (e.g. an extended warranty that requires the base warranty).

​​ Pricing Notes

  • price on a CART-scope offer is the headline cart-wide price.
  • price on an ITEM / GROUP-scope offer is the per-attached-entity price; per-item overrides appear in line_item_pricing keyed by line_item_id.
  • cart.addon_total carries the sum of selected-addon prices and feeds into cart.total.

​​ Example: cart.addons Snippet 


{
  "offers": [
    {
      "addon_id": "shipping_protection",
      "display": { "name": "Shipping Protection", "description": "Protect your entire order" },
      "scope": "CART",
      "coverage_mode": "PREDEFINED_GROUP",
      "price": { "currency": "USD", "value": 4.99, "number": 499, "symbol": "$" }
    },
    {
      "addon_id": "extended_warranty",
      "display": { "name": "3-Year Extended Warranty" },
      "scope": "ITEM",
      "coverage_mode": "PER_ITEM",
      "eligible_line_item_ids": ["761ff52b-8e6d-d373-fdf2-91a1a70df20c", "38d3f385-ea8d-8bb2-dcfc-759ac85af6ef"],
      "price": { "currency": "USD", "value": 89.99, "number": 8999, "symbol": "$" },
      "line_item_pricing": {
        "761ff52b-8e6d-d373-fdf2-91a1a70df20c": { "price": { "currency": "USD", "value": 89.99, "number": 8999, "symbol": "$" } },
        "38d3f385-ea8d-8bb2-dcfc-759ac85af6ef": { "price": { "currency": "USD", "value": 29.99, "number": 2999, "symbol": "$" } }
      },
      "child_offers": [
        {
          "addon_id": "EW-2YR",
          "display": { "name": "2 Year" },
          "scope": "INHERIT",
          "coverage_mode": "PER_ITEM",
          "price": { "currency": "USD", "value": 49.99, "number": 4999, "symbol": "$" }
        },
        {
          "addon_id": "33fd7d89-635d-5466-1a50-01519c4488a3",
          "display": { "name": "3 Year" },
          "scope": "INHERIT",
          "coverage_mode": "PER_ITEM",
          "price": { "currency": "USD", "value": 89.99, "number": 8999, "symbol": "$" }
        }
      ]
    }
  ],
  "selections": []

}