Brainerce
Help CenterPricingResourcesDashboard
API ReferenceEndpointsCartApply coupon to cart

Apply coupon to cart

Supports Idempotency-Key header for safe retries.

POST
/v1/cart/{cartId}/coupon

Authorization

AuthorizationBearer <token>

Admin API key (server-to-server). Issue via the dashboard at Settings → API keys. Plain-text key is shown once — store in a secret manager. Format: Authorization: Bearer brainerce_xxxxxxxxx.

In: header

Path Parameters

cartIdstring

Cart ID

Header Parameters

Idempotency-Key?string

Client-supplied key (a UUID v4 is the recommended form, max 255 characters) that makes this mutation safe to retry.

  • Replay window: 24 hours. The first response for a key is cached; a retry inside the window with the same request body returns the original status and body without re-running the handler.
  • Reusing a key with a different body returns 409 Conflict with code: "IDEMPOTENCY_KEY_REUSED". The request fingerprint (method + path + body hash) is compared against the stored one; a mismatch is refused rather than served the old response.
  • Keys are scoped to the calling credential and store — two API keys may safely use the same key value.
  • Error responses are cached too, so a retry of a request that failed validation returns the same 400 immediately.
  • Sending this header on a GET returns 400 with code: "IDEMPOTENCY_KEY_NOT_SUPPORTED" — GETs are already idempotent.
  • Support is per-route and this parameter is the authoritative signal: a key sent to a route that does not declare it is accepted and silently ignored.

See /docs/api/idempotency.

Lengthlength <= 255

Request Body

codestring

Coupon code (case-insensitive). Validation runs server-side and a refused code returns 400 with a code: COUPON_NOT_FOUND, COUPON_NOT_ACTIVE, COUPON_EXPIRED, COUPON_USAGE_LIMIT_REACHED, COUPON_PER_CUSTOMER_LIMIT_REACHED, COUPON_MINIMUM_NOT_MET, COUPON_REGION_RESTRICTED or COUPON_NO_ELIGIBLE_ITEMS.

