Getting Started

Introduction

The Coupon Affiliates REST API gives external tools, scripts and AI agents structured JSON access to your affiliate program: affiliates, coupons, referred orders, commission, payouts, registrations, click tracking, a change-event feed and store-wide reports. It also delivers outbound webhooks (PRO), so other systems can react the moment something happens in your program. On the free version the same ground is covered by polling the change-event feed, which carries a cursor for exactly that.

Everything lives under one base URL on your own site:

https://example.com/wp-json/wcusage/v2

A first request, using a WordPress application password for an admin user:

curl https://example.com/wp-json/wcusage/v2/me \
  -u "admin:abcd efgh ijkl mnop qrst uvwx"

{
  "user": { "id": 1, "display_name": "Admin", "login": "admin", "email": "admin@example.com" },
  "is_admin": true,
  "is_affiliate": false,
  "auth": { "method": "wordpress", "key_id": null, "scopes": null },
  "coupons": [],
  "api_version": "8.2.0"
}

What you can do with it

• Report — pull program totals, per-affiliate stats, per-coupon sales and commission, and referred-order lists into a BI tool, spreadsheet or custom dashboard.
• Automate — approve or decline affiliate applications, create payout requests, and react to program events in real time.
• Integrate — connect Zapier/Make-style automation, a CRM, an accounting system, or an AI agent that answers questions about your affiliates.
• Build affiliate-facing tools — an affiliate can authenticate as themselves and read only their own data, so you can build a custom affiliate app without handing out admin access.

Who can use it

• Admins — any user who passes the plugin's admin access check (usually manage_woocommerce, or whichever capability you configured) can read and manage everything.
• Affiliates — can read their own coupons, stats, referred orders, click stats and payouts, and can request a payout for their own coupon. They cannot see other affiliates, store-wide reports or the events feed.
• Multi-level uplines (PRO) — can also read a downline affiliate's coupon, stats and referred orders.
• Nobody else. There are no anonymous endpoints other than the OpenAPI document.

Requirements

• Coupon Affiliates 8.2 or later, with the API switched on (see the next page).
• The WordPress REST API enabled — it is by default.
• Pretty permalinks, if you want to use the /wp-json/… URL form. On a site with plain permalinks, use https://example.com/?rest_route=/wcusage/v2/me instead: the /wp-json/ path is not a REST request at all on such a site, and API keys will not authenticate against it.
• HTTPS. API keys are refused over plain HTTP outside local and development environments.
• Some endpoints depend on features that may not be present (payouts, registrations, clicks, activity log). Those answer 501 rather than pretending to be empty — see Availability.

Enabling the API

The API ships switched off. A site never starts answering API requests just because the plugin was updated — an administrator has to turn it on deliberately.

1. Go to Coupon Affiliates → Admin Tools → API in wp-admin.
2. Press Enable API at the top of the page.
3. Create an API key, or use a WordPress application password.

The same screen shows your base URL, the OpenAPI URL, every registered endpoint with the access level it needs, your API keys, and — on PRO — your webhooks.

Turning individual endpoints on and off

Each endpoint has its own checkbox on the API screen. Unticking one removes it from the route table for every request — it answers 404 with the core code rest_no_route, exactly as though it had never been registered. This is the right tool for narrowing what any integration can reach at all, regardless of who authenticates.

The settings live in the wcusage_api_settings option. Only the exceptions are stored, so an endpoint added in a later release is on by default once the API itself is on.

What the master switch controls

Authentication

Every endpoint except /openapi requires an authenticated WordPress user. Three methods work; each resolves to a user, and that user's capabilities decide what the request may access.

Application passwords

Built into WordPress. Create one under Users → Profile → Application Passwords, then send it with HTTP Basic auth:

curl https://example.com/wp-json/wcusage/v2/affiliates \
  -u "admin:abcd efgh ijkl mnop qrst uvwx"

An application password carries the user's full permissions, on this API and on every other WordPress endpoint. It is the quickest way to get started, and fine for a trusted server-to-server integration you control.

API keys

Plugin API keys are the better choice for anything you do not fully control, because they can be scoped, expired and revoked without touching the WordPress account. Create one under Coupon Affiliates → Admin Tools → API, or through the key management endpoints.

A key looks like wcus_9f2c1e4a… and is shown once, at creation — only a SHA-256 hash is stored. Send it as a bearer token:

curl https://example.com/wp-json/wcusage/v2/me \
  -H "Authorization: Bearer wcus_9f2c1e4a7b3d5e6f8a9b0c1d2e3f4a5b6c7d8e9f"

If your client cannot set the Authorization header (some hosts strip it), an alternative header is accepted:

X-WCUsage-API-Key: wcus_9f2c1e4a7b3d5e6f8a9b0c1d2e3f4a5b6c7d8e9f

Every key:

• Acts as one WordPress user. A key created against an affiliate's account can only ever reach that affiliate's own data, whatever it asks for. A key against an admin account has admin access.
• Carries scopes that restrict it further, on top of that user's capabilities.
• Works only on this plugin's namespaces — wcusage/v2 and woo-coupon-usage/v1. Presenting one to a core or WooCommerce endpoint fails with 403 wcusage_api_key_wrong_namespace. An API key is not a general-purpose WordPress credential.
• Can have an optional expiry date, and can be revoked at any moment. Revocation takes effect on the very next request.
• Records a last used timestamp, updated at most once every five minutes — a liveness signal, not an audit log.

Scopes

Scopes apply only to API keys. With an application password or a logged-in cookie, auth.scopes is null and access is governed purely by capabilities. A key missing a required scope receives 403 with the code wcusage_api_insufficient_scope.

On the legacy woo-coupon-usage/v1 namespace, which predates scopes, keys are held to a fail-closed default: GET, HEAD and OPTIONS need read, anything else needs write.

Cookie authentication

Same-site JavaScript can use the logged-in cookie with a REST nonce, exactly as with any WordPress REST endpoint:

fetch( '/wp-json/wcusage/v2/me', {
  headers: { 'X-WP-Nonce': wpApiSettings.nonce },
  credentials: 'same-origin'
} ).then( r => r.json() );

HTTPS

Bearer tokens are credentials, so they are refused over plain HTTP unless wp_get_environment_type() reports local or development. Such a request fails with 401 wcusage_api_https_required. The wcusage_api_require_https filter can override it — do that only if you know exactly why.

Failed-attempt lockout

An address that presents 20 invalid keys within 15 minutes is refused further attempts with 429 wcusage_api_too_many_auth_failures until the window rolls over. Counts are kept per IP address, so one client cannot lock out another. Adjust with the wcusage_api_max_auth_failures filter.

Who am I?

Whatever method you use, GET /me reports exactly what the request is authenticated as, what access level it has, and which scopes are in force. Call it first when setting up any integration.

Requests & Responses

Conventions

• All responses are JSON. GET parameters go in the query string; POST and PATCH parameters go in a JSON body with Content-Type: application/json (WordPress also accepts form-encoded bodies).
• Resources are addressed by numeric ID. Coupon codes are never identifiers: WooCommerce coupon codes are case-insensitive and are not guaranteed unique.
• Money values are plain JSON numbers in the store's currency — no symbol, no thousands separators. GET /reports/summary reports the currency code.
• Collections are returned as a bare JSON array, with totals in response headers.

