Brainerce
Help CenterPricingResourcesDashboard
API ReferenceEndpointsPublic API (v1)Apply coupon to checkout

Apply coupon to checkout

Supports Idempotency-Key header for safe retries.

POST
/v1/checkout/{checkoutId}/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

checkoutIdstring

Checkout 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/checkout/string/coupon" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "code": "SUMMER25"  }'
{
  "id": "clx1a2b3c4d5e6f7g8h9",
  "status": "PENDING",
  "email": "[email protected]",
  "customerId": "clx1a2b3c4d5e6f7g8h9",
  "deliveryType": "shipping",
  "pickupLocation": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "name": "Main store",
    "rateName": "Store pickup",
    "address": {
      "line1": "Herzl 12",
      "line2": "Apt 4",
      "city": "Tel Aviv",
      "region": "Center District",
      "postalCode": "6578301",
      "country": "IL"
    },
    "phone": "+972501234567",
    "hours": "Sun-Thu 09:00-18:00",
    "instructions": "Bring your order number",
    "price": "0.00",
    "currency": "USD"
  },
  "shippingAddress": {
    "firstName": "Dana",
    "lastName": "Cohen",
    "company": "Acme Ltd",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "region": "Center District",
    "postalCode": "6578301",
    "country": "IL",
    "phone": "+972501234567"
  },
  "billingAddress": {
    "firstName": "Dana",
    "lastName": "Cohen",
    "company": "Acme Ltd",
    "line1": "Herzl 12",
    "line2": "Apt 4",
    "city": "Tel Aviv",
    "region": "Center District",
    "postalCode": "6578301",
    "country": "IL",
    "phone": "+972501234567"
  },
  "shippingRateId": "clx1a2b3c4d5e6f7g8h9",
  "shippingMethod": {
    "id": "clx1a2b3c4d5e6f7g8h9",
    "name": "Standard shipping",
    "description": "Delivery in 3 to 5 business days",
    "price": "15.00",
    "currency": "USD",
    "estimatedDays": 4,
    "source": "manual",
    "carrier": "ups",
    "service": "ground",
    "speedTier": "cheapest",
    "requiresPickupPoint": true
  },
  "currency": "USD",
  "subtotal": "59.80",
  "discountAmount": "5.00",
  "ruleDiscountAmount": "5.00",
  "appliedRules": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Summer sale",
      "type": "ORDER_DISCOUNT",
      "discountAmount": "10.00"
    }
  ],
  "shippingAmount": "15.00",
  "taxAmount": "11.46",
  "taxBreakdown": {
    "subtotal": 50.9,
    "shippingNet": 12.71,
    "totalTax": 11.46,
    "total": 75.1,
    "breakdown": [
      {
        "name": "VAT",
        "rate": 18,
        "amount": 9.17
      }
    ],
    "currency": "USD"
  },
  "total": "81.26",
  "surchargeAmount": "0.00",
  "appliedSurcharges": [
    {
      "key": "handling",
      "name": "Handling fee",
      "value": "string",
      "amount": "5.00"
    }
  ],
  "customFieldValues": {},
  "couponCode": "WELCOME10",
  "tenders": [
    {
      "tenderId": "clx1a2b3c4d5e6f7g8h9",
      "amountApplied": "50.00"
    }
  ],
  "providerAmountDue": "81.26",
  "notes": "Leave at the door",
  "lineItems": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "productId": "clx1a2b3c4d5e6f7g8h9",
      "variantId": "clx1a2b3c4d5e6f7g8h9",
      "quantity": 2,
      "unitPrice": "29.90",
      "discountAmount": "0.00",
      "product": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Classic T-Shirt",
        "sku": "TSHIRT-BLK-M",
        "images": [
          {}
        ],
        "isDownloadable": true
      },
      "variant": {
        "id": "clx1a2b3c4d5e6f7g8h9",
        "name": "Black / M",
        "sku": "TSHIRT-BLK-M"
      },
      "notes": "Gift wrap please",
      "metadata": {},
      "customizations": {}
    }
  ],
  "itemCount": 2,
  "availableShippingRates": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9",
      "name": "Standard shipping",
      "description": "Delivery in 3 to 5 business days",
      "price": "15.00",
      "currency": "USD",
      "estimatedDays": 4,
      "source": "manual",
      "carrier": "ups",
      "service": "ground",
      "speedTier": "cheapest",
      "requiresPickupPoint": true
    }
  ],
  "expiresAt": "2019-08-24T14:15:22Z",
  "recoveryEmailSentAt": "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"
  },
  "presentment": {
    "currency": "USD",
    "subtotal": "59.80",
    "discountAmount": "0.00",
    "shippingAmount": "15.00",
    "taxAmount": "11.46",
    "surchargeAmount": "0.00",
    "total": "86.26",
    "fxChargingRate": "3.65",
    "fxBufferPercent": "2.00"
  },
  "pickupPoint": {
    "id": "pp_48213",
    "name": "Kiosk Herzl",
    "kind": "store",
    "address": {
      "street1": "Herzl 12",
      "city": "Tel Aviv",
      "zip": "6578301",
      "country": "IL"
    },
    "latitude": 32.0668,
    "longitude": 34.7647,
    "hours": "Sun-Thu 08:00-20:00",
    "note": "Next to the pharmacy",
    "distanceKm": 0.8
  },
  "totalAmount": "81.26"
}

{
  "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/checkout/{checkoutId}/coupon"
}

{
  "statusCode": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid or expired credential",
  "timestamp": "2026-08-23T10:15:00.000Z",
  "path": "/api/v1/checkout/{checkoutId}/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/checkout/{checkoutId}/coupon"
}

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

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

Enable, disable or revoke a gift card

Deliberately does NOT touch live holds: a checkout that already reserved value settles normally, because pulling it out from under a shopper mid-payment...

Remove coupon from checkout

Remove coupon from checkout. DELETE /v1/checkout/{checkoutId}/coupon in the Brainerce API.