Partial release
Pay a share in basis points. The remainder returns to you, not to us.
released_bps pays a share of the warrant and returns the whole remainder to your available balance — nothing is retained in between.
amount "8400000" 8.40 USDC
released_bps 5000 half
→ payee 4200000 4.20 USDC
→ available 4200000 4.20 USDCTwo ways it happens
A policy band decides it. A partial_release band with releasedBps fires
when the score lands in its range, and no person is involved.
{ "minScore": 0.8, "outcome": "partial_release", "releasedBps": 5000 }A person chooses it when resolving an escalation.
curl -sS https://api.gowarrant.xyz/v1/warrants/$WARRANT_ID/partial \
-b "warrant_session=$WARRANT_SESSION" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "released_bps": 5000 }'An API key cannot do this. It gets 403 user_session_required — settling needs
a person, or the passkey threshold would be decorative.
Basis points, strictly between the ends
released_bps must be an integer greater than 0 and less than 10000.
Zero is a refund and 10000 is a release. Those already exist as their own endpoints and their own states, so a partial that is really one of them would just be a second name for the same thing.
released_bps | Share |
|---|---|
| 2500 | a quarter |
| 5000 | half |
| 7500 | three quarters |
| 9900 | 99% |
The amount field does not change
After a partial release the warrant still reports the full amount, with
released_bps alongside it:
{
"state": "partially_released",
"amount": "8400000",
"released_bps": 5000
}The paid figure is the product of the two, not a third stored number. Two numbers that must agree eventually disagree; one number and a ratio cannot.
Do not read `amount` as what moved
This catches people. On a warrant.partially_released webhook, amount is
"8400000" and the payee received 4200000. Multiply by released_bps / 10000.
Where the remainder goes
Back to your available balance, in the same transaction. It is not retained,
and there is nothing for it to be retained by — Warrant charges no fee and the
ledger has no account one could sit in. Every tx_ref nets to zero across
exactly two accounts. See fees.
When it is the right answer
A supplier delivered something usable but not what was specified: the endpoint answered, the schema matched, the data was an hour stale. A refund says the work was worthless and a release says it was fine. Neither is true, and a partial is the only outcome that is.
If you find yourself always choosing the same share for the same reason code, that is a policy band waiting to be written — see your first policy.
Amounts
Integer strings of the smallest unit, ^[0-9]+$. released_bps is a plain
integer, not a string, because it is a ratio rather than a quantity of money.
"8400000" 8.40 USDC
8400000 rejected — a JSON number
"8.40" rejected — not the smallest unit