Pagination

Every collection endpoint takes the same two parameters:

And returns the same two headers:

• X-WP-Total — total matching items.
• X-WP-TotalPages — total pages at the current per_page.

A page past the end of the result set returns an empty array with correct headers, without running the underlying query.

Dates

• Request parameters (from, to, expires) use Y-m-d, e.g. 2026-08-01. Anything else is rejected with 400 rest_invalid_param.
• Response fields use ISO 8601 in the site's timezone, e.g. 2026-08-07T14:03:22. Empty dates are null.
• Ranges include both ends. When from is given without to, to defaults to today.

Errors

Errors use the standard WordPress REST shape. Every code raised by this plugin is prefixed wcusage_api_:

{
  "code": "wcusage_api_forbidden",
  "message": "You do not have permission to access this resource.",
  "data": { "status": 403 }
}

Rate-limit and throttle errors add retry_after (seconds) to data.

A full list of plugin error codes is in the Error reference.

Rate limiting

Requests to both plugin namespaces are counted per minute, per identity — the API key, the logged-in user, or a shared bucket for anonymous callers:

• Authenticated: 120 requests per minute
• Unauthenticated: 30 requests per minute

Over the limit, requests get 429 wcusage_api_rate_limited with retry_after: 60. Malformed requests are counted too, so a client stuck retrying a bad parameter is throttled like any other. Adjust the ceiling with the wcusage_api_rate_limit filter.

Performance & Caching

Most endpoints read cached figures and are cheap enough to poll. A few recalculate from the order history and are deliberately expensive; those are cached and throttled so one client cannot make the database do unbounded work.

What is cached

Throttle responses

When an uncached recalculation is asked for inside the one-per-minute window, the response is 429 with code wcusage_api_throttled and retry_after: 60. The one exception is all-time coupon stats, which return the stored snapshot with source: "throttled" rather than failing.

Working efficiently

• For "what changed?", poll /events?after={id} — one cheap indexed query — or use webhooks and stop polling altogether.
• For "how is the program doing?", one call to /reports/summary replaces walking every affiliate.
• Use per_page=100 on collections instead of many small pages.
• Prefer all-time stats (no from/to) for frequent reads; ask for a range only when you need one.

Security & Disclaimers

The API hands external systems real access to your affiliate program — personal data, commission figures and, in some configurations, the ability to move money. Please read this page before building anything against it.

Your responsibilities

Enabling the API is an explicit decision, and everything done with the credentials you issue is done on your authority and under your account. In particular, you are responsible for:

• Every key you create. A key acts as the WordPress user you attached it to, with that user's capabilities. Creating a key against an administrator account and pasting it into a third-party service gives that service administrator-level reach over your affiliate data.
• Where the data goes. Once a response leaves your server, its handling is governed by whoever received it — the SaaS platform, the spreadsheet, the AI provider — not by this plugin.
• What your automations do. Approving applications, cancelling payouts and creating payout requests are all real, consequential actions. The API performs what it is asked to; it cannot know whether the request reflects what you intended.
• Storing credentials safely. Keys and webhook secrets belong in a secret store or environment variable, never in a repository, a support ticket, a screenshot or a shared document.

Personal data

Several endpoints return personal data about real people: affiliate names, logins and email addresses, registration profile fields such as phone numbers and websites, and any custom registration fields your store collects.

• Under the GDPR, the UK GDPR and comparable regimes, you are the data controller for that information. Sending it to a third-party tool generally makes that tool a processor, which usually means you need a lawful basis for the transfer and an appropriate data-processing agreement with the provider.
• Deliberate omissions in this API are safety features, not oversights: order rows carry no customer data, payout destination details are never returned, click IP addresses are never exposed, and logins and emails are withheld from callers who are neither an admin nor the person concerned. If you add fields back with the response filters, you take on responsibility for what you have exposed and to whom.
• Grant the narrowest access that does the job. A read-only key on a dedicated account, scoped to the endpoints you actually call, limits the blast radius of a leak far more effectively than anything you can add afterwards.

Money and financial records

Commission figures, payout amounts and report totals come from the plugin's own records and are provided for information. They are not an accounting system, a tax record or a substitute for your payment provider's statements.

• Reconcile against your gateway and your books before paying anybody or filing anything. Figures can legitimately change — refunds, cancellations, manual adjustments and snapshot rebuilds all move them.
• All-time statistics are read from stored snapshots that can lag reality in either direction. Where the number matters, check source and last_refreshed, or request a fresh calculation.
• The plugin's authors accept no responsibility for payments made, withheld or duplicated as a result of an integration you build.

Treat inbound webhooks as untrusted

A webhook receiver is a public HTTP endpoint that anybody on the internet can send a request to. Nothing about a payload proves it came from your store except a valid signature.

• Always verify the HMAC signature and reject stale timestamps before acting on a delivery. If your platform cannot verify signatures, do not let it take consequential action on a payload alone — read the object back from the API first.
• Deliveries are at-least-once and unordered. Build handlers that tolerate duplicates and out-of-sequence arrivals.
• Validate and escape payload values like any other external input before writing them into your own systems.

Third-party and AI services

Connecting an external platform or an AI assistant means transmitting affiliate data to that provider, where it may be logged, retained or used for their own purposes according to their terms — not yours. Check what you are agreeing to before you connect it.

AI agents carry a specific extra risk: an agent acts on text it reads, and some of that text can come from outside your control — an application's "how will you promote us" field, a campaign name, a website URL. An agent with write access can be steered by content like that into taking actions you never asked for. Give agents read-only keys unless you have a concrete reason not to, and never give one the manage scope.

Stability and support

• Endpoints, response fields and defaults may change between plugin versions. Fields may be added at any time, so write clients that ignore unfamiliar keys rather than failing on them.
• Do not depend on anything not documented here — internal option names, database tables, undocumented fields or the exact wording of a message. The code in an error response is the stable part; the message is not, and is translated.
• Rate limits, cache windows and throttles exist to protect your site and may be adjusted in future releases. Handle 429 gracefully rather than assuming a fixed budget.
• Support covers the plugin and its own endpoints. Debugging custom integrations, third-party platforms and AI tooling is outside its scope, though the /me, /openapi and /webhooks endpoints are usually enough to work out where a problem lies.

No warranty

Coupon Affiliates is free software, licensed under the GNU General Public License version 3. Sections 15 and 16 of that license disclaim all warranties and limit liability, and those terms apply to the API exactly as they apply to the rest of the plugin. The API, the code samples in these docs and the integration patterns they describe are therefore provided as is, without warranty of any kind.

The examples are illustrative starting points, not production-hardened code: they omit the logging, retry policy, input validation and secret management your own environment will need. Review, adapt and test anything you take from here before relying on it.

To the fullest extent permitted by law, the plugin's authors accept no liability for loss or damage arising from use of the API — including lost or exposed data, incorrect commission or payout amounts, missed or duplicated webhook deliveries, or the actions of any third-party service or automated agent you connect to it. Nothing here affects any statutory rights that cannot lawfully be excluded.

Licensing

