Store Credit

Siren keeps each collaborator’s store credit as a ledger of entries in a custom currency. On WordPress a payout in the currency adds an entry, and checkout spending, refunds, and manual adjustments add entries too. The balance is their sum. On Siren Cloud, payouts don’t add entries, so a balance changes through adjustments and connected stores’ checkouts. Pay in Store Credit and Custom Currencies explains the flow for a store owner.

These routes need Siren Essentials and up, and only staff can use them. All paths use the base /wp-json/siren/v1. Every amount is an integer at the currency’s scale, which is whole units for store credit.

Adjust a balance

POST /credits/adjust

Parameter	Required	Description
collaboratorId	Yes	The collaborator to adjust
currency	Yes	The code of a store credit currency
amount	Yes	A non-zero stored integer. A positive amount adds credit and a negative one deducts it. It must fit the currency’s limit, which is 999,999,999 either side of zero for a whole-unit currency
description	No	The reason. Defaults to “Manual adjustment”

Answers 200 with success and entry, which holds the new entry’s id, amount, currency, and collaboratorId. Siren answers 400 when currency isn’t a store credit currency, when amount is zero or out of range, when description is over 255 characters, or when the collaborator doesn’t exist. Siren doesn’t check a deduction against the balance, so a balance can go below zero.

Read balances

GET /credit-balances?collaboratorId=12

collaboratorId is required.

Answers { "items": [...] } with one row for each store credit currency, including currencies where the balance is zero. Add currency to read one currency. On Siren Cloud, a request from a connected store sees only the currencies bound to its Property.

Field	Type	Description
collaboratorId	integer	The collaborator
currency	string	The currency code
balance	integer	The sum of the collaborator’s entries
reserved	integer	Credit held for a checkout in progress
available	integer	balance minus reserved, never below zero, which is what checkout can spend

A collaborator’s own record can carry the same figures through the creditBalances field, as Collaborators describes. That field calls the held amount onHold where this route calls it reserved. On Siren Cloud, each creditBalances row also carries stores, a list of { id, name } for the Properties where the credit can be spent.

List ledger entries

GET /credit-entries?collaboratorId=12

Returns the paginated envelope described in Pagination, Filtering, and Field Selection. The request must name collaboratorId or idempotencyKey. Filter by collaboratorId, idempotencyKey, currency, sourceType, sourceId, or description, all exact matches, and sort by id (the default), dateCreated, or amount.

Field	Type	Description
id	integer	The entry
collaboratorId	integer	The collaborator
currency	string	The currency code
amount	integer	Positive for credit added, negative for credit spent or deducted
sourceType, sourceId	string, integer or null	What made the entry: fulfillment for a payout, adjustment, redemption for checkout spending, refund, reversal, or detection. A reversal or detection entry is a zero-amount marker that keeps an order’s credit from being counted twice
description	string	The entry’s description, such as “Payout #42”
idempotencyKey	string	The key that stops the same entry being written twice
createdDate	datetime	When the entry was written