Skip to content
Aether Docs

Update an organization

PUT
/api/v1/organizations/{orgID}
curl --request PUT \
  --url https://api.aetherplatform.cloud/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "slug": "example", "billing_email": "example", "vat_id": "example", "payment_mode": "manual" }'

Updates the organization. There is no PATCH: this PUT is also how payment_mode is changed. Changing payment_mode is restricted to members with the owner or admin role and is refused for API tokens; switching to autocharge additionally requires a default payment method. The change is recorded in the audit log as organization.payment_mode_changed.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
orgID
required
string format: uuid

Organization UUID.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
string
slug
string
billing_email
string | null
vat_id
string | null
payment_mode

Optional. Sets how the organization’s issued invoices are paid (see Organization.payment_mode); omit it to leave the mode unchanged. Requires the owner or admin role and is refused for API tokens (403); autocharge requires a default payment method (402 payment_method_required). Any other value is a 422.

string
Allowed values: manual autocharge

Responses

Section titled “Responses”

200

Section titled “200”

The updated organization.

Media typeapplication/json
object
id
required
string format: uuid
name
required
string
slug
required
string
billing_email
string | null
vat_id
string | null
plan
required

Legacy organization field, always starter; not settable through the API and unrelated to a cluster’s package (plan on createCluster).

string
payment_mode
required

How the organization’s issued invoices are paid. manual (the default for every organization): a member pays each invoice through the pay endpoint. autocharge: the default payment method is charged automatically when an invoice is issued. Always present. Changed with payment_mode on updateOrganization.

string
Allowed values: manual autocharge
payment_mode_set_at

When a member last chose payment_mode explicitly. Omitted (not null) while the organization still carries the manual default that nobody chose. An automatic charge is only ever attempted for invoices issued at or after this instant.

string format: date-time
created_at
required
string format: date-time
updated_at
required
string format: date-time
Example
{
  "payment_mode": "manual"
}

400

Section titled “400”

Malformed request — e.g. an invalid path UUID or an unparseable JSON body.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
status_url

The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.

string format: uri
decline_code

The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.

string
invoice_id

Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.

string format: uuid
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ],
    "status_url": "https://example.com",
    "decline_code": "example",
    "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  }
}

401

Section titled “401”

Missing or invalid credentials.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
status_url

The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.

string format: uri
decline_code

The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.

string
invoice_id

Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.

string format: uuid
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ],
    "status_url": "https://example.com",
    "decline_code": "example",
    "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  }
}

402

Section titled “402”

payment_method_required — payment_mode: autocharge was requested and the organization has no default payment method. Nothing was changed.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
status_url

The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.

string format: uri
decline_code

The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.

string
invoice_id

Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.

string format: uuid
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ],
    "status_url": "https://example.com",
    "decline_code": "example",
    "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  }
}

403

Section titled “403”

A payment_mode change was refused: insufficient_role (the caller is a member or viewer) or token_not_permitted (the request was authenticated with an API token). Also answered by the organization role policy (see Authorization): forbidden (not a member of the organization), insufficient_role (the caller’s organization role is below the operation’s minimum) or token_not_permitted (an API token on an operation tokens may not use).

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
status_url

The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.

string format: uri
decline_code

The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.

string
invoice_id

Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.

string format: uuid
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ],
    "status_url": "https://example.com",
    "decline_code": "example",
    "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  }
}

404

Section titled “404”

The requested resource was not found.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
status_url

The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.

string format: uri
decline_code

The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.

string
invoice_id

Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.

string format: uuid
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ],
    "status_url": "https://example.com",
    "decline_code": "example",
    "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  }
}

409

Section titled “409”

The resource already exists or conflicts with current state.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
status_url

The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.

string format: uri
decline_code

The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.

string
invoice_id

Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.

string format: uuid
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ],
    "status_url": "https://example.com",
    "decline_code": "example",
    "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  }
}

422

Section titled “422”

Request validation failed.

Media typeapplication/json
object
error
required
object
code
required

A stable, machine-readable error code.

string
message
required
string
details
Array<object>
object
field
required
string
code
required
string
message
required
string
status_url

The platform status page (https://status.aetherplatform.cloud). Present on 5xx answers written by the API’s error writer and on no other; absent, not null, on 4xx.

string format: uri
decline_code

The payment provider’s decline code. Present only on 402 payment_declined; it is its own field and is never folded into message.

string
invoice_id

Present on exactly these errors of the invoice pay and pay/confirm endpoints: 402 payment_declined, 402 payment_method_required, 409 invoice_already_paid, 409 invoice_not_issued, 409 invoice_below_minimum, 409 payment_not_in_flight, and 409 invoice_void when the void invoice was replaced. It is the id of the live invoice, which after a re-issue is the replacement and not the id in the request URL (on 409 invoice_void from pay/confirm it is the replacement’s id). Absent on every other error — 400 (including discount_code_invalid), 403, 404, the discount_* 409s, 409 invoice_void with no replacement (nothing live to name), every 5xx and 503 code — and never null.

string format: uuid
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": [
      {
        "field": "example",
        "code": "example",
        "message": "example"
      }
    ],
    "status_url": "https://example.com",
    "decline_code": "example",
    "invoice_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  }
}