Skip to main content
DELETE
/
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>'

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

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