Promo (DropCorePromo)#
src/promo/drop_core_promo.ts. Routes at promo/**.
credits: Credits#
| method | endpoint | notes |
|---|---|---|
push(uid, value, { record? }) |
promo/credits/push |
value is in credits (1 credit = $0.01). |
value(uid) |
promo/credits/value |
Current balance for a user. |
records(uid, options?) |
promo/credits/records |
The per-user ledger; supports query / limit / order_by / offset / mask. |
The admin-side equivalent is admin.promo.credits (a DropCollection), which
gives raw Document Database access to the credits documents. Use the promo
route when you want the server's transactional takeCredits / push
semantics applied.
coupons: Coupons#
Coupon operations with server-side semantics — minting short unique codes,
read-only validation, and transactional redemption. The batch documents
themselves are managed through the generic admin CRUD (admin.promo.coupons /
admin.promo.codes, above). Every call accepts an optional batch secret — the
bearer credential that lets token-less external campaign tools mint / verify /
claim against one batch.
| method | endpoint | notes |
|---|---|---|
mint(id, { customer?, limit?, secret? }) |
promo/coupons/mint |
Mint exactly one code for a dynamic/generated batch (rejects static batches); master/owner token or the batch secret. Returns {code}. |
mintBatch(id, count, { customer?, limit?, secret? }) |
promo/coupons/mint-batch |
Bulk-mint count codes in one call (chunked batched writes server-side, hard-capped at 10000). Returns a summary {minted, requested, chunks, ms} — the codes are not echoed. |
verify(code, context?) |
promo/coupons/verify |
Read-only rule-chain check; returns {valid, batch?, effect?, reason?, unverified?} (unverified = conditions that need cart context). Never mutates. |
claim(code, context?) |
promo/coupons/claim |
Transactional redemption — re-runs the rules, increments usage, records the claimant (context adds order?). Failures throw with {valid: false, reason}. |
CouponContext carries customer?, order_value?, products? and secret?.
Checkout doesn't call claim directly: coupon codes ride
OrderInitEntity.promo.coupons into process/order/make and are validated and
redeemed at payment initialization (invalid codes are dropped silently —
pre-validate with verify); the applied discount lands in invoice.discount.