Skip to main content
POST
/
api
/
v2
/
domains
/
{domain}
/
cart
/
addons
/
_remove
Remove Addon
curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/addons/_remove \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "addon_id": "<string>",
  "deselected_line_item_id": "<string>",
  "deselected_child_id": "<string>"
}
'
{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
  "platform_id": "shopify",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "item-1",
      "sku": "MH07-XS-Gray",
      "variant_id": "MH07-XS-Gray",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      }
    }
  ],
  "shipments": [
    {
      "shipment_id": "shipment-1",
      "line_item_ids": ["item-1"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address"
      }
    }
  ],
  "addons": {
    "offers": [
      {
        "addon_id": "shipping_protection",
        "display": {
          "name": "Shipping Protection",
          "description": "Protect your order against damage or loss during shipping"
        },
        "scope": "CART",
        "price": {
          "currency": "USD",
          "value": 12.99,
          "number": 1299,
          "symbol": "$"
        }
      },
      {
        "addon_id": "extended_warranty",
        "display": {
          "name": "3-Year Extended Warranty",
          "description": "Comprehensive coverage for furniture protection"
        },
        "scope": "ITEM",
        "eligible_line_item_ids": ["item-1"],
        "price": {
          "currency": "USD",
          "value": 199.99,
          "number": 19999,
          "symbol": "$"
        }
      }
    ],
    "selections": []  // Empty after removal
  },
  "sub_total": {
    "currency": "USD",
    "value": 54.00,
    "number": 5400,
    "symbol": "$"
  },
  "addon_total": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 54.00,
    "number": 5400,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

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

The Remove Addon endpoint allows customers to remove previously selected addon services from their cart. This endpoint handles removal of addons at any scope (cart, item, or group level) and automatically recalculates cart totals.
Key Features:
  • Remove addon selections by ID
  • Supports partial removal from specific items
  • Automatically recalculates pricing
  • Maintains other addon selections

​
Authentication

​
x-firmly-authorization
string
required
Device authentication token to identify and map the session

​
Path Parameters

​
domain
string
required
Domain of the merchant website (e.g., staging.luma.gift)

​
Request Body

​
addon_id
string
required
The unique identifier of the addon to remove
​
deselected_line_item_id
string
For partial removal: specific line item ID to remove the addon from
​
deselected_child_id
string
For hierarchical addons: specific child addon ID to remove

​
Response

Returns the complete shopping cart with the addon removed and pricing recalculated.

​
Key Response Updates:

​
addons.selections
array
Updated selections array with the specified addon removed
​
addon_total
object
Recalculated total cost of remaining addons
​
total
object
Updated cart total reflecting the removal

​
Code Examples

curl --request POST \
  --url https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/addons/_remove \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_TOKEN' \
  --data '{
    "addon_id": "shipping_protection"
  }'

​
Removal Examples by Tier

​
Remove Cart-Level Addon

Remove shipping protection from the entire order: 
{
  "addon_id": "shipping_protection"
}
Before removal: 
{
  "addons": {
    "selections": [
      {
        "addon_id": "shipping_protection",
        "price": { "value": 12.99 }
      }
    ]
  },
  "addon_total": { "value": 12.99 }
}
After removal: 
{
  "addons": {
    "selections": []
  },
  "addon_total": { "value": 0.00 }
}

​
Remove Item-Level Addon

Remove extended warranty from specific items: 
{
  "addon_id": "extended_warranty"
}
When removing an item-level addon without specifying deselected_line_item_id, it’s removed from all items for which it was selected. Use deselected_line_item_id to remove specific items only.

​
Remove Hierarchical Addon