The plugin, its API and its add-ons are distributed under the GPLv3; a copy ships as license.txt in the plugin folder. You are free to use, study, modify and redistribute the code on those terms.

• Nothing on this page restricts those rights. It is operational guidance and a disclaimer of warranty and liability — which the GPL expressly permits — not an additional condition on using the software.
• The code samples in these docs are yours to use. Copy, adapt and ship them in your own integrations, commercial or otherwise, with no attribution required. They are short illustrative snippets, published so that people can build against the API.
• Your integration is your own work. A client that talks to this API over HTTP is a separate program; calling a REST endpoint does not make your codebase a derivative of the plugin. If you instead modify or bundle the plugin's own PHP, the GPL applies to what you distribute in the ordinary way.
• The licence covers the software, not your obligations. It says nothing about data protection, consumer law or your duties to your own affiliates and customers — those apply regardless of how the plugin is licensed.

Endpoint Index

Every route in the API, with the access level and scope it needs. All paths are relative to https://example.com/wp-json/wcusage/v2.

"Owner" means the affiliate the coupon is assigned to; "upline" means their multi-level parent, which exists in PRO only. Payout and webhook routes are PRO only. Every endpoint can additionally be switched off per site — see Enabling the API.

Endpoints

Me

Identify the authenticated caller, its access level and its scopes. This is the ideal first call for any integration — an AI agent can use it to discover what it is allowed to do before attempting anything.

[get] /wp-json/wcusage/v2/me

Permission: any authenticated user. No scope is needed for the identity fields; the coupons array requires read.

{
  "user": { "id": 1456, "display_name": "Sarah J", "login": "sarahj", "email": "sarah@example.com" },
  "is_admin": false,
  "is_affiliate": true,
  "auth": { "method": "api_key", "key_id": 3, "scopes": ["read"] },
  "coupons": [
    {
      "id": 8338,
      "code": "sarah10",
      "user_id": 1456,
      "date_created": "2023-05-02T10:11:12",
      "unpaid_commission": 40.46,
      "pending_order_commission": 0,
      "pending_payout_commission": 0
    }
  ],
  "api_version": "8.2.0"
}

Affiliates

An affiliate is a WordPress user with at least one published coupon assigned to them. There is no separate affiliate table; these endpoints derive the entity the same way the admin list table does, and aggregate across all of an affiliate's coupons.

List affiliates

[get] /wp-json/wcusage/v2/affiliates

Permission: admin, read scope.

[
  {
    "user": { "id": 1456, "display_name": "Sarah J", "login": "sarahj", "email": "sarah@example.com" },
    "coupons": [
      { "id": 8338, "code": "sarah10", "user_id": 1456, "date_created": "2023-05-02T10:11:12",
        "unpaid_commission": 40.46, "pending_order_commission": 0, "pending_payout_commission": 0 }
    ],
    "unpaid_commission": 40.46,
    "pending_payout_commission": 0
  }
]

Results are ordered by user ID ascending. Only users holding at least one published assigned coupon appear.

Get one affiliate

[get] /wp-json/wcusage/v2/affiliates/{user_id}

Permission: admin, or the affiliate themselves. read scope.

Returns the list shape plus detail fields, and each coupon carries its cached all-time stats block:

Affiliate stats

[get] /wp-json/wcusage/v2/affiliates/{user_id}/stats

Permission: admin, or the affiliate themselves. read scope.

{
  "user_id": 1456,
  "from": null,
  "to": null,
  "totals": {
    "orders_count": 19,
    "total_sales": 1977.80,
    "total_discount": 197.78,
    "total_commission": 181.60,
    "unpaid_commission": 40.46,
    "pending_payout_commission": 0
  },
  "coupons": [
    { "id": 8338, "code": "sarah10", "orders_count": 19, "total_sales": 1977.80,
      "total_discount": 197.78, "total_commission": 181.60 }
  ]
}

The two balance figures in totals are always current balances; they are not affected by from/to.

Coupons

Affiliate coupons, with balances, stats and referred orders. Reads go through the same functions the affiliate dashboard uses, so caps, rounding and commission rules always match what affiliates see.

List coupons

[get] /wp-json/wcusage/v2/coupons

Permission: admin, read scope.

Returns published coupons that have an affiliate assigned, newest first. Coupons with no assigned affiliate are never listed.

Get one coupon

[get] /wp-json/wcusage/v2/coupons/{id}

Permission: admin, the assigned affiliate, or their multi-level upline (PRO). read scope.

{
  "id": 8338,
  "code": "sarah10",
  "user_id": 1456,
  "user": { "id": 1456, "display_name": "Sarah J" },
  "date_created": "2023-05-02T10:11:12",
  "unpaid_commission": 40.46,
  "pending_order_commission": 0,
  "pending_payout_commission": 0,
  "stats": {
    "orders_count": 19, "total_sales": 1977.80, "total_discount": 197.78,
    "total_shipping": 0, "total_commission": 181.60, "last_refreshed": "2026-08-01T02:00:00"
  },
  "commission": { "percent": 10, "percent_override": "", "fixed_per_order": "", "fixed_per_product": "" },
  "referral_url": "https://example.com/affiliate-dashboard/?couponid=sarah10"
}

Draft and private coupons are addressable — a coupon does not have to be published to have an affiliate and a balance. Trashed and auto-draft coupons answer 404.

Coupon stats

[get] /wp-json/wcusage/v2/coupons/{id}/stats

Permission: admin, owner, or MLA upline. read scope; refresh=true additionally needs write.

{
  "coupon_id": 8338,
  "code": "sarah10",
  "from": null,
  "to": null,
  "source": "cache",
  "code_ambiguous": false,
  "orders_count": 19,
  "total_sales": 1977.80,
  "total_discount": 197.78,
  "total_shipping": 0,
  "total_commission": 181.60,
  "status_counts": { "Completed": 17, "Refunded": 2 },
  "last_refreshed": "2026-08-01T02:00:00",
  "unpaid_commission": 40.46,
  "pending_order_commission": 0,
  "pending_payout_commission": 0
}

The response shape is stable regardless of which path answered: status_counts and last_refreshed are always present, even when empty.

Referred orders

[get] /wp-json/wcusage/v2/coupons/{id}/orders

Permission: admin, owner, or MLA upline. read scope.

[
  {
    "order_id": 8355,
    "date": "2023-07-28T12:46:58",
    "status": "completed",
    "total": 179.80,
    "discount": 17.98,
    "commission": 16.18
  }
]

Newest first. Only orders that actually counted towards this coupon are listed — an order that used the code but was later reassigned to another affiliate is excluded, which keeps this endpoint consistent with /stats.

One request considers at most 5,000 orders (the newest ones). When that cap is hit, the response carries the header X-WCUsage-Truncated: 1, so a client can tell a capped total from a real one. Raise it with the wcusage_api_max_order_rows filter if your program needs a deeper window.

Payouts

Read payout history and create payout requests. Payouts are a PRO feature; on a build or install without them, these endpoints are absent or answer 501 wcusage_api_unavailable.

These are the highest-consequence endpoints in the API. Prove any automation on a staging store before pointing it at a live one, reconcile amounts against your payment provider rather than treating these figures as an accounting record, and keep the responsibility for verifying payments with a person. If you would rather nothing automated could ever create a payout, switch the /payouts endpoints off on the API screen — everything else keeps working.

