=== UseAdvert Affiliate Marketing & Sales ===
Contributors: useadvert
Tags: affiliate, influencer marketing, referral, commission, coupons
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.3.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Track influencer- and affiliate-driven sales in WooCommerce with Advert: attribute orders, reverse commissions on refund, and sync creator coupons.

== Description ==

Advert Affiliate Tracking connects your WooCommerce store to [Advert](https://useadvert.com), an influencer and affiliate marketing platform. It answers one question reliably: which creator drove this sale?

**What it does**

* **Link attribution.** A creator's tracked link carries an `adref` code. The plugin records it against the customer's session and pins it onto the order at checkout, so attribution survives an offsite payment gateway and a customer who never returns to the thank-you page.
* **Coupon attribution.** If no link code is present, the plugin falls back to the first coupon applied to the order.
* **Refund reversal.** Add your Refund Secret and a refunded order automatically reverses the creator's commission — cancelling a pending sale, or clawing back a charge still inside its hold window.
* **Creator coupon sync.** Advert generates a unique promo code per creator; the plugin creates the matching WooCommerce coupon and removes it when the campaign ends. Codes that already exist in your store are never taken over.

**Built for modern WooCommerce**

Compatible with High-Performance Order Storage (HPOS) and the Cart & Checkout blocks. Conversions are reported at most once per order.

**An Advert account is required.** The plugin is a client for the Advert service and does nothing on its own. You can create an account at [useadvert.com](https://useadvert.com).

== External services ==

This plugin connects to the Advert API at `https://api.useadvert.com` to attribute sales to creators. It is not optional: attribution is the entire purpose of the plugin, and no data leaves your site until you enter a Webhook Secret on the settings screen.

The following requests are made:

1. **Store registration** — `POST https://api.useadvert.com/api/woocommerce/register`
   Sent when you save your settings, and once when the plugin is activated with a secret already configured.
   Data sent: your Webhook Secret and your site URL.

2. **Conversion reporting** — `POST https://api.useadvert.com/track/conversion` or `https://api.useadvert.com/track/promo`
   Sent when an order reaches the thank-you page, or transitions to Processing or Completed.
   Data sent: the order ID, the order total, the affiliate link code or coupon code applied, a timestamp, and your Webhook Secret. No customer name, email address, or shipping address is transmitted.

3. **Refund reporting** — `POST https://api.useadvert.com/track/refund`
   Sent when an order is refunded, and only if you have configured a Refund Secret.
   Data sent: the order ID and your Refund Secret.

4. **Coupon sync** — `POST https://api.useadvert.com/api/woocommerce/coupons/pull` and `.../coupons/ack`
   Sent on a recurring schedule (every 5 minutes by default) while a Webhook Secret is configured.
   Data sent: your Webhook Secret, and the outcome of each coupon job (created, revoked, or failed).

Every request includes a user-agent string identifying the plugin version and your site URL.

Advert is operated by Advert. Use of the service is governed by its [Terms of Service](https://useadvert.com/terms) and [Privacy Policy](https://useadvert.com/privacy).

**Browser storage.** When a visitor arrives via a tracked link, the plugin stores the link code in that visitor's browser `localStorage` under the key `advert_ref`, so the attribution outlives a WooCommerce session that expires first. No cookie is set by this plugin and no personal data is stored in the browser.

== Installation ==

1. In WordPress admin, go to **Plugins → Add New → Upload Plugin**.
2. Choose the plugin ZIP and click **Install Now**, then **Activate**.
3. Go to **WooCommerce → Advert** and paste your Webhook Secret. You will find it in Advert under **Products → [Product] → Connect Your Store**.
4. Optionally paste your Refund Secret, from **Connect Your Store → Developer API**, to auto-reverse commissions on refunded orders.

WooCommerce must be installed and active.

== Frequently Asked Questions ==

= Do I need an Advert account? =

Yes. This plugin reports sales to the Advert service; it does not track affiliates on its own.

= Will a customer refreshing the thank-you page report the sale twice? =

No. The plugin marks each order once its conversion has been accepted and will not report it again.

= What happens if a creator's coupon code already exists in my store? =

The plugin refuses to touch it and reports the job as failed back to Advert. An existing coupon of yours is never re-pointed at a creator.

= How often does coupon sync run? =

Every five minutes, using Action Scheduler (which ships with WooCommerce). Developers can change this with the `advert_coupon_sync_interval` filter.

= Is it compatible with HPOS? =

Yes. The plugin declares compatibility with High-Performance Order Storage and reads and writes order data through the WooCommerce CRUD API.

= Can I point the plugin at a staging environment? =

Define `ADVERT_AFF_API_BASE` in `wp-config.php` before the plugin loads.

== Screenshots ==

1. The Advert settings screen under WooCommerce, where the Webhook Secret and Refund Secret are entered.

== Changelog ==

= 1.3.0 =
* Added: High-Performance Order Storage (HPOS) and Cart & Checkout blocks compatibility declarations.
* Added: attribution is now pinned to the order at checkout, so sales through offsite payment gateways are attributed correctly.
* Added: conversions are also reported on the Processing and Completed status transitions, not only on the thank-you page.
* Added: full translation support and a Settings link on the Plugins screen.
* Fixed: a refreshed thank-you page could report the same conversion more than once.
* Fixed: deactivating the plugin left the coupon-sync schedule running.
* Changed: coupon sync now polls every 5 minutes instead of every minute, filterable via `advert_coupon_sync_interval`.
* Changed: activation no longer makes a blocking API call; registration is queued instead.
* Changed: secrets are entered in password fields, and the settings form is hardened.

= 1.2.0 =
* Added: influencer coupon sync — the plugin registers the site with Advert and applies coupon create/delete jobs.

= 1.1.0 =
* Added: automatic commission reversal on refund via the Refund Secret.

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.3.0 =
Adds HPOS compatibility and fixes duplicate conversion reporting. Recommended for all stores.
