Skip to main content
POST
/
api
/
v2
/
domains
/
{domain}
/
cart
/
promo-codes
Add Promo Codes
curl --request POST \
  --url https://api.firmly.work/api/v2/domains/{domain}/cart/promo-codes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "promo_codes": [
    {}
  ]
}
'

​
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.
The endpoint supports both POST and PUT methods for adding promo codes.

​
Request

​
domain
string
required
The merchant domain (e.g., “staging.luma.gift”)
​
promo_codes
array
required
Array of promotional codes to apply
  • Minimum: 1 code
  • Maximum: 10 codes
  • Each code must be a valid string

​
Response

Returns a complete shopping cart (same structure as 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

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"]
  }'

​
Response Example

{
  "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