Remove a parent addon with child selections: 
{
  "addon_id": "furniture_installation"
}
This removes the parent addon and all its selected child addons (e.g., white glove service, assembly). 
{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SA",
  "platform_id": "shopify",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "item-1",
      "sku": "MH07-XS-Gray",
      "variant_id": "MH07-XS-Gray",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 54.00,
        "number": 5400,
        "symbol": "$"
      }
    }
  ],
  "shipments": [
    {
      "shipment_id": "shipment-1",
      "line_item_ids": ["item-1"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address"
      }
    }
  ],
  "addons": {
    "offers": [
      {
        "addon_id": "shipping_protection",
        "display": {
          "name": "Shipping Protection",
          "description": "Protect your order against damage or loss during shipping"
        },
        "scope": "CART",
        "price": {
          "currency": "USD",
          "value": 12.99,
          "number": 1299,
          "symbol": "$"
        }
      },
      {
        "addon_id": "extended_warranty",
        "display": {
          "name": "3-Year Extended Warranty",
          "description": "Comprehensive coverage for furniture protection"
        },
        "scope": "ITEM",
        "eligible_line_item_ids": ["item-1"],
        "price": {
          "currency": "USD",
          "value": 199.99,
          "number": 19999,
          "symbol": "$"
        }
      }
    ],
    "selections": []  // Empty after removal
  },
  "sub_total": {
    "currency": "USD",
    "value": 54.00,
    "number": 5400,
    "symbol": "$"
  },
  "addon_total": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 54.00,
    "number": 5400,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

​
Common Scenarios

To change from one addon to another (e.g., switching warranty types):
// Step 1: Remove current warranty
await removeAddon({ addon_id: "warranty_1year" });

// Step 2: Add new warranty
await addAddon({ 
  selections: [{
    addon_id: "warranty_3year",
    selected_line_item_ids: ["item-1"]
  }]
});

​
Error Responses

Invalid request format or missing addon_id
{
  "code": 400,
  "error": "ErrorInvalidInputBody",
  "description": "Request body validation failed"
}
Cart does not exist
{
  "code": 404,
  "error": "ErrorCartNotFound",
  "description": "Cart not found for this domain"
}
Addon not found in current selections
{
  "code": 422,
  "error": "ErrorUnprocessableEntity",
  "description": "Addon not found in cart selections"
}

​
Important Considerations

Removal Behavior:
  • Removing a parent addon also removes all child selections
  • Item-level addons are removed from ALL items unless deselected_line_item_id is specified
  • Use deselected_line_item_id to remove from specific items only
  • Required addons cannot be removed without consequences

​
Impact on Cart State

When an addon is removed:
  1. Pricing Updates
    • Addon cost removed from totals
    • Tax recalculated if applicable
    • Shipping costs may change (for delivery-related addons)
  2. Offer Availability
    • Removed addon returns to offers array
    • May become available for re-selection
    • Eligibility rules still apply
  3. Related Addons
    • Child addons are removed with parent
    • Dependent addons may become unavailable
    • Group constraints are re-evaluated

​
UI Implementation Guide

Best Practices for Remove Actions:
  1. Confirmation: Consider showing a confirmation dialog for high-value addons
  2. Visual Feedback: Update UI immediately after removal
  3. Price Display: Show savings when addon is removed
  4. Undo Option: Consider offering a quick “undo” to re-add
  5. Clear Messaging: Explain what will be removed (especially for hierarchical addons)

​
Example UI Flow

async function handleRemoveAddon(addonId, addonName, price) {
  // Show confirmation for valuable addons
  if (price > 50) {
    const confirmed = await showConfirmDialog({
      title: `Remove ${addonName}?`,
      message: `This will remove $${price} from your order.`,
      confirmText: 'Remove',
      cancelText: 'Keep'
    });
    
    if (!confirmed) return;
  }
  
  // Remove addon
  try {
    showLoadingState();
    const updatedCart = await removeAddon({ addon_id: addonId });
    updateCartUI(updatedCart);
    showSuccessMessage(`${addonName} removed`);
  } catch (error) {
    showErrorMessage('Failed to remove addon');
  }
}