Version 8.2.0 – REST API & Webhooks

| Posted on |

Version 8.2.0 of Coupon Affiliates is now available!

This update adds a more comprehensive REST API and webhooks for connecting external tools, dashboards and AI assistants to your affiliate program, a new “Lifetime” tab for managing the customers linked to each affiliate, a full breakdown of how any order’s commission was worked out, redesigned and customisable payout statements, right-to-left language support on the affiliate dashboard, and a large speed-up across every screen that totals up commission.

REST API

Coupon Affiliates now has a proper REST API, so your affiliate data no longer has to live only inside WordPress. You can pull statistics into an external dashboard, sync affiliates and referrals with another system, wire your program into an automation tool, or point an AI assistant at it and ask it questions about your affiliates.

You will find it under Coupon Affiliates > Admin Tools > API. The API stays switched off until you enable it, and individual endpoints can be turned on and off from the same page, so nothing is exposed that you have not deliberately allowed.

In short:

  • Endpoints for affiliates, coupons, referred orders, clicks, registrations, reports, payouts, activity events, and a “me” endpoint that an affiliate’s own integration can call.
  • API keys with scopes. Create a key, choose whether it can read, write, or manage the API itself, give it an optional expiry date, and revoke it at any time. WordPress application passwords work too.
  • Permissions are inherited. A key acts as a specific user, so administrators can read everything, while a key issued for an affiliate only ever sees that affiliate’s own coupons, statistics and payouts.
  • An OpenAPI document is generated for your own site, so tools that understand OpenAPI (including most AI assistants) can discover the endpoints themselves.

The API is included in the free version. The full endpoint reference, authentication details, request examples and webhook payloads are all in the documentation:

View the API documentation

Webhooks

Rather than polling the API for changes, PRO users can have your site tell another service the moment something happens.

Add a webhook, choose which events it should receive, and a signed JSON payload is sent to your URL whenever one of them fires: a referral being attributed, commission being added or removed, a registration being submitted, approved or declined, and payouts being requested, paid, cancelled or reversed. Multi-level commission events are included as well.

Every delivery is signed with HMAC-SHA256 so the receiving end can verify it really came from your store, failed deliveries are retried with a backoff, and there is a “Send test” button to check your endpoint before you rely on it.

A “Lifetime” tab on the affiliate page

Lifetime commission links a customer to an affiliate so their future orders keep earning commission, even when the coupon is not used again. Until now there was no simple way to see those links, let alone change one.

The “View Affiliate” page now has a Lifetime tab listing every customer linked to that affiliate, with the coupon they are linked to, the date the link expires, and whether it is currently active, expired, or set to never expire. There is a summary of those counts at the top, and the list can be filtered by status.

Both the linked coupon and the expiry date can be edited directly from the list, and a customer can be unlinked from the affiliate entirely. Leaving the expiry date blank means the link never expires. Every change is recorded in the activity log.

See exactly how a commission was calculated

“Why is the commission on this order that amount?” is one of the most common questions we get, and answering it used to mean checking the coupon, the product rates, the user role rates and the settings one by one.

Hovering over the commission amount in the “Coupon Affiliate” panel on an order now shows the whole calculation:

  • Which coupon earned it, which affiliate it went to, and how the order was attributed to them: the coupon being used at checkout, a lifetime link, or a referral URL.
  • Which configured rate won – the coupon’s own rate, a product or category rate, a user role or group rate, or the site default.
  • A line by line breakdown of the order, with the total split into the percentage, fixed per order and fixed per product parts that make up the final figure.

It also tells you when the figure was earned by a different coupon to the one you are looking at, which is easy to miss on an order with more than one coupon on it.

While we were in there, the panel itself has been restyled, and its “refresh” button is more reliable.

Redesigned payout statements

The PDF payout statement your affiliates download has been redesigned, with a clearer header and a status badge, the “From” and “Paid To” details side by side, a tidier items table, and a highlighted total that picks up the button colour from your design settings.

