retail.coupon-validate

def validate_coupon(coupon: Coupon, lines: Sequence[CouponLine], customer_uses: int, on_date: str) -> CouponCheck

@dataclass(frozen=True)
class Coupon:
    """The rules attached to one coupon code. A null limit is no limit."""

    code: str
    #: first day it can be used
    valid_from: Optional[str]
    #: last day it can be used, inclusive
    valid_to: Optional[str]
    minimum_spend: Optional[Money]
    #: basket: the whole basket counts; eligible: only eligible lines count
    minimum_spend_on: SpendScope
    #: redemptions allowed across all customers
    max_uses: Optional[int]
    #: redemptions so far across all customers
    times_used: int
    max_uses_per_customer: Optional[int]
    #: eligible SKUs; with categories empty too, every line is eligible
    skus: List[str]
    #: eligible categories
    categories: List[str]
    #: never eligible, even when listed above
    excluded_skus: List[str]
    #: never eligible, even when listed above
    excluded_categories: List[str]

SpendScope = Literal["basket", "eligible"]

@dataclass(frozen=True)
class CouponLine:
    """One basket line as the coupon sees it."""

    sku: str
    category: str
    #: the line's price after any line promotions
    total: Money

@dataclass(frozen=True)
class CouponCheck:
    """Whether the coupon applies, every reason it does not, and which lines it can discount."""

    valid: bool
    #: in a fixed order: not-yet-valid, expired, usage-limit-reached, customer-limit-reached, no-eligible-items, minimum-spend-not-met
    reasons: List[str]
    #: 0-based indices into lines, in basket order
    eligible_lines: List[int]

from fune.retail.coupon_validate import validate_coupon  # retail.coupon-validate@^1

import re
from typing import List, Sequence

from .money_compare import compare_money  ← from money.compare ^1.0.0 · built alongside by fune
from .money_sum import sum_money  ← from money.sum ^1.0.0 · built alongside by fune
from .retail_coupon_validate_types import Coupon, CouponLine, CouponCheck

_ISO_DATE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}")


def _is_eligible(coupon: Coupon, line: CouponLine) -> bool:
    open_to_all = len(coupon.skus) == 0 and len(coupon.categories) == 0
    listed = open_to_all or line.sku in coupon.skus or line.category in coupon.categories
    excluded = line.sku in coupon.excluded_skus or line.category in coupon.excluded_categories
    return listed and not excluded


def validate_coupon(coupon: Coupon, lines: Sequence[CouponLine], customer_uses: int, on_date: str) -> CouponCheck:
    """Whether a coupon can be used on a basket, with every reason it cannot.

    ISO dates compare correctly as strings.
    """
    if not isinstance(on_date, str) or not _ISO_DATE.fullmatch(on_date):
        raise ValueError('onDate must be an ISO date (YYYY-MM-DD), received "%s"' % (on_date,))
    if isinstance(customer_uses, bool) or not isinstance(customer_uses, int) or customer_uses < 0:
        raise ValueError("customerUses must not be negative, received %r" % (customer_uses,))

    eligible_lines = [i for i, line in enumerate(lines) if _is_eligible(coupon, line)]

    reasons: List[str] = []
    if coupon.valid_from is not None and on_date < coupon.valid_from:
        reasons.append("not-yet-valid")
    if coupon.valid_to is not None and on_date > coupon.valid_to:
        reasons.append("expired")
    if coupon.max_uses is not None and coupon.times_used >= coupon.max_uses:
        reasons.append("usage-limit-reached")
    if coupon.max_uses_per_customer is not None and customer_uses >= coupon.max_uses_per_customer:
        reasons.append("customer-limit-reached")
    if len(eligible_lines) == 0:
        reasons.append("no-eligible-items")
    if coupon.minimum_spend is not None:
        if coupon.minimum_spend_on == "eligible":
            counted = [lines[i].total for i in eligible_lines]
        else:
            counted = [line.total for line in lines]
        spend = sum_money(counted, coupon.minimum_spend.currency)
        if compare_money(spend, coupon.minimum_spend) < 0:
            reasons.append("minimum-spend-not-met")

    return CouponCheck(valid=len(reasons) == 0, reasons=reasons, eligible_lines=eligible_lines)

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add retail.coupon-validate

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./retail.coupon-validate-1.0.1-python.fune, or fetch it from a terminal with fune pull retail.coupon-validate@1.0.1:python.

The whole function, every language, is one file too: retail.coupon-validate-1.0.1.fune, 33,269 bytes, sha256 4c0c6b527fd50c4a971742164fab44783c6122b6fb78fabb9a80b5a6722cb6fd. It installs into a project of any language.

# fune: before retail.coupon-validate

# fune: after retail.coupon-validate

# fune: replace money.amount in retail.coupon-validate
# fune: replace money.compare in retail.coupon-validate
# fune: replace money.sum in retail.coupon-validate

# fune: step retail.coupon-validate after <n|label>

More from the author

| reason | fails when | |---|---| | `not-yet-valid` | `onDate` is before `validFrom` | | `expired` | `onDate` is after `validTo` (the last day is inclusive) | | `usage-limit-reached` | `timesUsed` is `maxUses` or more | | `customer-limit-reached` | `customerUses` is `maxUsesPerCustomer` or more | | `no-eligible-items` | no line passes the product rules | | `minimum-spend-not-met` | the spend is below `minimumSpend` |

Every failing reason is returned, not just the first, so a checkout can say "this code expired, and it needs a £20 spend" in one go. `valid` is true exactly when `reasons` is empty. A null limit is no limit.

## Which lines are eligible

A line is eligible when its SKU is in `skus` or its category is in `categories` (either list; both empty means every line), and neither its SKU is in `excludedSkus` nor its category in `excludedCategories`. Exclusions always win: that is how "20% off homeware, excluding sale items" is written.

## Minimum spend

`minimumSpendOn` says what counts towards it: `basket` sums every line, `eligible` only the eligible ones. Retailers do both, and the difference is a common source of complaints, so the coupon has to say. Line totals should be after line promotions and before this coupon's own discount. The minimum spend and the lines must share a currency.

This function only decides eligibility. Working out the discount and spreading it across the eligible lines is `money.apply-rate` and `money.allocate`, and recording the use (incrementing `timesUsed`) is the caller's job, once the order is placed, not when the code is checked.

1.0.1 fixes Python accepting a trailing newline or non-ASCII digits in onDate; adds tests.

Files