Distributors

A distributor defines how earned rewards are calculated and paid out to collaborators. Each distributor specifies an incentive resolver (the formula for computing reward amounts), a pool resolver (the source of funds), a unit of measurement (typically a currency), and an optional schedule that controls when distributions are processed. Distributors are the configuration backbone of the distribution pipeline: programs reference distributors to determine what collaborators receive when conversions are approved.

The distribution system runs on a heartbeat. On each tick, Siren checks whether any distributions have reached their trigger date, allocates rewards from the pool to qualifying collaborators, and creates obligations. This is a fundamentally different flow from the per-transaction attribution pipeline.

The distributor object

Status lifecycle

Accessing distributor data

# List active distributors
curl -X GET "https://your-site.com/wp-json/siren/v1/distributors?status=active&fields=id,name,status,units" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get a single distributor with extended fields
curl -X GET "https://your-site.com/wp-json/siren/v1/distributors/3?fields=id,name,status,collaboratorCount" \
  -H "Authorization: Bearer YOUR_TOKEN"

use Siren\Distributions\Core\Datastores\Distributor\Interfaces\DistributorDatastore;

class DistributorReport
{
    protected DistributorDatastore $distributors;

    public function __construct(DistributorDatastore $distributors)
    {
        $this->distributors = $distributors;
    }

    public function getActiveDistributors(): array
    {
        return $this->distributors->andWhere([
            ['column' => 'status', 'operator' => '=', 'value' => 'active']
        ]);
    }
}

use Siren\Distributions\Core\Facades\Distributors;

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

$distributor = Distributors::getById(3);

Siren is built on an event-driven architecture. Distributions are created and completed automatically by the heartbeat and allocation pipeline. The events distribution_completed and allocation_completed drive the downstream obligation creation. If you’re reading these datastores, you’re most likely building reporting or dashboards. If you find yourself creating distributions manually, you’re probably working against the heartbeat system rather than with it.

PHP domain methods

Looking up a collaborator’s distributors

getCollaboratorDistributors retrieves all distributors a specific collaborator participates in, with pagination support.

use Siren\Distributions\Core\Datastores\Distributor\Interfaces\DistributorDatastore;

class CollaboratorDashboard
{
    protected DistributorDatastore $distributors;

    public function __construct(DistributorDatastore $distributors)
    {
        $this->distributors = $distributors;
    }

    public function listDistributors(int $collaboratorId): array
    {
        // Defaults to 10 results starting at offset 0
        return $this->distributors->getCollaboratorDistributors($collaboratorId);
    }

    public function listAllDistributors(int $collaboratorId): array
    {
        return $this->distributors->getCollaboratorDistributors($collaboratorId, 50, 0);
    }
}

use Siren\Distributions\Core\Facades\Distributors;

$distributors = Distributors::getCollaboratorDistributors($collaboratorId);

// With pagination
$distributors = Distributors::getCollaboratorDistributors($collaboratorId, 25, 0);

Counting collaborators in a distributor

getCollaboratorCount returns the estimated number of collaborators enrolled in a given distributor. This method is available on the datastore interface through dependency injection.

$count = $this->distributors->getCollaboratorCount($distributorId);

Extended fields (REST only)

Via ?fields=

Specialized fields (single-record only)

These fields are always included in the single-record response (GET /siren/v1/distributors/{id}) and are not part of the field resolver system:

Metric types

Metric types define which performance indicators a distributor tracks and how they’re weighted. Each metric type record links a distributor to a specific metric identifier and its current accumulated value.

The metric type model

Accessing metric type data

use Siren\Distributions\Core\Datastores\DistributorMetricTypes\Interfaces\DistributorMetricTypeDatastore;

class MetricInspector
{
    protected DistributorMetricTypeDatastore $metricTypes;

    public function __construct(DistributorMetricTypeDatastore $metricTypes)
    {
        $this->metricTypes = $metricTypes;
    }

    public function getAllMetrics(int $distributorId): array
    {
        return $this->metricTypes->getDistributorMetricTypes($distributorId);
    }
}

use Siren\Distributions\Core\Facades\DistributorMetricTypes;

$metrics = DistributorMetricTypes::getDistributorMetricTypes($distributorId);

foreach ($metrics as $metric) {
    echo $metric->getMetricType() . ': ' . $metric->getMetricValue();
}

Metric type domain methods

getMetricTypeForDistributor retrieves a single metric type record by distributor ID and metric type identifier. Throws RecordNotFoundException if the distributor doesn’t have the specified metric configured.

use Siren\Distributions\Core\Facades\DistributorMetricTypes;

$salesMetric = DistributorMetricTypes::getMetricTypeForDistributor($distributorId, 'totalSales');

echo 'Total sales metric value: ' . $salesMetric->getMetricValue();

getDistributorMetricTypes returns all metric type records configured for a given distributor. This is useful for building summary views that show all performance indicators at once.

use Siren\Distributions\Core\Facades\DistributorMetricTypes;

$metrics = DistributorMetricTypes::getDistributorMetricTypes($distributorId);

foreach ($metrics as $metric) {
    echo $metric->getMetricType() . ': ' . $metric->getMetricValue();
}

Relationships

• Program (upstream). Programs reference one or more distributors to define what collaborators earn. A single distributor can serve multiple programs.
• Distribution (downstream). When a distribution cycle runs, the distributor produces distribution records that track the calculated amounts owed to each collaborator.
• Obligation (downstream, indirect). Distributions feed into the obligation and fulfillment pipeline, ultimately resulting in payouts.

REST endpoints

See the individual endpoint pages in the sidebar for full request and response details, or browse the all REST endpoints reference.