The details an affiliate fills in for their statements can now be customised too. A new “Customise affiliate details fields” panel under the payout statement settings lets you rename the company, address and tax number fields, mark any of them as required, and hide the ones you do not need. Hiding a field only removes it from the dashboard and statements – anything an affiliate has already entered is kept. You can also add extra fields of your own, which appear underneath the built-in ones and are printed on their statements.

Labels are left blank by default, so nothing changes on your site until you enter your own wording.

A few statement fixes went in alongside it: the tax number and any extra fields are now labelled in the “Paid To” section, rather than a reference number being printed on a line of its own with nothing to say what it is; a payout marked as paid without a payment date recorded against it showed “Nov 30th, -0001” as its date, and now falls back to the date the payout was requested; with statement tax turned off the total printed without its currency symbol or decimal places, for example “74.71” rather than “$74.71”; and a long “footer text” printed its line breaks as literal <br/> tags instead of wrapping onto the next line.

Orders with more than one coupon

If a customer stacks two affiliate coupons on the same order, the commission for that order was stored as a single figure that the last coupon overwrote.

Each affiliate was still credited correctly at the time, but when the order later left a completed status – refunded, cancelled, or moved back to processing – only that one stored figure was available to take back, so the wrong amount was removed from one of the affiliates.

Each coupon now records and removes its own amount, so the balance goes back exactly as it was granted. Commission handling on orders with more than one coupon has been improved more generally as part of the same work.

Faster dashboards, reports and leaderboards

The plugin’s settings are all stored in a single option, and every setting the plugin read meant unpacking that whole option again from scratch. On a screen that totals up commission across hundreds of orders, each of which checks a handful of settings, that added up to a surprising share of the page load.

Those settings are now read once per request and reused. The affiliate dashboard, the admin reports, the leaderboard and every other screen that totals up commission are all noticeably quicker as a result, with the heaviest pages seeing the biggest improvement.

Generating the admin reports has had a few further improvements of its own on top of that.

We have also made some performance improvements to the “View Affiliate” page, which is significantly quicker for affiliates with a lot of referrals. Its “Referred Orders” tab can now also be filtered by order status and by coupon, and searched by order number, customer name or email address.

Right-to-left language support

The affiliate dashboard had no right-to-left support at all, so certain languages stayed left-aligned, tabs and icons sat on the wrong side, and labels came out reading “:Total Sales” with the colon on the wrong end.

The dashboard is now mirrored properly, and it happens automatically on any site running a right-to-left language – there is nothing to switch on.

Translations have had some attention elsewhere too. Around thirty pieces of text on the leaderboard are now translatable, along with a number of dashboard, portal and settings strings that were missing from the translation template. The custom “Affiliate” terminology you can set in the design settings now also applies to the affiliate dashboard, the MLA portal and the leaderboard, instead of only the admin area.

Settings that silently failed to save

On some hosts, using “save all settings” appeared to work, showed no error, and then quietly discarded everything you had changed.

The cause was PHP’s max_input_vars limit. Bulk saves are now sent in batches that fit within the limit, so they work regardless of your host’s configuration. And if a save is blocked or the database write fails for any other reason, you now get an error explaining why instead of a success message.

Other changes

A few smaller additions and fixes:

  • On stores in a timezone ahead of UTC, an order placed shortly after midnight was missing from “Referred Orders”, the dashboard statistics and the commission graph until later in the day, even though the all-time totals counted it. Date ranges now follow the store’s own timezone instead of UTC.
  • The “Export Affiliate Users” button on the Coupon Affiliate Users page now sits on the right and opens a panel to choose the group, role and sort order before downloading, matching the export on the Affiliate Orders page.
  • The “Non-Affiliate Coupon Settings” are now available in the free version, and have moved higher up the commission settings tab.
  • The Affiliate Portal and MLA Portal pages could return a “404 Not Found” on sites that had never re-saved their settings. The required URL rules are now installed automatically whenever they are missing.
  • The Affiliate Portal slug was not escaped in its URL rule, so an empty slug or one containing punctuation could take over other pages.
  • Adding a coupon to an affiliate from the affiliate view page reported that the coupon already existed when a coupon with the same code was sitting in the trash. Codes whose coupon has been deleted can now be used again.
  • Sending a test newsletter added a backslash before every apostrophe and quotation mark in the subject and content. Newsletters sent to affiliates were not affected.

