{"lexicon":1,"id":"money.atmosphere.app.setRecipientFeeShare","defs":{"main":{"type":"procedure","description":"Set a LOWER per-recipient app fee for this app (e.g. a creator on the app's own Pro plan keeps more of their revenue). The override must be at or below the app's configured fee and is applied as a minimum whenever ATM prepares a new fee plan — it can only ever reduce the app's share. It affects new checkouts, subscription re-pricing, and pledge conversions; optionally it also lowers application_fee_percent on the app's RUNNING subscriptions for this recipient (lower-only per subscription, batch-capped). Exact processor work whose fee is already frozen remains immutable: in particular, a prepared membership tier-change invoice/schedule keeps its frozen fee until the change completes or is canceled, and its active relationship is deferred from running-subscription re-pricing until then. Requires app service-auth.","input":{"encoding":"application/json","schema":{"type":"object","required":["recipientDid","environment","feeShareBps"],"properties":{"recipientDid":{"type":"string","format":"did"},"environment":{"type":"string","knownValues":["test","live"],"maxLength":8},"feeShareBps":{"type":"integer","minimum":0,"maximum":10000,"description":"Basis points of gross this app takes for this recipient. Must be ≤ the app's configured feeShareBps for the environment."},"reason":{"type":"string","maxLength":64,"description":"App-chosen label for reconciliation (e.g. pro_plan). Private; echoed back in listRecipientFeeShares."},"sourceSubscriptionId":{"type":"string","maxLength":256,"description":"Optional audit pointer to the app-owned subscription justifying the discount."},"expiresAt":{"type":"string","format":"datetime","description":"Optional expiry; past it the override is ignored and fees return to the configured rate."},"applyToActiveSubscriptions":{"type":"boolean","default":false,"description":"Also request a lower application_fee_percent on the app's running subscriptions for this recipient (never raises; batch-capped). A relationship with exact prepared processor work, including a prepared membership tier change, is deferred rather than rewriting its frozen fee. Repeat the same request to drain eligible batches; deferred relationships reconcile after the prepared work completes or is canceled."}}}},"output":{"encoding":"application/json","schema":{"type":"object","required":["recipientDid","environment","feeShareBps","baseFeeShareBps","appliedToSubscriptions","skippedSubscriptions"],"properties":{"recipientDid":{"type":"string","format":"did"},"environment":{"type":"string","knownValues":["test","live"],"maxLength":8},"feeShareBps":{"type":"integer","minimum":0,"maximum":10000},"baseFeeShareBps":{"type":"integer","minimum":0,"maximum":10000,"description":"The app's configured fee this override lowers from."},"appliedToSubscriptions":{"type":"integer","minimum":0},"skippedSubscriptions":{"type":"integer","minimum":0,"description":"Running subscriptions not re-priced by this call, including active relationships deferred behind exact prepared processor work."},"hasMoreSubscriptions":{"type":"boolean","description":"True when more eligible running subscriptions remain or at least one active relationship was deferred/skipped and still carries the older fee. Repeating the same feeShareBps drains eligible batches, but a deferred prepared membership change may keep this true until it completes or is canceled."}}}},"errors":[{"name":"InvalidRecipient"},{"name":"InvalidFeeShare"},{"name":"InvalidExpiry"},{"name":"FeeShareAboveBase","description":"Overrides only lower fees; raise the configured fee through app settings + recipient approval instead."},{"name":"AppEnvironmentNotConfigured"},{"name":"ActiveSubscriptionRepricePending","description":"The existing override is still reconciling a requested lower fee across running subscriptions. Retry after that durable reconciliation finishes before changing its rate or split."}]}}}