List payouts

[get] /wp-json/wcusage/v2/payouts

Permission: any authenticated user, read scope. Non-admins are always restricted to their own payouts, whatever user_id they send.

{
  "id": 321,
  "user": { "id": 1456, "display_name": "Sarah J" },
  "coupon_id": 8338,
  "coupon_code": "sarah10",
  "amount": 40.46,
  "method": "PayPal",
  "method_type": "paypal",
  "status": "pending",
  "has_details": true,
  "transaction_id": "",
  "invoice_id": 0,
  "date": "2026-08-07T09:00:00",
  "date_paid": null
}

Get one payout

[get] /wp-json/wcusage/v2/payouts/{id}

Permission: admin or the payout's owner. read scope. Somebody else's payout answers 404.

Request a payout

[post] /wp-json/wcusage/v2/payouts

Permission: admin (any coupon), or the coupon's affiliate (their own). write scope.

curl -X POST https://example.com/wp-json/wcusage/v2/payouts \
  -H "Authorization: Bearer wcus_..." \
  -H "Content-Type: application/json" \
  -d '{"coupon_id": 8338}'

Returns 201 with the created payout, plus two extra fields:

• gateway_triggered — true when auto-accept moved the payout straight to created or paid, meaning a real gateway may have been called.
• gateway_notice — present only when a gateway handler produced a message worth passing on.

Idempotency

Only one open request can exist per coupon at a time. If one already exists (pending, created or processing), the existing payout is returned with 200 and the header X-WCUsage-Existing: 1 — so a retrying client can never create duplicates. Concurrent requests for the same coupon are serialised with a lock; the loser gets 409 wcusage_api_in_progress.

Rules that are enforced

Requests are held to the same rules as the affiliate dashboard, so the API cannot be used to route around a store's configuration:

Update payout status

[post] /wp-json/wcusage/v2/payouts/{id}/status

Permission: admin, write scope.

This runs the same status flow as the admin screen: balances move between the unpaid, pending-payout and paid pools, the activity log records the change, notification emails are sent and webhooks fire. No payment gateway is contacted.

Permitted transitions

Anything else is refused with 400 wcusage_api_invalid_transition rather than leaving the balances inconsistent. Setting the status a payout already has returns 400 wcusage_api_no_change.

Two further guards:

• Re-opening a cancelled payout takes its amount back out of the unpaid balance. If that money is no longer there — already paid out, or the balance was edited — the request is refused with 409 wcusage_api_insufficient_unpaid rather than letting the ledger drift.
• Concurrent status changes are settled by a conditional update. Only the request that actually changes the row runs the balance arithmetic; the loser gets 409 wcusage_api_conflict.

Registrations

Read and moderate affiliate applications. These endpoints read the plugin's registration table, and approval goes through the same function the admin screen calls, so the full accept flow runs identically.

List registrations

[get] /wp-json/wcusage/v2/registrations

Permission: admin, read scope.

{
  "id": 512,
  "user": { "id": 2201, "display_name": "New Affiliate", "login": "newaffiliate", "email": "new@example.com" },
  "coupon_code": "newaff15",
  "status": "pending",
  "type": "",
  "promote": "Instagram and my newsletter",
  "referrer": "",
  "website": "https://blog.example.net",
  "custom_fields": { "Audience size": "12000" },
  "date": "2026-08-05T18:22:41",
  "date_accepted": null
}

custom_fields holds whatever extra registration fields the store has configured, as a flat object. It is an empty object when there are none.

Get one registration

[get] /wp-json/wcusage/v2/registrations/{id}

Permission: admin, read scope.

Approve or decline

[post] /wp-json/wcusage/v2/registrations/{id}/status

Permission: admin, write scope.

Returns the updated registration.

Clicks

Aggregated referral-link click statistics, counted in SQL rather than loaded row by row.

[get] /wp-json/wcusage/v2/clicks/stats

Permission: admin for store-wide figures; affiliates must pass a coupon_id they own. read scope.

{
  "coupon_id": 8338,
  "campaign": null,
  "from": "2026-07-01",
  "to": "2026-07-31",
  "clicks": 412,
  "conversions": 19,
  "conversion_rate": 4.61
}

conversion_rate is a percentage rounded to two decimals, and is 0 when there were no clicks.

Events

A cursor-based change feed over the plugin's activity log. This is the polling counterpart to webhooks: ask "what happened since event X" and act on the answer. Webhooks are PRO, so on the free version this endpoint is how you keep an external system in step.

[get] /wp-json/wcusage/v2/events

Permission: admin, read scope.

[
  { "id": 9911, "event": "payout_paid", "event_id": 321, "user_id": 1, "info": "40.46", "date": "2026-08-07T10:15:00" },
  { "id": 9912, "event": "referral", "event_id": 8355, "user_id": 0, "info": "sarah10", "date": "2026-08-07T10:16:31" }
]

The response header X-WCUsage-Last-Event carries the highest event ID returned. Store it and pass it as after on the next poll:

GET /wp-json/wcusage/v2/events?after=9912&per_page=100
→ X-WCUsage-Last-Event: 9987

Event types

user_id is the acting user, and is 0 for system and guest actions such as a referral from a logged-out shopper. info is free-form context whose meaning depends on the event type.

Reports

A store-wide program summary, built for dashboards and AI assistants that need the whole picture in one call.

[get] /wp-json/wcusage/v2/reports/summary

Permission: admin, read scope.

{
  "generated": "2026-08-07T14:05:00",
  "currency": "USD",
  "totals": {
    "affiliates": 448,
    "coupons": 512,
    "orders_count": 10231,
    "total_sales": 812337.20,
    "total_discount": 79110.55,
    "total_commission": 81233.71,
    "unpaid_commission": 6120.44,
    "pending_payout_commission": 1240.00
  },
  "payouts": { "pending_count": 12, "pending_amount": 1240.00, "paid_count": 981, "paid_amount": 73873.27 },
  "pending_registrations": 7,
  "top_affiliates": [
    { "user_id": 1456, "orders_count": 19, "total_sales": 1977.80, "total_commission": 181.60,
      "user": { "id": 1456, "display_name": "Sarah J", "login": "sarahj", "email": "sarah@example.com" } }
  ],
  "cached": false
}

cached: true means the response came from the 5-minute cache. The payouts block is present only when the payouts add-on is available — the free build omits it entirely rather than reporting four zeros as though the program had simply never paid anybody.

API Key Management

Keys can be managed in the admin UI (Coupon Affiliates → Admin Tools → API) or programmatically. Every route here requires an admin with the manage scope.

List keys

[get] /wp-json/wcusage/v2/keys

Standard pagination. Returns metadata only — never tokens or hashes:

[
  {
    "id": 4,
    "user_id": 1456,
    "description": "Zapier integration",
    "key_prefix": "wcus_9f2c1e",
    "scopes": ["read"],
    "status": "active",
    "last_used": "2026-08-07T13:55:00",
    "date_created": "2026-08-01T09:12:00",
    "date_expires": null
  }
]

key_prefix is the first 12 characters of the token — enough to recognise a key in your own logs, useless as a credential.

