Payouts

A payout is a single line item representing the amount owed to one collaborator within a fulfillment batch. Each payout records the currency, value, and payment status for one collaborator’s share of a fulfillment run.

The payout object

Status lifecycle

Accessing payout data

# List payouts for a collaborator
curl -X GET "https://your-site.com/wp-json/siren/v1/payouts?collaboratorId=42&fields=id,value,currency,status,datePaid" \
  -H "Authorization: Bearer YOUR_TOKEN"

# List payouts in a fulfillment with collaborator details
curl -X GET "https://your-site.com/wp-json/siren/v1/payouts?fulfillmentId=12&fields=id,value,status,collaboratorName,collaboratorEmail" \
  -H "Authorization: Bearer YOUR_TOKEN"

use Siren\Fulfillments\Core\Datastores\Payout\Interfaces\PayoutDatastore;

class PayoutReport
{
    protected PayoutDatastore $payouts;

    public function __construct(PayoutDatastore $payouts)
    {
        $this->payouts = $payouts;
    }

    public function getPayoutsForCollaborator(int $collaboratorId): array
    {
        return $this->payouts->andWhere([
            ['column' => 'collaboratorId', 'operator' => '=', 'value' => $collaboratorId]
        ]);
    }

    public function getPayoutsForFulfillment(int $fulfillmentId): array
    {
        return $this->payouts->andWhere([
            ['column' => 'fulfillmentId', 'operator' => '=', 'value' => $fulfillmentId]
        ]);
    }
}

use Siren\Fulfillments\Core\Facades\Payouts;

// Get all payouts for a specific collaborator
$payouts = Payouts::andWhere([
    ['column' => 'collaboratorId', 'operator' => '=', 'value' => $collaboratorId]
]);

// Get all payouts within a specific fulfillment
$payouts = Payouts::andWhere([
    ['column' => 'fulfillmentId', 'operator' => '=', 'value' => $fulfillmentId]
]);

$payout = Payouts::getById(55);

Siren is built on an event-driven architecture. Fulfillments and payouts are normally created by the fulfillment generation pipeline in response to admin actions. If you find yourself creating these records manually, consider whether you should be triggering the generation process instead, which ensures obligations are correctly resolved and all downstream events fire.

PHP domain methods

The payout datastore supports all shared methods documented in the introduction. It does not have additional domain-specific methods beyond standard CRUD.

Querying payouts by status and fulfillment

A common pattern is finding all unpaid payouts for a given fulfillment, or calculating the total value of a fulfillment’s payouts.

use Siren\Fulfillments\Core\Facades\Payouts;

// Find unpaid payouts in a fulfillment
$unpaid = Payouts::andWhere([
    ['column' => 'fulfillmentId', 'operator' => '=', 'value' => $fulfillmentId],
    ['column' => 'status', 'operator' => '!=', 'value' => 'paid']
]);

// Calculate total payout value for a fulfillment
$payouts = Payouts::andWhere([
    ['column' => 'fulfillmentId', 'operator' => '=', 'value' => $fulfillmentId]
]);

$total = array_sum(array_map(fn($p) => $p->getValue(), $payouts));

Extended fields (REST only)

Relationships

Each payout belongs to a single collaborator through collaboratorId. When payouts are exported to CSV, the export endpoint resolves the collaborator’s name and email for inclusion in the output.

Each payout belongs to a fulfillment batch through fulfillmentId. The fulfillment’s extended fields (payoutCount, totalValue, etc.) are computed aggregates over its child payouts.

Payouts connect back to obligations indirectly. The generation process that creates payouts also links each source obligation to its payout via the obligation’s payoutId field.

REST endpoints

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