Set Billing Email
Set or clear the organisation's billing email. Admins of the organisation only.
โถBody
billing_email: an email address, trimmed and lower-cased, at most 254 characters.nullclears it, and the earliest active admin's email applies again.
โถStripe changes in the same request
fm-api saves the email and updates the organisation's Stripe Customer
before it answers. If Stripe refuses or cannot be reached, nothing is saved
and the call returns 502 or 503. A timed-out update may still have
reached Stripe, so fm-api then pushes the saved email back to the Customer.
An organisation with no Stripe Customer yet saves the email only. Its first Checkout creates the Customer with it. So does an organisation whose Customer was deleted at Stripe: fm-api keeps the save and forgets the Customer.
Clearing the email never leaves the Customer without one. If the organisation has no active admin either, the Customer keeps its current email.
โถWho may call it
Only the organisation itself may change its billing email. A parent
organisation cannot change a child's, whether it reaches the child through
its scope or with x-acting-as; it can still read it.
Call it with an admin's member key or OAuth token. An organisation key
cannot change where invoices and receipts go, even when it names an admin
in x-epoch-user-id: the header only attributes the request. Admins can
also change it in the Epoch app.
Every change is logged as billing_email_changed, with the old and new
addresses masked (j***@example.com), the key's id, kind and name, and the
user behind the request when there is one.
โถErrors
| Status | Code | Meaning |
|---|---|---|
| 400 | BAD_REQUEST | The id is not a UUID, or billing_email is not an email address. |
| 401 | Missing or invalid API key. | |
| 403 | FORBIDDEN | The member is not an admin, an organisation key names no admin, the caller is a parent organisation writing a child's, or the key does not hold billing:write. |
| 404 | NOT_FOUND | The organisation is not in this key's scope. |
| 502 | CHECKOUT_GATEWAY_REJECTED | Stripe refused the change. Nothing was saved. |
| 503 | CHECKOUT_UPSTREAM_ERROR | Stripe did not confirm the change. Nothing was saved. Retry. |
| 503 | CHECKOUT_NOT_CONFIGURED | The organisation has a Stripe Customer but this deployment has no Stripe gateway. Nothing was saved. |
Required scope:
billing:write