Create a key

[post] /wp-json/wcusage/v2/keys

{
  "id": 4,
  "token": "wcus_9f2c1e4a7b3d5e6f8a9b0c1d2e3f4a5b6c7d8e9f",
  "notice": "Store this token now - it cannot be shown again.",
  "user_id": 1456
}

You may always create a key for yourself. Creating one for another user requires the capability to edit that user, so a lower-privileged manager cannot mint a key that acts as a full administrator. Otherwise the response is 403 wcusage_api_cannot_create_for_user.

Revoke a key

[delete] /wp-json/wcusage/v2/keys/{id}

{ "revoked": true }

Revocation is immediate: clients using the key receive 401 on their next request. It is idempotent — revoking an already-revoked key reports success. The same "could you edit that user" rule applies, so one plugin admin cannot destroy an administrator's integration credential.

Key creation and revocation are both recorded in the activity log (api_key_created, api_key_revoked), so they show up in /events.

Webhooks

Webhooks Overview

Webhooks push signed JSON notifications to a URL you choose, the moment something happens in your affiliate program — no polling required. Set them up under Coupon Affiliates → Admin Tools → API → Webhooks, or through the management API.

Every lifecycle event in the plugin already flows through one funnel, and the webhook dispatcher listens to it. Deliveries are queued (Action Scheduler when WooCommerce provides it, otherwise WP-Cron), so your endpoint never slows down a checkout or an admin action.

Available events

Every event below needs PRO, since webhooks themselves do. These first ones are raised by the core plugin, so they arrive on any PRO install:

These further events come from individual PRO add-ons, so they need that add-on to be active as well:

Subscribe an endpoint to specific events, or to * for everything. The live catalog for your install is always available at [get] /wp-json/wcusage/v2/webhooks/events — it lists only events this build can actually raise, so you never subscribe to a notification that could never arrive.

Endpoint requirements

• The delivery URL must be HTTPS and publicly reachable. Loopback and private-network addresses are rejected at creation. Local development environments may use HTTP — see the wcusage_api_webhook_require_https filter.
• Respond with any 2xx status within 8 seconds. Anything else counts as a failed delivery.
• Do the real work asynchronously. Acknowledge first, process afterwards.

Deliveries & Security

Payload format

Every delivery is a JSON POST with the same envelope. The data block is rebuilt from the live object at delivery time, so a retry never carries stale figures:

POST /your-endpoint HTTP/1.1
Content-Type: application/json
User-Agent: CouponAffiliates-Webhook/8.2.0
X-WCUsage-Event: payout.paid
X-WCUsage-Delivery: whd_66b4a1e2c3d4f5.12345678
X-WCUsage-Signature: t=1786457100,v1=5f8a2b...

{
  "event": "payout.paid",
  "created": "2026-08-07T14:05:00+00:00",
  "site": "https://example.com",
  "data": {
    "payout_id": 321,
    "user_id": 1456,
    "coupon_id": 8338,
    "amount": 40.46,
    "method": "PayPal",
    "method_type": "paypal",
    "status": "paid",
    "date": "2026-08-07T09:00:00",
    "date_paid": "2026-08-07T14:04:58"
  }
}

Payload shapes by event

Verifying signatures

Each webhook has a secret (whsec_…), shown in the admin UI and returned once on creation through the API. Every delivery is signed with HMAC-SHA256 over "<timestamp>.<raw body>":

X-WCUsage-Signature: t=<unix timestamp>,v1=<hex hmac>

Verify it before trusting anything in the payload:

<?php
$secret = 'whsec_your_webhook_secret';
$body   = file_get_contents( 'php://input' );
$header = $_SERVER['HTTP_X_WCUSAGE_SIGNATURE'] ?? '';

$parts = [];
foreach ( explode( ',', $header ) as $pair ) {
    [ $k, $v ] = array_pad( explode( '=', $pair, 2 ), 2, '' );
    $parts[ trim( $k ) ] = trim( $v );
}

$expected = hash_hmac( 'sha256', ( $parts['t'] ?? '' ) . '.' . $body, $secret );

if ( ! hash_equals( $expected, $parts['v1'] ?? '' ) ) {
    http_response_code( 401 );
    exit; // signature mismatch
}

if ( abs( time() - (int) ( $parts['t'] ?? 0 ) ) > 300 ) {
    http_response_code( 401 );
    exit; // replayed or stale delivery
}

http_response_code( 200 );
// then process json_decode( $body, true ) out of band

Retries and automatic disabling

• Deliveries are queued asynchronously, so your endpoint is never in the critical path of a checkout or an admin action.
• A failed delivery is retried up to 5 attempts with exponential backoff: roughly 1 minute, 4 minutes, 16 minutes, then about an hour.
• After 25 consecutive failures the endpoint is automatically disabled. Re-enable it from the admin page or with a PATCH request; either resets the failure counter and clears the last error.
• Delivery is at-least-once. Duplicates are possible, so use X-WCUsage-Delivery to deduplicate if your handler is not idempotent.
• Ordering is not guaranteed. Two events raised close together may arrive in either order, and a retried delivery may land after a newer one.
• The last failure message and the failure count are visible on the admin page and in GET /webhooks.

Tune the two limits with the wcusage_api_webhook_max_attempts and wcusage_api_webhook_max_failures filters.

Webhook Management API

All routes require an admin with the manage scope, except the event catalog, which needs read. PRO only — none of these routes are registered in the free build, so they answer 404 rest_no_route there.

List webhooks

[get] /wp-json/wcusage/v2/webhooks

[
  {
    "id": 1,
    "name": "Ops Slack relay",
    "url": "https://hooks.example.net/coupon-affiliates",
    "events": ["payout.requested", "payout.paid"],
    "status": "active",
    "failures": 0,
    "last_delivery": "2026-08-07T14:05:01",
    "last_error": "",
    "date_created": "2026-07-30T11:00:00"
  }
]

Signing secrets are not included in list responses. Full administrators can read them on the admin page; other plugin admins see them masked.

Create a webhook

[post] /wp-json/wcusage/v2/webhooks

Returns 201 including the signing secret. Store it — it is the only way to verify deliveries, and this is the only response that carries it.

Update a webhook

[patch] /wp-json/wcusage/v2/webhooks/{id}

Sending neither returns 400 wcusage_api_no_fields.

Test a webhook

[post] /wp-json/wcusage/v2/webhooks/{id}/test

Sends a signed ping delivery immediately and synchronously, and returns the HTTP status your endpoint answered with:

{ "code": 200 }

A transport-level failure (DNS, TLS, timeout) returns 502 wcusage_api_delivery_failed with the underlying message. Test deliveries do not count towards the failure counter.

Delete a webhook

[delete] /wp-json/wcusage/v2/webhooks/{id}

{ "deleted": true }

Event catalog

[get] /wp-json/wcusage/v2/webhooks/events

Permission: admin, read scope.

[
  { "event": "referral.created", "description": "A referred order was attributed to an affiliate." },
  { "event": "payout.paid", "description": "A payout was marked as paid." }
]

Read this rather than hard-coding the list: it reflects exactly which add-ons are active on the install.

Integrations

Code Samples

Nothing here needs a client library — the API is plain HTTP with a bearer token. These are complete, working starting points.

