Skip to main content
POST
https://api.firmly.work
/
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"
}

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');
  }
}