Overview
Read platform-managed seller balances and manage payout requests without exposing provider credentials.
Seller payouts are a new, explicit platform-managed funds domain. They are separate from the prepaid fee balance shown on the dashboard and from affiliate referral payouts.
All amounts use integer minor units. For USD, 5000 means $50.00. The balance resource separates funds that are still pending, funds available to request, and funds reserved by open payout requests.
Use a token with the seller-balance ability to read the balance. Payout history, configuration, requests, and cancellations require the more sensitive seller-payout ability. The authenticated actor must belong to the store selected by X-STORE.
Payout requests require an idempotency_key. Repeating the same key with the same amount returns the original request without reserving funds twice. Reusing it with a different amount returns a validation error. Creating a request only reserves funds and queues a durable internal effect; it does not expose provider operations or credentials.
Request, cancellation, and configuration mutations are attributed in the store audit trail. There is no public seller-payout webhook event in this initial contract; integrations should read the payout resource for current status rather than subscribing to affiliate payout events.
Configuration accepts only a destination type and a seller-safe masked label, such as Bank account ending in 4242. Never send account numbers, private keys, access tokens, or other provider secrets in the label.