PHP (inside WordPress)

Talking to another store from a WordPress site, using the HTTP API that is already loaded:

$response = wp_remote_get(
    'https://example.com/wp-json/wcusage/v2/reports/summary?top=5',
    array(
        'timeout' => 15,
        'headers' => array(
            'Authorization' => 'Bearer ' . WCUSAGE_API_KEY,
            'Accept'        => 'application/json',
        ),
    )
);

if ( is_wp_error( $response ) ) {
    error_log( 'Coupon Affiliates API unreachable: ' . $response->get_error_message() );
    return;
}

$code = wp_remote_retrieve_response_code( $response );
$body = json_decode( wp_remote_retrieve_body( $response ), true );

if ( 200 !== $code ) {
    // Every plugin error carries a machine-readable code.
    error_log( 'API error ' . $code . ': ' . ( $body['code'] ?? 'unknown' ) );
    return;
}

printf( 'Unpaid commission: %s %.2f', $body['currency'], $body['totals']['unpaid_commission'] );

PHP (standalone, with pagination)

Walking a collection to the end, using the pagination headers rather than guessing:

<?php
function wcu_api_get( $path, $params = [] ) {
    $url = 'https://example.com/wp-json/wcusage/v2' . $path;
    if ( $params ) {
        $url .= '?' . http_build_query( $params );
    }

    $ch = curl_init( $url );
    curl_setopt_array( $ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADER         => true,
        CURLOPT_HTTPHEADER     => [ 'Authorization: Bearer ' . getenv( 'WCUSAGE_KEY' ) ],
        CURLOPT_TIMEOUT        => 20,
    ] );

    $raw         = curl_exec( $ch );
    $status      = curl_getinfo( $ch, CURLINFO_RESPONSE_CODE );
    $header_size = curl_getinfo( $ch, CURLINFO_HEADER_SIZE );
    curl_close( $ch );

    $headers = substr( $raw, 0, $header_size );
    $body    = json_decode( substr( $raw, $header_size ), true );

    $pages = 1;
    if ( preg_match( '/^X-WP-TotalPages:\s*(\d+)/mi', $headers, $m ) ) {
        $pages = (int) $m[1];
    }

    return [ 'status' => $status, 'body' => $body, 'pages' => $pages ];
}

$page = 1;
do {
    $result = wcu_api_get( '/affiliates', [ 'page' => $page, 'per_page' => 100 ] );

    if ( 200 !== $result['status'] ) {
        throw new RuntimeException( 'API error: ' . ( $result['body']['code'] ?? $result['status'] ) );
    }

    foreach ( $result['body'] as $affiliate ) {
        printf( "%-30s %8.2f unpaid\n",
            $affiliate['user']['display_name'],
            $affiliate['unpaid_commission']
        );
    }

    $page++;
} while ( $page <= $result['pages'] );

JavaScript / Node

Including the one piece of error handling that matters most in practice — honouring retry_after:

const BASE = 'https://example.com/wp-json/wcusage/v2';
const KEY  = process.env.WCUSAGE_KEY;

async function api( path, params = {} ) {
  const url = new URL( BASE + path );
  Object.entries( params ).forEach( ( [ k, v ] ) => url.searchParams.set( k, v ) );

  const res  = await fetch( url, { headers: { Authorization: `Bearer ${KEY}` } } );
  const body = await res.json();

  if ( res.status === 429 ) {
    const wait = ( body?.data?.retry_after ?? 60 ) * 1000;
    await new Promise( r => setTimeout( r, wait ) );
    return api( path, params );           // one retry after the window
  }

  if ( ! res.ok ) {
    throw new Error( `${body.code}: ${body.message}` );
  }

  return { body, total: Number( res.headers.get( 'X-WP-Total' ) || 0 ) };
}

const { body: me } = await api( '/me' );
console.log( `Authenticated as ${me.user.display_name}, admin: ${me.is_admin}, scopes:`, me.auth.scopes );

Python

import os, requests

BASE = "https://example.com/wp-json/wcusage/v2"
SESSION = requests.Session()
SESSION.headers["Authorization"] = f"Bearer {os.environ['WCUSAGE_KEY']}"

def get(path, **params):
    r = SESSION.get(f"{BASE}{path}", params=params, timeout=20)
    if r.status_code != 200:
        raise RuntimeError(f"{r.status_code} {r.json().get('code', '')}")
    return r

# All referred orders for one coupon last month, newest first.
page, orders = 1, []
while True:
    r = get("/coupons/8338/orders", **{"from": "2026-07-01", "to": "2026-07-31",
                                       "page": page, "per_page": 100})
    orders += r.json()
    if r.headers.get("X-WCUsage-Truncated") == "1":
        print("Warning: order window was capped; narrow the date range.")
    if page >= int(r.headers.get("X-WP-TotalPages", 1)):
        break
    page += 1

print(f"{len(orders)} orders, {sum(o['commission'] for o in orders):.2f} commission")

Command line

# Quick health check
curl -s https://example.com/wp-json/wcusage/v2/me \
  -H "Authorization: Bearer $WCUSAGE_KEY" | jq

# Top 5 affiliates by all-time commission
curl -s "https://example.com/wp-json/wcusage/v2/reports/summary?top=5" \
  -H "Authorization: Bearer $WCUSAGE_KEY" \
  | jq -r '.top_affiliates[] | "\(.user.display_name)\t\(.total_commission)"'

# Anything that needs paying out
curl -s "https://example.com/wp-json/wcusage/v2/payouts?status=pending&per_page=100" \
  -H "Authorization: Bearer $WCUSAGE_KEY" \
  | jq -r '.[] | "#\(.id)\t\(.user.display_name)\t\(.amount)\t\(.method)"'

No-Code Platforms

Zapier, Make, n8n, Pabbly Connect, Activepieces and similar tools all speak plain HTTP, so no special connector is needed. There are two ways to wire them up.

Push: webhook trigger (recommended, PRO)

1. In your automation tool, create a scenario starting with a Webhook / Catch Hook trigger and copy the URL it gives you.
2. In WordPress, go to Coupon Affiliates → Admin Tools → API → Webhooks and add an endpoint with that URL, subscribed to the events you care about.
3. Press Test. Your tool receives a ping payload and learns the structure.
4. Map the fields from data into whatever comes next — a Slack message, a spreadsheet row, a CRM record.

This is instant, costs no polling quota, and scales to any program size.

Pull: scheduled polling

If you are on the free version, or your tool cannot receive webhooks, poll the change feed on a schedule instead:

1. Add a Scheduled trigger (every 5–15 minutes is plenty).
2. Add an HTTP GET module pointed at https://example.com/wp-json/wcusage/v2/events with the query after={{ last_id }}&per_page=100, and a header Authorization: Bearer wcus_….
3. Store the response header X-WCUsage-Last-Event in a data store / variable, and feed it back as last_id next run.
4. Iterate the returned array and branch on event.

Starting from after=0 would replay the whole history, so seed the cursor once with a single unfiltered call and store the highest id you see.

Writing back

Actions such as approving an application are ordinary HTTP requests:

