Affiliate Discounts & Promo Codes

The HeldSway SDK enables storefronts to look up, validate, and track affiliate coupon discounts directly in the checkout or cart flow.

Overview

When customers enter a promotional coupon code at checkout, the SDK checks its validity, enforces minimum order thresholds, computes the deduction, and attributes the conversion to the associated affiliate.

sequenceDiagram
    participant Shopper as Customer Cart
    participant SDK as HeldSway SDK
    participant API as HeldSway API
    Shopper->>SDK: validateDiscount({ code: "JANE10", orderTotal: 89.97 })
    SDK->>API: POST /sdk/discounts/validate
    API-->>SDK: 200 OK (is_valid: true, discount_amount: 9.00)
    SDK-->>Shopper: Apply discount to order

1. Lookup a Discount Code

Check if a discount code exists and retrieve its configuration without consuming an usage count.

JavaScript SDK Method

const discount = await window.AffiliateSDK.getDiscount("JANE10");

if (discount) {
  console.log(`Valid code: ${discount.type === 'percentage' ? discount.value + '%' : '$' + discount.value} off`);
} else {
  console.log("Discount code is invalid or expired.");
}

Direct HTTP Request

GET /api/v1/sdk/discount/{code}
X-API-Key: <your_sdk_key>

Example Response — HTTP 200 OK

{
  "success": true,
  "message": "OK",
  "data": {
    "code": "JANE10",
    "type": "percentage",
    "value": 10,
    "min_order": 25.00,
    "description": "10% off orders over $25"
  }
}

2. Validate Discount for an Order Total

Validates whether a discount applies to the current cart amount and calculates the exact deduction.

JavaScript SDK Method

const result = await window.AffiliateSDK.validateDiscount({
  code: "JANE10",
  orderTotal: 89.97
});

if (result.isValid) {
  console.log("Discount amount:", result.discountAmount);
  // Deduct from checkout total and display discount badge
} else {
  alert("Coupon code is not valid for this order amount.");
}

Direct HTTP Request

POST /api/v1/sdk/discounts/validate
Content-Type: application/json
X-API-Key: <your_sdk_key>

{
  "code": "JANE10",
  "order_total": 89.97
}

Success Response — Valid Discount

{
  "success": true,
  "message": "OK",
  "data": {
    "is_valid": true,
    "discount_amount": 9.00,
    "affiliate_code": "JANESMITH"
  }
}

Success Response — Below Minimum or Inactive

{
  "success": true,
  "message": "OK",
  "data": {
    "is_valid": false,
    "discount_amount": 0,
    "affiliate_code": null
  }
}

Key Best Practices

1. Case-Insensitive Input: The SDK normalizes discount codes to uppercase automatically.
2. Always Check is_valid: The validation endpoint returns HTTP 200 even when a coupon cannot be applied. Check data.is_valid to determine whether to deduct the amount.
3. Automatic Conversion Attribution: When a coupon has an affiliate_code attached, conversions created with this order are credited to that affiliate even if no referral link was clicked.