Headless Development

A headless Siren install runs the Siren plugin on WordPress, but the user-facing frontend lives somewhere else. That frontend can be Astro, Next.js, Remix, a custom React app, a Shopify storefront, or anything else that talks to WordPress over HTTP. Siren still owns affiliate logic, attribution, programs, and payouts. The frontend owns the customer experience.

This section is a developer’s guide for the patterns that come up when you build that way. The endpoints are the same ones a WordPress-rendered site uses. What changes is that your frontend code is the caller.

Vocabulary

Opportunity, conversion, engagement, alias, program. If those terms aren’t already familiar, Vocabulary Translation is the right starting point. It maps Siren’s vocabulary to the terms used in other affiliate platforms and to non-affiliate use cases like LMS, marketplace, and SaaS.

When this section applies

Headless integrations come in two shapes. Each task page below calls out which one applies.

Hybrid is when a headless frontend sits in front of a WordPress install that still runs WooCommerce, EDD, Gravity Forms, or another commerce or forms plugin. Transactions and form submissions still happen server-side through those plugins. The only thing you build on the frontend is referral tracking.

Fully headless is when checkout, form submission, or data capture moves into your frontend or an external system. There’s no WordPress commerce extension carrying the weight. The patterns get more involved, because Siren’s hooks live inside those extensions and you’re now operating outside them.

Tier requirement

Headless integration depends on the event ingestion endpoints, which require Essentials or above. Lite installs cannot serve as a backend for a headless frontend.

Cross-origin requests

Browser-side calls into Siren are subject to CORS when your frontend is on a different origin from the WordPress install. Siren’s response interceptor sets Access-Control-Expose-Headers: X-Siren-OID automatically so JavaScript can read the opportunity ID across origins. Access-Control-Allow-Origin is left to WordPress.

If you don’t already have a CORS policy in place, the simplest setup is a mu-plugin that hooks rest_pre_serve_request. Scope it to Siren’s namespace so it doesn’t leak permissions to the rest of the WordPress REST API:

add_action('rest_pre_serve_request', function ($value) {
    if (strpos($_SERVER['REQUEST_URI'] ?? '', '/wp-json/siren/v1/') === false) {
        return $value;
    }
    header('Access-Control-Allow-Origin: https://your-frontend.example');
    header('Access-Control-Allow-Methods: GET, POST, OPTIONS');
    header('Access-Control-Allow-Headers: Content-Type, X-Siren-OID, Authorization');
    return $value;
});

Two things to avoid. Don’t set Access-Control-Allow-Origin: *. It weakens defenses against any future endpoint that depends on the browser origin. And don’t pair a permissive origin with Access-Control-Allow-Credentials: true, because the combination opens credentialed cross-origin requests from any site. A reverse-proxy header or a CORS plugin works equally well as the mu-plugin route, but the same scoping and *-avoidance rules apply.

Authentication

Siren defers to WordPress’s own REST authentication chain. Two patterns cover everything in this section.

Admin endpoints are called from server-side runtimes using WordPress application passwords. The admin endpoints in this section are the JWT mint endpoint (collaborator-applications page) and the conversions create endpoint (coupons page). Server-side runtimes means Astro server functions, Next.js route handlers, or serverless functions. Treat the password as a server-side secret.

Public endpoints, including the event ingestion endpoint and the collaborator submission endpoint, accept unauthenticated requests. Their protection comes from elsewhere. The collaborator submission endpoint is gated by the signed JWT covered on its own page. The event endpoints rely on whatever rate-limiting and bot-protection layers the install runs in front of them. Siren’s plugin ships extension points (EventIngestionAuthMiddleware, EventIngestionRateLimitMiddleware) for installers who want to tighten that.

What’s in this section

• Attribution. Track a referred visit and persist the opportunity ID across page loads, then send it back at conversion time. The first thing you build for any headless setup.
• Coupons. Make sure coupon-based attribution still works when checkout doesn’t render through WordPress. Mostly a matter of letting the WordPress commerce plugin do its job, with a note on what’s harder if you went fully headless on commerce too.
• Collaborator applications. Let people apply to become collaborators from a form on your headless frontend. Either ride your forms plugin’s existing integration or use Siren’s signed JWT flow directly.