Fulfillments

A fulfillment is a batch container that groups together the payouts generated from pending obligations. When it is time to pay collaborators, the “generate” endpoint collects pending obligations, groups them by collaborator, creates payout records for each, and wraps them in a fulfillment batch. The fulfillment then moves through processing states until all payouts are handled.

The fulfillment object

Field	REST name	PHP getter	Type	Description
ID	`id`	`getId()`	integer	Unique identifier
Status	`status`	`getStatus()`	string	Current status (see lifecycle below)
Created	`dateCreated`	`getCreatedDate()`	datetime	When the fulfillment batch was created
Modified	`dateModified`	`getModifiedDate()`	datetime	When the fulfillment was last modified

Status lifecycle

Pending

The fulfillment batch has been generated. Payouts exist but no processing has begun.

Processing

Payment processing is underway for the payouts in this batch.

Complete

All payouts in the batch have been handled.

Status	Description
`pending`	The fulfillment batch has been generated. Payouts exist but no processing has begun.
`processing`	Payment processing is underway for the payouts in this batch.
`complete`	All payouts in the batch have been handled.
`failed`	The batch encountered an error. Equivalent to a soft delete; a second DELETE request permanently removes the record.

Accessing fulfillment data

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

# Get a single fulfillment with extended fields
curl -X GET "https://your-site.com/wp-json/siren/v1/fulfillments/12?fields=id,status,payoutCount,totalValue,currency" \
  -H "Authorization: Bearer YOUR_TOKEN"

use Siren\Fulfillments\Core\Datastores\Fulfillment\Interfaces\FulfillmentDatastore;

class FulfillmentReport
{
    protected FulfillmentDatastore $fulfillments;

    public function __construct(FulfillmentDatastore $fulfillments)
    {
        $this->fulfillments = $fulfillments;
    }

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

use Siren\Fulfillments\Core\Facades\Fulfillments;

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

$fulfillment = Fulfillments::getById(12);

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

Both the fulfillment and payout datastores support all shared methods documented in the introduction. Neither has additional domain-specific methods beyond standard CRUD.

Extended fields (REST only)

Field	Type	Description
`payoutCount`	integer	Total number of payouts in this fulfillment
`paidCount`	integer	Number of payouts marked as paid
`unpaidCount`	integer	Number of payouts not yet paid
`totalValue`	integer	Sum of all payout values in the fulfillment
`currency`	string	Currency code for this fulfillment’s payouts
`payouts`	array	Nested array of payout objects (detail endpoint only)

Relationships

Fulfillments sit downstream of obligations. The generation process collects pending obligations, creates payouts from them, and links each obligation back to its payout via the obligation’s payoutId field.

A fulfillment acts as a batch container for its payouts. Each payout carries a fulfillmentId linking it to its parent, and the fulfillment’s extended fields (payoutCount, totalValue, etc.) are computed aggregates over its child payouts.

REST endpoints

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