Resource Reference Introduction

This section documents every resource in Siren and how to access it. Each resource page covers the data model, status lifecycle, and relationships in one place, with code examples showing both the REST API and the PHP data layer side by side. Individual REST endpoint pages provide detailed HTTP request and response formats.

REST API

Authentication

On WordPress, the API uses WordPress’s built-in authentication. Requests made through the WordPress admin (via the REST API nonce) are authenticated automatically. All endpoints require authentication unless otherwise noted. Unauthenticated requests receive a 401 response.

Base URL

All Siren endpoints are registered under the siren/v1 namespace using the WordPress REST API. The full URL pattern is:

https://your-site.com/wp-json/siren/v1/{endpoint}

If your site uses a custom REST API prefix or has pretty permalinks disabled, adjust accordingly. The examples throughout this reference use the short form (GET /siren/v1/programs) without the site URL prefix.

Response format

Single-resource endpoints (get by ID, create, update) return the resource object directly as JSON with a 200 or 201 status code.

List endpoints return a JSON array with an x-siren-estimated-count response header for total count estimation. See Pagination, Filtering & Field Selection for the full pagination, sorting, and filtering system.

Errors return a JSON object with a message field and an appropriate HTTP status code. Simple errors include just the message:

{
  "message": "The requested resource could not be found."
}

Validation errors (status 400) include a context object with a failedValidations map. Each key is the field that failed, and the value is an array of error messages for that field. Multiple fields can fail at once, and a single field can have multiple validation errors:

{
  "message": "Validations failed.",
  "context": {
    "type": "VALIDATION_FAILED",
    "failedValidations": {
      "collaboratorId": ["This field is required."],
      "value": ["This field is required.", "Expected type: integer."],
      "status": ["Expected value to be one of: pending, fulfilled, cancelled."]
    }
  }
}

REST conventions

Field selection. Most list and detail endpoints require a fields query parameter specifying which fields to include in the response. This keeps responses lean and avoids expensive joins for fields you don’t need. Some fields are “extended” and only resolved when explicitly requested. Each resource’s documentation lists its available fields.

Filtering and search. List endpoints support filtering by resource-specific columns (like status or type) and text search via the s parameter. Filters use exact match by default. Passing comma-separated values creates an IN clause. See the pagination and filtering guide for details.

Two-stage deletion. Resources that support deletion use a two-stage pattern. The first DELETE request sets the resource status to deleted (a soft delete). A second DELETE request on an already-deleted resource performs a permanent hard delete. This gives you a window to recover accidentally deleted records.

Bulk actions. Several resources support bulk operations via a POST /siren/v1/{resource}/bulk endpoint. Bulk requests accept an action field and an ids array. Each resource’s documentation lists its supported bulk actions.

Owner scoping. Some endpoints (like obligations and reporting) automatically filter results based on the authenticated user’s role. Admin users see all records. Collaborator users only see records associated with their own collaborator ID. This scoping is transparent — the same endpoint serves both roles with different result sets.

Collaborator alias resolution. Several endpoints accept a collaboratorId parameter. Instead of passing a numeric ID, you can pass an alias reference in the format type:code — for example, tracking:JNE or coupon:SAVE20. The middleware resolves the alias to the collaborator’s numeric ID before the request is processed.

PHP data layer

When to access data directly

Siren is built on an event-driven architecture. Most records in the system are created as side effects of the normal event flow — a sale triggers a transaction, which triggers a conversion, which triggers an obligation. You should not manually create these records unless you have a specific reason to bypass the normal pipeline.

The most common reasons to access datastores directly are reading data for display or reporting, looking up records to make decisions in custom logic, and building migration scripts that import data from other systems. If you find yourself creating transactions, conversions, or obligations manually, consider whether firing the appropriate domain event would be more correct.

Accessing a datastore

There are two ways to access any datastore: dependency injection (for extensions and any code running inside Siren’s container) and facades (for external code like theme functions or standalone scripts).

use Siren\Programs\Core\Datastores\Program\Interfaces\ProgramDatastore;

class MyService
{
    protected ProgramDatastore $programs;

    public function __construct(ProgramDatastore $programs)
    {
        $this->programs = $programs;
    }

    public function getActivePrograms(): array
    {
        return $this->programs->where([
            ['type' => 'AND', 'clauses' => [
                ['column' => 'status', 'operator' => '=', 'value' => 'active']
            ]]
        ]);
    }
}

use Siren\Programs\Core\Facades\Programs;

$activePrograms = Programs::andWhere([
    ['column' => 'status', 'operator' => '=', 'value' => 'active']
]);

$program = Programs::getById(42);

Dependency injection is the preferred approach for extension code because it makes dependencies explicit and testable. Facades are convenient for one-off scripts, theme functions, or any code running outside Siren’s initializer pipeline. If you find yourself using a facade inside extension code, that usually means the class isn’t properly wired through the initializer system.

Standard datastore methods

Siren’s datastores are built on PHPNomad’s datastore system. The two methods you’ll use most often are getById() for fetching a single record by primary key and andWhere() for querying records with filter conditions. Both return model instances.

// Fetch a single program by ID. Throws RecordNotFoundException if missing.
$program = $programs->getById(42);

// Query with filter conditions. Returns an array of models.
$active = $programs->andWhere([
    ['column' => 'status', 'operator' => '=', 'value' => 'active']
]);

For writes, create() accepts an associative array of attributes and returns the new model. update() takes a primary key and an array of changed attributes. delete() removes a record by primary key.

Filters use structured arrays with column, operator, and value keys. Supported operators are =, !=, >, <, >=, <=, LIKE, NOT LIKE, IN, and NOT IN. You can pass multiple clauses to andWhere() and they combine with AND logic.

// Multiple conditions
$filtered = $programs->andWhere([
    ['column' => 'status', 'operator' => '=', 'value' => 'active'],
    ['column' => 'incentiveType', 'operator' => '=', 'value' => 'saleTransactionPercentage']
]);

// IN clause
$specific = $programs->andWhere([
    ['column' => 'id', 'operator' => 'IN', 'value' => [1, 2, 3]]
]);

Counting works with count() and countAndWhere(), which accept the same filter formats but return an integer instead of model arrays.

Some datastores have additional domain-specific methods documented on their individual resource pages.

Resources

Each page in this section covers one resource, including the data model, access patterns (REST and PHP), and relationships to other resources. The resources follow the data flow through Siren’s attribution pipeline:

Programs define the incentive rules. Program groups bundle related programs so only one fires per conversion. Collaborators are the affiliates, partners, or participants who earn rewards.

When a customer interacts with a collaborator’s referral link or coupon, Siren creates opportunities to track the visitor and engagements to record confirmed attribution. If that customer completes a tracked action, a conversion is created linking the engagement to a transaction.

Approved conversions generate obligations. When it’s time to pay, obligations are grouped into fulfillments and payouts.

For scheduled reward systems based on aggregate metrics, distributors and distributions handle the configuration and execution.

Supporting resources include aliases for tracking codes and coupon codes, mappings for bridging Siren IDs with external platform IDs, and configs for the key-value configuration system. The enums and constants reference lists the string identifiers used throughout the system. The reporting endpoint provides aggregated analytics.

For a complete list of all REST endpoints, see the All REST Endpoints reference.