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. null clears 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

StatusCodeMeaning
400BAD_REQUESTThe id is not a UUID, or billing_email is not an email address.
401Missing or invalid API key.
403FORBIDDENThe 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.
404NOT_FOUNDThe organisation is not in this key's scope.
502CHECKOUT_GATEWAY_REJECTEDStripe refused the change. Nothing was saved.
503CHECKOUT_UPSTREAM_ERRORStripe did not confirm the change. Nothing was saved. Retry.
503CHECKOUT_NOT_CONFIGUREDThe organisation has a Stripe Customer but this deployment has no Stripe gateway. Nothing was saved.

Required scope: billing:write