Remove Addon - Firmly API

POST

api

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

Change Selection
Clear All Addons
Remove Before Checkout

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"]
  }]
});

To remove all addons from a cart:

// Get current selections
const cart = await getCart();
const selections = cart.addons.selections;

// Remove each addon
for (const selection of selections) {
  await removeAddon({ addon_id: selection.addon_id });
}

Remove optional addons before proceeding to payment:

// Remove non-essential addons
const optionalAddons = ["gift_wrap", "expedited_processing"];

for (const addonId of optionalAddons) {
  if (hasAddon(cart, addonId)) {
    await removeAddon({ addon_id: addonId });
  }
}

Error Responses

400 Bad Request

Invalid request format or missing addon_id

{
  "code": 400,
  "error": "ErrorInvalidInputBody",
  "description": "Request body validation failed"
}

404 Not Found

Cart does not exist

{
  "code": 404,
  "error": "ErrorCartNotFound",
  "description": "Cart not found for this domain"
}

422 Unprocessable Entity

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:

Pricing Updates
- Addon cost removed from totals
- Tax recalculated if applicable
- Shipping costs may change (for delivery-related addons)
Offer Availability
- Removed addon returns to offers array
- May become available for re-selection
- Eligibility rules still apply
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:

Confirmation: Consider showing a confirmation dialog for high-value addons
Visual Feedback: Update UI immediately after removal
Price Display: Show savings when addon is removed
Undo Option: Consider offering a quick “undo” to re-add
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');
  }
}

Add Addon - Add addon selections
Get Cart - View current addon state
Overview - Learn about the three-tier system

Get Public KeyRetrieves the public key for encrypting credit card information

⌘I

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

​Authentication

​Path Parameters

​Request Body

​Response

​Key Response Updates:

​Code Examples

​Removal Examples by Tier

​Remove Cart-Level Addon

​Remove Item-Level Addon

​Remove Hierarchical Addon

​Common Scenarios

​Error Responses

​Important Considerations

​Impact on Cart State

​UI Implementation Guide

​Example UI Flow

​Related Endpoints

Overview

Authentication

Path Parameters

Request Body

Response

Key Response Updates:

Code Examples

Removal Examples by Tier

Remove Cart-Level Addon

Remove Item-Level Addon

Remove Hierarchical Addon

Common Scenarios

Error Responses

Important Considerations

Impact on Cart State

UI Implementation Guide

Example UI Flow

Related Endpoints