Skip to main content

Smart Coupons Advanced

Overview​

Smart Coupons Advanced extends WooCommerce's own coupons rather than replacing them. A WooCommerce coupon gains a row in this module's table that says how it should behave: apply itself automatically when the cart qualifies, be applied by a link, or act as a buy-one-get-one offer.

It also carries a store credit balance per customer, spendable at checkout and expirable, plus a configurable reward percentage that turns completed orders into credit.

Because it builds on WooCommerce coupons, the discount logic, usage limits and restrictions a store already knows continue to work; this module decides when and how the coupon reaches the cart.

It is for stores running promotions that should not require the customer to know a code.

Availability​

ItemValue
Module keysmart-coupons-advanced
TierPremium
Entitlement keysmart-coupons-advanced
Admin tabsmart-coupons
Enabled optionaiowc_module_enabled_smart-coupons-advanced (off until turned on)
REST namespaceaiowc/v1

Enabling the module creates the four tables below, seeds the defaults and schedules the three jobs.

registerHooks() returns early when the licence does not grant smart-coupons-advanced. Each feature is then constructed with its setting passed in, so a feature switched off is inert inside the service rather than merely hidden.

Settings​

Stored in the bundled option row aiowc_sc_settings.

Stored keyDefaultMeaning
enable_auto_applytrueWhether qualifying coupons apply themselves.
enable_url_couponstrueWhether a coupon can be applied by visiting a link.
enable_bogotrueWhether buy-one-get-one coupons are processed.
enable_store_credittrueWhether the store credit balance is offered at checkout.
allow_coupon_stackingfalseWhether several coupons may apply at once. Off by default.
show_coupon_notificationtrueWhether the customer is told a coupon was applied for them.
reminder_days_before3How far ahead of expiry a reminder is sent.
credit_expiry_days365How long issued store credit lasts.
reward_percent0.0Percentage of a completed order returned as store credit. Zero by default — the reward feature is off until a store sets it.

Coupon behaviours​

coupon_type / flagBehaviour
auto_applyThe coupon applies itself when the cart matches its restrictions. The default type.
url_couponThe coupon is applied when the customer arrives on a link carrying its code.
BOGOConfigured in bogo_config, giving an item when a qualifying item is bought.

restrictions holds the module's own extra conditions, and expires_at gives a smart coupon its own expiry independent of the WooCommerce coupon's.

Whether two coupons may apply together is governed by allow_coupon_stacking, which is off by default — so without changing it, one coupon applies at a time.

Store credit​

A credit row carries a balance, a source (admin by default), the order it came from, and an expiry. Spending writes a transaction row with the amount, the type, a description and the order.

With reward_percent above zero, a completed order issues credit worth that percentage of the order back to the customer, expiring after credit_expiry_days.

🔴 Balances live in the Store Credit ledger. Store Credit owns store credit. Once its ledger is ready (Store Credit switched on at the current version), every balance this module reads or writes goes through StoreCreditLedger under idempotency keys prefixed smart_coupons:, and checkout spends that one balance.

This module's own aiowc_store_credits rows move into the ledger once: a customer's rows when their balance is first read, and the rest in batches of 100 on admin page loads until done (option aiowc_sc_ledger_migration_version). A moved row keeps its id and history; its balance goes to zero with a debit transaction reading "Moved to the Store Credit ledger". Nothing is deleted.

If Store Credit has never been switched on, this module keeps using its own tables, the balances stay spendable but are not combined with any other, and an admin notice on the Empora screen and the dashboard says so.

Admin screen​

The Smart Coupons tab lists the smart coupon rows and creates, edits and deletes them, shows per-coupon analytics, and edits the module's nine settings.

REST API endpoints​

All routes are on aiowc/v1 and answer with the { success, data, message } envelope.

MethodPathPurposePermissionRequired args
GET/coupons/smartEvery smart coupon row.manage_woocommerce–
POST/coupons/smartAttach smart behaviour to a coupon.manage_woocommercecoupon_type
PATCH/coupons/smart/{id}Update it.manage_woocommerceid
DELETE/coupons/smart/{id}Remove it.manage_woocommerceid
GET/coupons/{id}/analyticsHow often the coupon has been used, and for how much.manage_woocommerceid
GET / PATCH / PUT / POST/coupons/settingsRead and write the settings.manage_woocommerce–
GET/coupons/auto-applyThe coupons that would apply to this cart.Public, rate-limited–
POST/coupons/url-apply/{code}Apply a coupon by code from a link.Nonce, rate-limited–
GET/store-credits/balanceThe signed-in customer's credit balance.Signed-in user–
POST/store-credits/applySpend credit on the current cart.Signed-in user–

The two store-credit routes require a signed-in customer, so a balance is always read for the caller rather than for a named user id.

WooCommerce integration​

HookWhat the module does
initRegisters the URL-coupon handler, so a link applies its coupon on arrival.
woocommerce_before_calculate_totalsApplies auto-apply coupons, BOGO and store credit to the cart.
woocommerce_applied_couponReacts when a coupon is applied, including by the customer.
woocommerce_checkout_order_processedRecords usage against the coupon.
woocommerce_order_status_completedIssues the reward credit, where reward_percent is set.

Shortcodes [aiowc_my_coupons] lists the customer's available coupons, and [aiowc_store_credit] prints their credit balance.

Database schema​

TableHolds
{prefix}aiowc_smart_couponsThe behaviour attached to a WooCommerce coupon: type, auto-apply and URL flags, BOGO configuration, restrictions, its own expiry.
{prefix}aiowc_coupon_usage_logOne row per use: the coupon, customer, order and amount discounted.
{prefix}aiowc_store_creditsA customer's credit: balance, source, originating order, expiry.
{prefix}aiowc_store_credit_transactionsMovements against a credit: amount, type, description, order.

Background jobs​

HookIntervalWork
aiowc_coupons_expire_checkdailyExpires smart coupons past their date.
aiowc_coupons_send_remindersdailyWarns customers about a coupon expiring in reminder_days_before days.
aiowc_store_credits_expiredailyExpires store credit past credit_expiry_days.

All three run on WP-Cron, first scheduled an hour after the module is enabled.

Action hooks for integrators​

HookFired when
aiowc_track_eventThe module is enabled or disabled.

The module fires no coupon or credit lifecycle events, so an integration cannot react to a coupon applying itself or to credit being issued or spent.

Entitlement limits​

smart-coupons-advanced is an on/off grant with no cap on the number of smart coupons, credits or transactions.

Health check​

The module reports a warning when its tables are missing or WooCommerce is inactive, and otherwise reports that it is functioning normally. A disabled module reports that it is disabled.

Known gaps​

  • Until Store Credit is switched on, this module's balances stay separate from Gift Cards' store-credit cards; the admin notice is the only signal.
  • reward_percent defaults to 0.0, so the order-reward feature appears to do nothing until a store notices the setting.
  • No lifecycle hooks are fired, so an integration cannot observe a coupon auto-applying or credit being issued.
  • Analytics are per coupon; there is no store-wide view of what the auto-apply feature has cost.
  • The module extends WooCommerce coupons, so a smart coupon row whose underlying WooCommerce coupon is deleted is left without its coupon. Nothing cleans those rows up.