> ## 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.

# Add Promo Codes

> Applies promotional codes to the cart for discounts

## Overview

This endpoint applies promotional codes to the cart for discounts. It accepts multiple promo codes and validates them against the merchant's active promotions.

<Note>
  The endpoint supports both POST and PUT methods for adding promo codes.
</Note>

## Request

<ParamField path="domain" type="string" required>
  The merchant domain (e.g., "staging.luma.gift")
</ParamField>

<ParamField body="promo_codes" type="array" required>
  Array of promotional codes to apply

  * Minimum: 1 code
  * Maximum: 10 codes
  * Each code must be a valid string
</ParamField>

## Response

Returns a complete shopping cart (same structure as [Get Cart](/api-reference/cart-management/get-cart)) with:

* `coupons` array containing the applied promo codes
* `cart_discount` field with the total discount amount (if applicable)
* Recalculated totals reflecting the discounts

## Promo Code Behavior

### Multiple Codes

* Multiple promo codes can be applied simultaneously
* Codes are validated in the order they are provided
* Each code's eligibility is checked against cart contents

### Validation Rules

* Codes must be active and not expired
* Codes must be applicable to current cart items
* Merchant-specific rules may apply (minimum purchase, product restrictions)

### Impact on Pricing

* Discounts are reflected in the `cart_discount` field
* Line items may include `discount` and `line_discount` amounts
* The `discounts` array on line items contains discount details (if supported by merchant)
* Taxes are recalculated based on discounted prices

## Errors

### ErrorInvalidPromoCode

**Status Code:** 422\
**Description:** One or more promo codes are invalid or expired

### ErrorPromoNotAvailable

**Status Code:** 422\
**Description:** Promo code is not available for current cart contents

### MissingAuthHeader

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

### InvalidToken

**Status Code:** 401\
**Description:** JWT token is invalid

### ErrorInvalidInputBody

**Status Code:** 400\
**Description:** Request body validation failed

## Examples

<CodeGroup>
  ```bash Single Promo Code theme={null}
  curl -X POST 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/promo-codes' \
    -H 'x-firmly-authorization: <your-auth-token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "promo_codes": ["SAVE20"]
    }'
  ```

  ```bash Multiple Promo Codes theme={null}
  curl -X POST 'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/promo-codes' \
    -H 'x-firmly-authorization: <your-auth-token>' \
    -H 'Content-Type: application/json' \
    -d '{
      "promo_codes": ["SAVE20", "FREESHIP", "LOYALTY10"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/promo-codes', {
    method: 'POST',
    headers: {
      'x-firmly-authorization': '<your-auth-token>',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      promo_codes: ['SAVE20']
    })
  });

  const cart = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.firmly.work/api/v2/domains/staging.luma.gift/cart/promo-codes',
      headers={
          'x-firmly-authorization': '<your-auth-token>',
          'Content-Type': 'application/json'
      },
      json={
          'promo_codes': ['SAVE20']
      }
  )

  cart = response.json()
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "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_01H2XVBR8C8JS5MQSFPJ8HF9SB",
      "platform_line_item_id": "gid://shopify/CartLine/123",
      "sku": "WS12-XS-Orange",
      "description": "Radiant Tee",
      "quantity": 2,
      "price": {
        "currency": "USD",
        "value": 49.99,
        "number": 4999,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 79.98,
        "number": 7998,
        "symbol": "$"
      },
      "discount": {
        "currency": "USD",
        "value": 10.00,
        "number": 1000,
        "symbol": "$"
      },
      "line_discount": {
        "currency": "USD",
        "value": 20.00,
        "number": 2000,
        "symbol": "$"
      },
      "image": {
        "src": "https://staging.luma.gift/radiant-tee.jpg",
        "alt": "Radiant Tee"
      },
      "requires_shipping": true
    }
  ],
  "shipments": [
    {
      "shipment_id": "ship_01H2XVBR8C8JS5MQSFPJ8HF9SD",
      "line_item_ids": ["item_01H2XVBR8C8JS5MQSFPJ8HF9SB"],
      "fulfillment_type": {
        "id": "SHIP_TO_ADDRESS",
        "name": "Ship to Address",
        "description": "Standard shipping to your address"
      },
      "shipping_method": {
        "id": "STANDARD_GROUND",
        "description": "Standard Ground (5-7 days)",
        "price": {
          "currency": "USD",
          "value": 9.99,
          "number": 999,
          "symbol": "$"
        },
        "estimated_delivery": "5-7 business days"
      }
    }
  ],
  "coupons": ["SAVE20"],
  "sub_total": {
    "currency": "USD",
    "value": 99.98,
    "number": 9998,
    "symbol": "$"
  },
  "cart_discount": {
    "currency": "USD",
    "value": 20.00,
    "number": 2000,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 9.99,
    "number": 999,
    "symbol": "$"
  },
  "tax_total": {
    "currency": "USD",
    "value": 7.20,
    "number": 720,
    "symbol": "$"
  },
  "total": {
    "currency": "USD",
    "value": 97.17,
    "number": 9717,
    "symbol": "$"
  },
  "addons": {
    "offers": [],
    "selections": []
  },
  "addon_total": {
    "currency": "USD",
    "value": 0,
    "number": 0,
    "symbol": "$"
  },
  "schema_version": "2.0"
}
```

## Key Points

* **Field Names**: The applied codes appear in the `coupons` array, not `promo_codes`
* **Discount Tracking**: Total discount appears in `cart_discount` field
* **Line Item Discounts**: Individual items may show `discount` and `line_discount` fields
* **Multiple Code Support**: Apply up to 10 codes simultaneously