Skip to main content
DELETE
https://api.firmly.work
/
api
/
v2
/
domains
/
{domain}
/
cart
/
promo-codes
Clear Promo Codes
curl --request DELETE \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/promo-codes \
  --header 'Authorization: Bearer <token>'

Overview

This endpoint removes all applied promotional codes from the cart and recalculates totals without promotional discounts.
Some merchants may have this functionality disabled. Check the ErrorClearPromoCodeNotAllowed error response.

Request

domain
string
required
The merchant domain (e.g., “staging.luma.gift”)
No request body is required for this endpoint.

Response

Returns a complete shopping cart (same structure as Get Cart) with:
  • Empty coupons array (all promo codes removed)
  • cart_discount reset to zero (if applicable)
  • Totals recalculated without promotional discounts

Promo Code Clearing Behavior

What Happens

  • The coupons array is cleared
  • The cart_discount field is reset (if applicable)
  • Line item discount and line_discount fields are removed
  • Taxes are recalculated based on full prices

Use Cases

  • Customer wants to remove all discounts
  • Testing different promo code combinations
  • Cart cleanup before applying new codes

Errors

ErrorClearPromoCodeNotAllowed

Status Code: 422
Description: Merchant has disabled promo code clearing functionality

MissingAuthHeader

Status Code: 401
Description: x-firmly-authorization header is missing or invalid

InvalidToken

Status Code: 401
Description: JWT token is invalid

ErrorCartNotFound

Status Code: 404
Description: Cart session not found

Examples

curl -X DELETE 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/promo-codes' \
  -H 'x-firmly-authorization: <your-auth-token>'

Response Examples

Standard Response

{
  "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-12345",
      "sku": "WT08-XS-Purple",
      "description": "Antonia Racer Tank",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 49.99,
        "number": 4999,
        "symbol": "$"
      }
    }
  ],
  "shipments": [
    {
      "shipment_id": "shipment-12345",
      "line_item_ids": ["item-12345"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "shipping_method": {
        "id": "STANDARD_GROUND",
        "description": "Standard Ground",
        "price": {
          "currency": "USD",
          "value": 9.99,
          "number": 999,
          "symbol": "$"
        },
        "estimated_delivery": "5-7 business days"
      }
    }
  ],
  "coupons": [],
  "sub_total": {
    "currency": "USD",
    "value": 99.98,
    "number": 9998,
    "symbol": "$"
  },
  "cart_discount": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 9.99,
    "number": 999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 8.80,
    "number": 880,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 118.77,
    "number": 11877,
    "symbol": "$"
  },
  "addons": {
    "offers": [],
    "selections": []
  },
  "addon_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

Multiple Items Response

{
  "cart_id": "cart_01H2XVBR8C8JS5MQSFPJ8HF9SB",
  "platform_id": "shopify",
  "shop_id": "staging.luma.gift",
  "display_name": "Luma Store",
  "cart_status": "active",
  "line_items": [
    {
      "line_item_id": "item-67890",
      "sku": "MH07-XS-Black",
      "description": "Hero Hoodie",
      "quantity": 1,
      "price": {
        "currency": "USD",
        "value": 299.99,
        "number": 29999,
        "symbol": "$"
      }
    },
    {
      "line_item_id": "item-11111",
      "sku": "WT09-XS-White",
      "description": "Breathe-Easy Tank",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 39.99,
        "number": 3999,
        "symbol": "$"
      }
    }
  ],
  "shipments": [
    {
      "shipment_id": "mixed-shipment-001",
      "line_item_ids": ["item-67890", "item-11111"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "shipping_method": {
        "id": "STANDARD_GROUND",
        "description": "Standard Ground",
        "price": {
          "currency": "USD",
          "value": 12.99,
          "number": 1299,
          "symbol": "$"
        },
        "estimated_delivery": "5-7 business days"
      }
    }
  ],
  "coupons": [],
  "sub_total": {
    "currency": "USD",
    "value": 379.97,
    "number": 37997,
    "symbol": "$"
  },
  "cart_discount": {
    "currency": "USD",
    "value": 0.00,
    "number": 0,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 12.99,
    "number": 1299,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 31.44,
    "number": 3144,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 424.40,
    "number": 42440,
    "symbol": "$"
  },
  "addons": {
    "offers": [],
    "selections": []
  },
  "addon_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "schema_version": "2.0"
}

Key Points

  • Field Names: Cleared codes are removed from the coupons array, not promo_codes
  • Discount Reset: The cart_discount field returns to zero
  • Merchant Controls: Some merchants may disable this functionality
  • Complete Response: Returns the full cart structure with updated pricing