Method:  POST
URL:     https://example.com/wp-json/wcusage/v2/registrations/512/status
Headers: Authorization: Bearer wcus_...
         Content-Type: application/json
Body:    { "status": "accepted", "send_email": true }

Use a key with write for this, and keep it separate from any read-only key you use elsewhere so you can revoke one without breaking the other.

Reporting & Dashboards

Google Sheets

An Apps Script bound to a sheet, refreshing a leaderboard on a timer:

function refreshAffiliates() {
  const key   = PropertiesService.getScriptProperties().getProperty( 'WCUSAGE_KEY' );
  const url   = 'https://example.com/wp-json/wcusage/v2/reports/summary?top=50';
  const res   = UrlFetchApp.fetch( url, {
    headers: { Authorization: 'Bearer ' + key },
    muteHttpExceptions: true
  } );

  if ( res.getResponseCode() !== 200 ) {
    throw new Error( res.getContentText() );
  }

  const data  = JSON.parse( res.getContentText() );
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName( 'Affiliates' );

  sheet.clear();
  sheet.appendRow( [ 'Affiliate', 'Orders', 'Sales', 'Commission' ] );
  data.top_affiliates.forEach( function ( a ) {
    sheet.appendRow( [ a.user.display_name, a.orders_count, a.total_sales, a.total_commission ] );
  } );

  sheet.getRange( 'A1:D1' ).setFontWeight( 'bold' );
}

Add a time-driven trigger for refreshAffiliates and store the key under Project Settings → Script Properties, not in the code.

Looker Studio, Power BI, Metabase

All three can read a JSON/REST source with a bearer header. Point them at:

• /reports/summary?top=50 for the program overview — one row of totals plus a leaderboard, already aggregated and cached for five minutes.
• /affiliates?per_page=100 for a per-affiliate table, walking pages with X-WP-TotalPages.
• /coupons/{id}/orders?from=&to= for transaction-level detail, one coupon at a time.

Warehousing the data

For an incremental ETL, drive it from /events rather than re-reading collections. Store the last event ID alongside your data, pull only what is new, and reconcile occasionally with a full pass over /affiliates. That keeps a nightly job to a handful of requests regardless of program size.

Notifications

A small receiver that verifies the signature and relays events into Slack. The same shape works for Discord, Teams, Telegram or an SMS gateway — only the last few lines change.

<?php
// webhook-receiver.php
$secret = getenv( 'WCUSAGE_WEBHOOK_SECRET' );
$body   = file_get_contents( 'php://input' );
$header = $_SERVER['HTTP_X_WCUSAGE_SIGNATURE'] ?? '';

$parts = [];
foreach ( explode( ',', $header ) as $pair ) {
    [ $k, $v ] = array_pad( explode( '=', $pair, 2 ), 2, '' );
    $parts[ trim( $k ) ] = trim( $v );
}

$expected = hash_hmac( 'sha256', ( $parts['t'] ?? '' ) . '.' . $body, $secret );

if ( ! hash_equals( $expected, $parts['v1'] ?? '' ) || abs( time() - (int) ( $parts['t'] ?? 0 ) ) > 300 ) {
    http_response_code( 401 );
    exit;
}

// Acknowledge immediately - the sender allows 8 seconds and retries on anything else.
http_response_code( 200 );
fastcgi_finish_request();

$payload = json_decode( $body, true );
$data    = $payload['data'] ?? [];

switch ( $payload['event'] ) {
    case 'payout.requested':
        $text = sprintf( ':moneybag: Payout requested: %s asked for %.2f via %s (payout #%d)',
            get_display_name( $data['user_id'] ), $data['amount'], $data['method'], $data['payout_id'] );
        break;

    case 'registration.created':
        $text = sprintf( ':wave: New affiliate application for code *%s*', $data['coupon_code'] );
        break;

    case 'affiliate.payout_details_updated':
        $text = sprintf( ':warning: Affiliate %d changed their payout details (%s)',
            $data['user_id'], $data['method_type'] ?: 'none set' );
        break;

    default:
        return; // not interested
}

$ch = curl_init( getenv( 'SLACK_WEBHOOK_URL' ) );
curl_setopt_array( $ch, [
    CURLOPT_POST       => true,
    CURLOPT_HTTPHEADER => [ 'Content-Type: application/json' ],
    CURLOPT_POSTFIELDS => json_encode( [ 'text' => $text ] ),
    CURLOPT_RETURNTRANSFER => true,
] );
curl_exec( $ch );

Two details worth copying:

• Acknowledge before working. fastcgi_finish_request() (or a queue) returns the 2xx immediately, so a slow Slack call never turns into a retry storm.
• Ignore unknown events. New event types appear in later releases; a receiver that throws on them will disable itself after 25 failures.

AI Agents & Assistants

The API was designed with agents in mind: stable numeric IDs, plain JSON, self-describing errors, a machine-readable spec and a single "who am I" call.

Setting one up

1. Create a WordPress user for the agent, at the access level it genuinely needs — an affiliate account for an affiliate-facing assistant, an admin account only for a program-management assistant.
2. Create an API key against that user with the read scope only, and an expiry date.
3. Give the tool the OpenAPI URL: https://example.com/wp-json/wcusage/v2/openapi. Custom GPT Actions, most agent frameworks and any OpenAPI-aware tool builder import it directly, generating one callable function per endpoint.
4. Configure bearer authentication with the key.

For frameworks without OpenAPI import, hand-define a handful of tools instead — /me, /reports/summary, /affiliates/{id}/stats, /coupons/{id}/orders and /events cover the overwhelming majority of questions.

Prompting notes

• Tell the agent to call /me first. It learns whether it is an admin or a single affiliate, and which scopes it holds, instead of guessing and hitting 403s.
• Tell it to reference coupons by ID, not code.
• Tell it that 404 can mean "not yours", so it should not conclude an ID is unused.
• Tell it to respect retry_after on 429 rather than retrying immediately — otherwise a loop burns the whole rate limit.
• Point it at /reports/summary for "how are we doing" questions. Left to itself an agent will happily page through every affiliate to compute a total the API already has.

Safety

An agent acts on the text it reads, and some of that text comes from outside your control — an applicant's "how will you promote us" answer, a campaign name, a website URL an affiliate typed in. An agent with write access can be steered by content like that into doing something you never asked for. Read-only access removes the problem entirely; anything more needs a person in the loop on the actions that matter.

If an agent must act, grant write deliberately and remember what it can then do: approve or decline applications, create payout requests, and change payout statuses. Payout status changes never contact a gateway, but on a store with automatic payouts a created payout request can pay real money immediately. If that is a concern, switch the /payouts endpoints off on the API screen and let the agent read everything else.

Recipes

Sync new referrals into another system

Poll the change feed and keep a cursor — one indexed query per poll, no matter how busy the program is:

curl -s "https://example.com/wp-json/wcusage/v2/events?after=9912&event=referral&per_page=100" \
  -H "Authorization: Bearer $WCUSAGE_KEY" -D headers.txt

# the new cursor for next time
grep -i '^X-WCUsage-Last-Event' headers.txt

On PRO, subscribe a webhook to referral.created and skip the polling entirely.

Build a monthly affiliate statement

# totals for the month
GET /wp-json/wcusage/v2/affiliates/1456/stats?from=2026-07-01&to=2026-07-31

