Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Resources
  3. Schemas
  4. Addon schemas

Addon schemas

Addons are merchant-offered add-ons attached to a cart or line item — warranties, gift wrap, gift messages, protection plans. The AddonsContainer lives on the cart; AddonOffer describes what’s available; AddonSelection records the user’s choices.

​​ AddonsContainer

Container for addon offers and customer selections.

  • offers (array, required) — Available addon services for the cart. Each is an AddonOffer.

  • selections (array, required) — Customer’s selected addons. Each is an AddonSelection.

​​ AddonOffer

Available addon service that can be selected.

  • addon_id (string, required) — Unique addon identifier.

  • display (AddonDisplay, required) — Display information for the addon. See AddonDisplay.

  • scope (string, required) — Where the addon applies. Enum values:

    • ITEM — Applies to specific items
    • GROUP — Applies to item groups
    • CART — Applies to the entire order
    • INHERIT — Inherits scope from the parent offer (used by child offers)

  • coverage_mode (string, required) — How items are covered by the addon. Enum values:

    • PER_ITEM — Price per individual item
    • PREDEFINED_GROUP — Fixed groups
    • FREE_GROUPING — Customer chooses grouping

  • price (Amount, required) — Base price for the addon.

  • platform_addon_id (string) — Identifier for the addon in the merchant’s underlying commerce platform.

  • hide_price (boolean) — When true, the price is not shown to the buyer.

  • eligible_line_item_ids (array) — Line item IDs eligible for this addon.

  • line_item_pricing (object) — Per-item pricing overrides, keyed by line_item_id.

    properties
    • [line_item_id] (object) — An object with price (Amount) and optional hide_price (boolean) for that line item.

  • constraints (AddonConstraints) — Rules and limitations. See AddonConstraints.

  • child_offers (array) — Hierarchical sub-options. Each child offer has the same shape as an AddonOffer (without further nesting): addon_id, display, scope, coverage_mode, price, and the optional platform_addon_id, hide_price, eligible_line_item_ids, line_item_pricing, and constraints.


{
  "addon_id": "shipping_protection",
  "display": {
    "name": "Shipping Protection",
    "description": "Covers lost or damaged shipments",
    "image_url": "https://staging.luma.gift/addons/protection.png"
  },
  "scope": "CART",
  "coverage_mode": "PREDEFINED_GROUP",
  "price": {
    "value": 4.99,
    "currency": "USD"
  }

}


{
  "addon_id": "extended_warranty",
  "display": {
    "name": "Extended Warranty",
    "description": "2-year extended warranty"
  },
  "scope": "ITEM",
  "coverage_mode": "PER_ITEM",
  "eligible_line_item_ids": [
    "8f3a2b1c-1d2e-4a5b-9c8d-1a2b3c4d5e6f",
    "b2c3d4e5-6f70-4a1b-8c9d-0e1f2a3b4c5d"
  ],
  "price": {
    "value": 29.99,
    "currency": "USD"
  },
  "line_item_pricing": {
    "8f3a2b1c-1d2e-4a5b-9c8d-1a2b3c4d5e6f": {
      "price": {
        "value": 29.99,
        "currency": "USD"
      }
    },
    "b2c3d4e5-6f70-4a1b-8c9d-0e1f2a3b4c5d": {
      "price": {
        "value": 19.99,
        "currency": "USD"
      }
    }
  }

}

​​ AddonDisplay

Display information for an addon offer.

  • name (string, required) — Addon display name.

  • description (string) — Short description.

  • long_description (string) — Extended description.

  • image_url (string) — Image URL (absolute http(s) URL).

  • links (array) — Related links (for example, terms or coverage details).

​​ AddonConstraints

Rules that govern how an addon can be combined with others.

  • exclusive_group_id (string) — Addons sharing the same exclusive group ID are mutually exclusive — only one can be selected.

  • requires_addon_ids (array) — Addon IDs that must also be selected for this addon to be valid.

​​ AddonSelection

Customer’s selected addon configuration.

  • addon_id (string, required) — References AddonOffer.addon_id.

  • selected_line_item_ids (array) — Line item IDs this addon applies to (for ITEM scope).

  • selected_child_ids (array) — Selected child addon IDs.

  • hide_price (boolean) — When true, the price is not shown to the buyer.

  • price (Amount) — Total price for this selection (calculated server-side).

  • line_item_pricing (object) — Per-item price breakdown, keyed by line_item_id.

  • metadata (object) — Addon-specific attributes.


{
  "addon_id": "extended_warranty",
  "selected_line_item_ids": ["8f3a2b1c-1d2e-4a5b-9c8d-1a2b3c4d5e6f"],
  "price": {
    "value": 29.99,
    "currency": "USD"
  },
  "line_item_pricing": {
    "8f3a2b1c-1d2e-4a5b-9c8d-1a2b3c4d5e6f": {
      "price": {
        "value": 29.99,
        "currency": "USD"
      }
    }
  }

}