Lengthlength <= 100
curl -X POST "https://api.brainerce.com/api/v1/cart/string/coupon" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "code": "SUMMER25"  }'
{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "sessionToken": "cs_7d9f2a1b3c4e5f60",
  "customerId": "clx1a2b3c4d5e6f7g8h9",
  "status": "ACTIVE",
  "currency": "USD",
  "notes": "Leave at the door",
  "analyticsClientId": "clx1a2b3c4d5e6f7g8h9",
  "analyticsSessionId": "clx1a2b3c4d5e6f7g8h9",
  "subtotal": "59.80",
  "discountAmount": "5.00",
  "ruleDiscountAmount": "5.00",
  "promoDiscountTotal": "0.00",
  "couponCode": "WELCOME10",
  "appliedDiscounts": [
    {
      "ruleId": "clx1a2b3c4d5e6f7g8h9",
      "ruleName": "Summer sale",
      "type": "ORDER_DISCOUNT",
      "discountAmount": "10.00",
      "description": "10% off orders over 200"
    }
  ],
  "nudges": [
    {
      "ruleId": "clx1a2b3c4d5e6f7g8h9",
      "text": "Add 20.00 more for free shipping",
      "type": "AMOUNT_NEEDED",
      "amountNeeded": "20.00",
      "quantityNeeded": 1
    }
  ],
  "items": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "productId": "clx1a2b3c4d5e6f7g8h9",
      "variantId": "clx1a2b3c4d5e6f7g8h9",
      "quantity": 2,
      "unitPrice": "29.90",
      "currentUnitPrice": "31.90",
      "priceChanged": true,
      "priceDelta": "2.00",
      "priceDirection": "increased",
      "isAvailable": true,
      "unavailableReason": "PRODUCT_DRAFT",
      "discountAmount": "0.00",
      "promoDiscountAmount": "0.00",
      "promoSource": "BUNDLE",
      "promoSourceId": "clx1a2b3c4d5e6f7g8h9",
      "notes": "Gift wrap please",
      "metadata": {},
      "customizations": {},
      "product": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Classic T-Shirt",
        "sku": "TSHIRT-BLK-M",
        "images": [
          {}
        ]
      },
      "variant": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Black / M",
        "sku": "TSHIRT-BLK-M",
        "image": {
          "url": "string",
          "alt": "string"
        }
      },
      "modifiers": [
        {
          "modifierId": "clx1a2b3c4d5e6f7g8h9",
          "modifierGroupId": "clx1a2b3c4d5e6f7g8h9",
          "name": "Extra cheese",
          "priceDelta": "5.00",
          "freeApplied": true,
          "effectivePrice": "5.00",
          "positionInGroup": 0
        }
      ],
      "modifiersTotal": "5.00",
      "parentCartItemId": "clx1a2b3c4d5e6f7g8h9",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "itemCount": 2,
  "hasPriceChanges": true,
  "hasUnavailableItems": true,
  "unavailableItemIds": [
    "string"
  ],
  "expiresAt": "2019-08-24T14:15:22Z",
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z",
  "reservation": {
    "hasReservation": true,
    "expiresAt": "2019-08-24T14:15:22Z",
    "remainingSeconds": 540,
    "strategy": "ON_PAYMENT",
    "countdownMessage": "Your items are reserved for 9 minutes"
  },
  "recommendations": {
    "recommendations": [
      {
        "id": "string",
        "name": "string",
        "slug": "string",
        "basePrice": "string",
        "salePrice": "string",
        "images": [
          {
            "url": "string",
            "alt": "string"
          }
        ],
        "type": "SIMPLE",
        "inventory": {
          "total": 0,
          "available": 0,
          "trackingMode": "TRACKED",
          "inStock": true,
          "canPurchase": true
        },
        "relationType": "string",
        "targetVariantId": "string",
        "requiresVariantSelection": true,
        "pinnedVariant": {
          "id": "string",
          "name": "string",
          "attributes": {}
        },
        "variants": [
          {
            "id": "string",
            "name": "string",
            "attributes": {},
            "image": {
              "url": "string",
              "alt": "string"
            },
            "price": "string",
            "salePrice": "string"
          }
        ]
      }
    ]
  },
  "upgrades": {
    "upgrades": {}
  },
  "bundles": {
    "bundles": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "triggerProductId": "string",
        "productIds": [
          "string"
        ],
        "offeredProducts": [
          {
            "id": "string",
            "name": "string",
            "slug": "string",
            "basePrice": "string",
            "salePrice": "string",
            "images": [
              {
                "url": "string",
                "alt": "string"
              }
            ],
            "type": "SIMPLE",
            "variantId": "string",
            "requiresVariantSelection": true,
            "pinnedVariant": {
              "id": "string",
              "name": "string",
              "attributes": {}
            },
            "variants": [
              {
                "id": "string",
                "name": "string",
                "attributes": {},
                "image": {
                  "url": "string",
                  "alt": "string"
                },
                "price": "string",
                "salePrice": "string"
              }
            ],
            "originalPrice": "string",
            "discountedPrice": "string"
          }
        ],
        "discountType": "PERCENTAGE",
        "discountValue": "string",
        "totalOriginalPrice": "string",
        "totalDiscountedPrice": "string"
      }
    ]
  }
}

{
  "statusCode": 400,
  "code": "VALIDATION_FAILED",
  "message": "name should not be empty, price must be a positive number",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/cart/{cartId}/coupon"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/cart/{cartId}/coupon"
}

{
  "statusCode": 403,
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key does not have the required scope: products:write",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/cart/{cartId}/coupon"
}

{
  "statusCode": 404,
  "code": "RESOURCE_NOT_FOUND",
  "message": "Resource not found",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/cart/{cartId}/coupon"
}

{
  "statusCode": 429,
  "code": "RATE_LIMITED",
  "message": "Too many requests",
  "details": {
    "retryAfterSeconds": 12
  },
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/cart/{cartId}/coupon"
}

Clear all items from cart

Clear all items from cart. DELETE /v1/cart/{cartId}/items in the Brainerce API.

Remove coupon from cart

Remove coupon from cart. DELETE /v1/cart/{cartId}/coupon in the Brainerce API.