# the orders behind them, one coupon at a time
GET /wp-json/wcusage/v2/coupons/8338/orders?from=2026-07-01&to=2026-07-31&per_page=100

Keep the range fixed between calls so both are served from cache rather than rescanned.

Auto-approve applications that meet your criteria

# 1. find pending applications
GET /wp-json/wcusage/v2/registrations?status=pending&per_page=100

# 2. approve the ones that qualify
POST /wp-json/wcusage/v2/registrations/512/status
{ "status": "accepted", "message": "Welcome aboard!", "send_email": true }

Needs an admin key with write. Remember that accepting is one-way through the API, so apply your criteria before calling, not after.

Give an affiliate read-only API access to their own data

POST /wp-json/wcusage/v2/keys
{ "user_id": 1456, "description": "Sarah's reporting script", "scopes": ["read"], "expires": "2027-01-01" }

The resulting key can call /me, /affiliates/1456/stats, its own coupons, their orders and click stats, and /payouts filtered to itself — and nothing else. Creating it requires manage plus the capability to edit that user.

Reconcile payouts with your accounting system

# everything paid in a period
GET /wp-json/wcusage/v2/payouts?status=paid&from=2026-07-01&to=2026-07-31&per_page=100

Match on transaction_id where your gateway provides one, and on id otherwise. date is when the payout was requested and date_paid when it was settled — use the latter for period allocation.

Flag a payout-fraud pattern

Subscribe a webhook to affiliate.payout_details_updated and payout.requested. When both arrive for the same user_id within a short window, hold the payout for manual review:

POST /wp-json/wcusage/v2/payouts/321/status
{ "status": "cancel" }

Cancelling returns the amount to the affiliate's unpaid balance, so nothing is lost; re-open it with pending once you are satisfied.

Refresh stale coupon statistics nightly

GET /wp-json/wcusage/v2/coupons/8338/stats?refresh=true

Rebuilds the stored snapshot from the order history and saves it, so the affiliate's dashboard and every later API read are current. Needs the write scope, and is limited to one rebuild per coupon per minute — space the calls out, and treat source: "throttled" as "try this one again later".

Check the health of your integration

GET /wp-json/wcusage/v2/me            # what am I, and what may I do?
GET /wp-json/wcusage/v2/webhooks      # failures, last_error, last_delivery
GET /wp-json/wcusage/v2/keys          # last_used, status, date_expires

A webhook with a rising failures count, or a key whose last_used has gone stale, is usually the first sign that something upstream broke.

Developer Reference

OpenAPI Document

Fetching the spec

[get] /wp-json/wcusage/v2/openapi

Returns an OpenAPI 3.1 document generated live from the registered routes — every path, parameter, enum, default and required flag, plus both security schemes (bearer API key and Basic application password). Because it is generated from the actual route definitions, it never drifts from the implementation, and it automatically reflects which endpoints you have switched off and which add-ons are active.

The document is public by default, since the WordPress REST index already enumerates routes. Restrict it to admins with:

add_filter( 'wcusage_api_openapi_public', '__return_false' );

Amend the generated spec — to add descriptions, tags or examples — with the wcusage_api_openapi_spec filter.

What it contains

{
  "openapi": "3.1.0",
  "info": {
    "title": "Coupon Affiliates REST API",
    "description": "Affiliate data for WooCommerce: affiliates, coupons, referred orders, commission, payouts, registrations, clicks, events and reports.",
    "version": "8.2.0"
  },
  "servers": [ { "url": "https://example.com/wp-json/wcusage/v2" } ],
  "paths": {
    "/coupons/{id}/stats": {
      "get": {
        "operationId": "get_coupons_id_stats",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } },
          { "name": "from", "in": "query", "required": false, "schema": { "type": "string" } },
          { "name": "refresh", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }
        ],
        "security": [ { "bearerApiKey": [] }, { "basicAppPassword": [] } ],
        "responses": { "200": { "description": "Success." }, "401": { "description": "Authentication required or invalid." }, "403": { "description": "Insufficient permissions or scope." } }
      }
    }
  },
  "components": { "securitySchemes": { "bearerApiKey": { "type": "http", "scheme": "bearer" }, "basicAppPassword": { "type": "http", "scheme": "basic" } } }
}

Path parameters, query parameters and JSON request bodies are all derived from the routes' own argument definitions, including types, enums, defaults and required flags. Because the document is built per request, it reflects exactly what this install exposes: endpoints switched off in the settings are absent, and so are routes belonging to add-ons that are not active.

Using it is covered under AI Agents & Assistants and No-Code Platforms — most tools that accept an OpenAPI URL will generate a working client from it directly.

Availability

Not every endpoint exists on every install. Three things decide it: the plugin edition, which add-ons are active, and which endpoints an administrator has switched on.

MLA-related access (an upline reading a downline's coupon) and the add-on webhook events likewise exist only where those add-ons do. The safest way to discover what a given install offers is to read /openapi and /webhooks/events rather than assuming.

Error Reference

All codes are prefixed wcusage_api_ in the response. Core WordPress codes such as rest_no_route, rest_invalid_param and rest_missing_callback_param can also appear.

Hooks & Filters

Behaviour filters

Enabling the API, and enabling individual endpoints, is done from Coupon Affiliates → Admin Tools → API rather than by a filter. Those settings live in the wcusage_api_settings option.

Response filters

// Add the affiliate's country to every coupon the API returns.
add_filter( 'wcusage_api_coupon_summary', function ( $data, $coupon_id ) {
    $user_id = (int) $data['user_id'];
    $data['country'] = $user_id ? get_user_meta( $user_id, 'billing_country', true ) : '';
    return $data;
}, 10, 2 );

Actions

add_action( 'wcusage_activity_recorded', function ( $event, $event_id, $info, $actor_id ) {
    if ( 'payout_request' === $event ) {
        // $event_id is the payout ID.
    }
}, 10, 4 );

Legacy v1 API

The original three endpoints under woo-coupon-usage/v1 remain available for backwards compatibility. They predate scopes, pagination and schemas, and they require a full administrator account — not merely the plugin's configurable admin capability.

[get] /wp-json/woo-coupon-usage/v1/coupon-info?coupon_id={id}

{
  "coupon_name": "sarah10",
  "unpaid_commission": 40.46,
  "pending_payouts": 0,
  "coupon_user_id": 1456,
  "referral_url": "https://example.com/affiliate-dashboard/?couponid=sarah10"
}

[get] /wp-json/woo-coupon-usage/v1/users-coupons?user={login} — an array of coupon IDs assigned to that login. An unknown login returns an empty array.

[post] /wp-json/woo-coupon-usage/v1/request-payout — body coupon_id and user (login). Returns 1 when a payout request was submitted and 0 otherwise, with no explanation of why. PRO only.

How v1 relates to v2

• The v1 routes are not affected by the API master switch, so existing integrations keep working whether or not v2 is enabled.
• API keys, however, belong to v2: while the API is switched off they authenticate nothing at all, v1 included. v1 remains reachable with an application password or cookie.
• When a key is used on v1, scopes are enforced with a fail-closed default: reads need read, writes need write.
• Both namespaces share the same rate limiter.