Full Changelog

  • New: A REST API for connecting external tools, dashboards and AI assistants to your affiliate program, with API keys, scopes and an OpenAPI document. See “Coupon Affiliates > Admin Tools > API”.
  • New: (PRO) Webhooks, sending a signed JSON notification to another service whenever a referral, commission, registration or payout happens.
  • New: (PRO) A “Lifetime” tab on the affiliate view page, listing every customer linked to that affiliate, with the linked coupon and expiry date editable from the list. Customers can also be assigned to an affiliate as their lifetime referrer by hand, without waiting for the customer to order on the coupon.
  • New: Hovering the commission amount in the “Coupon Affiliate” panel on an order now shows a full breakdown of how that figure was calculated.
  • New: Right-to-left support for the affiliate dashboard, applied automatically on sites using a right-to-left language such as Hebrew, Arabic, Farsi or Urdu.
  • New: A “New Coupon Assigned” email, sent to an existing affiliate when an admin gives them an additional coupon. The “Add New Coupon” and “Add New Affiliate” forms now let you choose which email the affiliate receives, or send none at all, and the email can be edited or turned off under the notification settings.
  • New: (PRO) A “Customise affiliate details fields” panel under the payout statement settings, for renaming the company, address and tax number fields the affiliate fills in, marking any of them as required, hiding the ones you do not need, and adding extra fields of your own. Labels are left blank by default, so nothing changes until you enter your own wording.
  • Tweak: Significantly sped up the affiliate dashboard, admin reports, leaderboard and every other screen that totals up commission.
  • Tweak: Significantly sped up the “View Affiliate” page for affiliates with a lot of referrals.
  • Tweak: The “Referred Orders” tab on the “View Affiliate” page can now be filtered by order status and by coupon, and searched by order number, customer name or email address. The “To” date is also now pre-filled with today’s date.
  • Tweak: Made a few improvements to the speed and performance of generating admin reports.
  • Tweak: (PRO) Improved the speed of loading the “Commission Graph” on the affiliate dashboard.
  • Tweak: Improved the commission handling when more than one coupon was used on the same order.
  • Tweak: Updated the styling of the “Coupon Affiliate” panel on the edit order page.
  • Tweak: The “Export Affiliate Users” button on the Coupon Affiliate Users page now sits on the right and opens a panel to choose the group / role and sort order before downloading, matching the export on the Affiliate Orders page.
  • Tweak: Improved the reliability of the “refresh” button on an order’s “Coupon Affiliate” panel.
  • Tweak: The custom “Affiliate” terminology set under the design settings is now applied to the affiliate dashboard, MLA portal and leaderboard, not just the admin area.
  • Tweak: (PRO) Made around thirty pieces of text on the leaderboard translatable, along with a number of dashboard, portal and settings strings missing from the translation template.
  • Tweak: The “Non-Affiliate Coupon Settings” are now available in the free version, and have been moved higher up the commission settings tab.
  • Tweak: Updated the “Admin Tools” page styling and layout.
  • Tweak: (PRO) Redesigned the PDF payout statement, with a clearer header and a status badge, side-by-side “From” and “Paid To” panels, a tidier items table and a highlighted total that picks up the button colour from your design settings.
  • Tweak: (PRO) The tax number, and any extra fields you add, are now labelled in the “Paid To” section of a payout statement, so a reference number is no longer printed on a line of its own with nothing to say what it is.
  • Tweak: Custom registration field answers were only saved to the affiliate’s profile when the application created a new account, so an applicant who was already logged in had the values on their application but nowhere else – the dashboard “Account Details” and admin user screens showed the fields blank even once accepted. Answers on existing applications can be copied across with the new “Restore Registration Field Answers” tool, which appears under Admin Tools only if your site has any to copy.
  • Fix: A custom registration field whose label contained an apostrophe or an ampersand (for example “Recipient’s full name”) never matched its stored answer, so it always displayed as blank, and answers containing an apostrophe displayed as “&#039;”.
  • Fix: (PRO) On an order with more than one coupon, the granted commission was stored as a single figure that the last coupon overwrote, so the wrong amount was taken back when the order left a completed status. Each coupon now records and removes its own amount.
  • Fix: Refreshing an affiliate’s statistics did not recalculate pending commission on stores using High-Performance Order Storage.
  • Fix: On stores in a timezone ahead of UTC, an order placed shortly after midnight was missing from “Referred Orders”, the dashboard statistics and the commission graph until later in the day, even though the all-time totals counted it. Date ranges now follow the store’s own timezone instead of UTC.
  • Fix: (PRO) Lifetime commission was calculated twice on stores using High-Performance Order Storage, and the customer was only linked to their lifetime affiliate on the second run.
  • Fix: (PRO) Fixed an issue with the commission balance when re-opening a cancelled order.
  • Fix: (PRO) Store credit was taken before payment, and was not returned if the payment failed. It is now returned when an order fails or is cancelled, and taken again if that order is later paid.
  • Fix: The Affiliate Portal and MLA Portal pages could return a “404 Not Found” on sites that had never re-saved their settings. The required URL rules are now installed automatically whenever they are missing.
  • Fix: The Affiliate Portal slug was not escaped in its URL rule, so an empty slug or one containing punctuation could take over other pages. It is now escaped and falls back to “affiliate-portal”.
  • Fix: (PRO) Sending a test newsletter added a backslash before every apostrophe and quotation mark in the subject and content. Newsletters sent to affiliates were not affected.
  • Fix: Settings could silently fail to save when saving all at once on servers with a low PHP “max_input_vars” limit, or when a save was blocked or the database write failed. Bulk saves now fit within the limit, and any failure to save now shows the reason.
  • Fix: Adding a coupon to an affiliate from the affiliate view page reported that the coupon already existed when a coupon with the same code was sitting in the trash. Codes whose coupon has been deleted can now be used again, and the admin “Add New Affiliate” form no longer blocks a code whose accepted registration points to a deleted coupon.
  • Fix: Adding a coupon to an existing, already approved affiliate sent them the “Affiliate Application Submitted” email, telling them their application had been received and would be reviewed when nothing was pending. The new “New Coupon Assigned” email is sent instead, and the “Custom Message” field on that form is now included in it rather than being discarded.
  • Fix: (PRO) Cancelling or failing an order no longer leaves its commission in the affiliate’s pending balance, and cancelling a completed order no longer adds the commission back as pending.
  • Fix: With the settings page set to “Manual Saving”, the “Save Settings” button did nothing at all. A stored currency conversion rate with more decimal places than its field allowed made the browser refuse to submit the form, and choosing “Manual Saving” was itself never saved, so the page reverted to automatic saving.
  • Fix: Some settings appear on more than one settings tab. When saving all settings at once, changing one of them was undone by the copy on the other tab, which still held the old value. All copies of a setting now update together.
  • Fix: (PRO) A payout marked as paid without a payment date recorded against it showed “Nov 30th, -0001” as the date on its statement. Statements now fall back to the date the payout was requested.
  • Fix: (PRO) With statement tax turned off, the total on a payout statement was printed without its currency symbol or decimal places, for example “74.71” rather than “$74.71”.
  • Fix: (PRO) A long “footer text” on a payout statement printed its line breaks as literal “<br/>” tags instead of wrapping onto the next line.

Check out some other posts:

Leave a Reply

Your email address will not be published. Required fields are marked *