doc: custom hostname PATCH requires type+method when changing CA

src/content/docs/cloudflare-for-platforms/cloudflare-for-saas/reference/troubleshooting.mdx

@@ -96,7 +96,7 @@
 
 ## Older devices have issues connecting
 
 As Let's Encrypt - one of the [certificate authorities (CAs)](/ssl/reference/certificate-authorities/) used by Cloudflare - has announced changes in its [chain of trust](/ssl/concepts/#chain-of-trust), starting September 9, 2024, there may be issues with older devices trying to connect to your custom hostname certificate.
 
 Consider the following solutions:
 
@@ -124,6 +124,18 @@
 - Use the [Edit Custom Hostname](/api/resources/custom_hostnames/methods/edit/) endpoint to set the `certificate_authority` parameter to `google`: this sets Google Trust Services as the CA for your custom hostnames. In your API call, make sure to also include `method` and `type` in the `ssl` object.
 - If you are using a custom certificate for your custom hostname, refer to the [custom certificates troubleshooting](/ssl/edge-certificates/custom-certificates/troubleshooting/#lets-encrypt-chain-update).
 
+## Missing required SSL fields when editing custom hostname
+
+The [Edit Custom Hostname](/api/resources/custom_hostnames/methods/edit/) PATCH endpoint requires specific `ssl` fields depending on whether the custom hostname uses a managed certificate or a [custom certificate](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/). Omitting required fields returns an error.
+
+**Managed certificates** — `ssl.type` (`"dv"`) and `ssl.method` (`"http"` or `"txt"`) are always required. For example, changing `certificate_authority` without including `type` and `method` will fail.
+
+**Custom certificates** — `ssl.custom_certificate` is always required, plus one of `ssl.custom_key` or `ssl.custom_csr_id`.
+
+For the full list of required fields and examples, refer to [Edit custom hostname SSL](/cloudflare-for-platforms/cloudflare-for-saas/start/common-api-calls/#edit-custom-hostname-ssl).
+
+***
+
 ## Custom hostname fails to verify because the zone is held
 
 The [zone hold feature](/fundamentals/account/account-security/zone-holds/) is a toggle that will prevent their zone from being activated on other Cloudflare account. When enabled, Cloudflare is not able to issue an SSL/TLS certificate on behalf of that domain name for either a zone or custom hostname.

src/content/docs/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/issue-and-validate/issue-certificates.mdx

@@ -8,7 +8,7 @@ head:
     content: Issue certificates
 ---
 
-import { Render } from "~/components";
+import { Details, Render } from "~/components";
 
 Cloudflare automatically issues certificates when you [create a custom hostname](/cloudflare-for-platforms/cloudflare-for-saas/domain-support/create-custom-hostnames/).
 
@@ -24,6 +24,54 @@ If you create the custom hostname via API, you can leave the `certificate_author
 
 Refer to [this certificate authorities reference page](/ssl/reference/certificate-authorities/) to learn more about the CAs that Cloudflare uses to issue SSL/TLS certificates.
 
+## Change certificate authority
+
+To change the CA for an existing managed custom hostname, use the [Edit Custom Hostname](/api/resources/custom_hostnames/methods/edit/) PATCH endpoint. You must include `ssl.type` and `ssl.method` alongside `ssl.certificate_authority` — these fields are always required when [editing a managed hostname's SSL settings](/cloudflare-for-platforms/cloudflare-for-saas/start/common-api-calls/#managed-certificates).
+
+This triggers certificate re-issuance with the new CA.
+
+<Details header="Switch to Google Trust Services">
+
+```sh
+curl --request PATCH 
+"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
+--header "X-Auth-Email: <EMAIL>" \
+--header "X-Auth-Key: <API_KEY>" \
+--header "Content-Type: application/json" \
+--data '{
+  "ssl": {
+      "type": "dv",
+      "method": "http",
+      "certificate_authority": "google"
+  }
+}'
+```
+
+</Details>
+
+<Details header="Reset to default CA">
+
+To let Cloudflare choose the best CA, set `certificate_authority` to an empty string:
+
+```sh
+curl --request PATCH \
+"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
+--header "X-Auth-Email: <EMAIL>" \
+--header "X-Auth-Key: <API_KEY>" \
+--header "Content-Type: application/json" \
+--data '{
+  "ssl": {
+      "type": "dv",
+      "method": "http",
+      "certificate_authority": ""
+  }
+}'
+```
+
+</Details>
+
+Valid `certificate_authority` values: `"google"` (Google Trust Services), `"lets_encrypt"` (Let's Encrypt), `"ssl_com"` (SSL.com), or `""` (empty string for default CA).
+
 ## Certificate details and compatibility
 
 <Render file="issue-certs-preamble" product="cloudflare-for-platforms" />

src/content/docs/cloudflare-for-platforms/cloudflare-for-saas/start/common-api-calls.mdx

@@ -6,6 +6,8 @@ sidebar:
 
 ---
 
+import { Details } from "~/components";
+
 As a SaaS provider, you may want to configure and manage Cloudflare for SaaS [via the API](/api/) rather than the [Cloudflare dashboard](https://dash.cloudflare.com/). Below are relevant API calls for creating, editing, and deleting custom hostnames, as well as monitoring, updating, and deleting fallback origins. Further details can be found in the [Cloudflare API documentation](/api/).
 
 ***
@@ -17,9 +19,87 @@ As a SaaS provider, you may want to configure and manage Cloudflare for SaaS [vi
 | [List custom hostnames](/api/resources/custom_hostnames/methods/list/)                                        | Use the `page` parameter to pull additional pages. Add a `hostname` parameter to search for specific hostnames.                         |
 | [Create custom hostname](/api/resources/custom_hostnames/methods/create/)                                      | In the `validation_records` object of the response, use the `txt_name` and `txt_record` listed  to validate the custom hostname.        |
 | [Custom hostname details](/api/resources/custom_hostnames/methods/get/)                                    |                                                                                                                                         |
-| [Edit custom hostname](/api/resources/custom_hostnames/methods/edit/)                                          | When sent with an `ssl` object that matches the existing value, indicates that hostname should restart domain control validation (DCV). |
+| [Edit custom hostname](/api/resources/custom_hostnames/methods/edit/)                                          | When sent with an `ssl` object that matches the existing value, indicates that hostname should restart domain control validation (DCV). Refer to [Edit custom hostname SSL](#edit-custom-hostname-ssl) for required fields. |
 | [Delete custom hostname](/api/resources/custom_hostnames/methods/delete/) | Also deletes any associated SSL/TLS certificates.                                                                                       |
 
+### Edit custom hostname SSL
+
+Custom hostname SSL configurations come in two types, each with different required fields when sending a [PATCH request](/api/resources/custom_hostnames/methods/edit/).
+
+#### Managed certificates
+
+Cloudflare handles the certificate lifecycle (ordering, validation, renewal). When editing a managed custom hostname's `ssl` object, `type` and `method` are always required:
+
+- `type` — Validation type. The only valid value is `"dv"`.
+- `method` — Validation method. Use `"http"` or `"txt"`.
+- `certificate_authority` — Optional. Valid values: `"google"`, `"lets_encrypt"`, `"ssl_com"`, or `""` (empty string for [default CA](/ssl/reference/certificate-authorities/)).
+
+Changing the `certificate_authority` triggers certificate re-issuance with the new CA.
+
+<Details header="Example: Change certificate authority">
+
+```sh
+curl --request PATCH \
+"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
+--header "X-Auth-Email: <EMAIL>" \
+--header "X-Auth-Key: <API_KEY>" \
+--header "Content-Type: application/json" \
+--data '{
+  "ssl": {
+      "type": "dv",
+      "method": "http",
+      "certificate_authority": "google"
+  }
+}'
+```
+
+</Details>
+
+<Details header="Example: Reset to default CA">
+
+```sh
+curl --request PATCH \
+"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
+--header "X-Auth-Email: <EMAIL>" \
+--header "X-Auth-Key: <API_KEY>" \
+--header "Content-Type: application/json" \
+--data '{
+  "ssl": {
+      "type": "dv",
+      "method": "http",
+      "certificate_authority": ""
+  }
+}'
+```
+
+</Details>
+
+#### Custom certificates
+
+You provide your own certificate and key material. When editing a [custom certificate](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/) hostname's `ssl` object, `custom_certificate` is always required, plus one of `custom_key` or `custom_csr_id`:
+
+- `custom_certificate` — PEM-encoded certificate. Always required.
+- `custom_key` — PEM-encoded private key. Required unless using a CSR.
+- `custom_csr_id` — ID of a previously created [certificate signing request](/cloudflare-for-platforms/cloudflare-for-saas/security/certificate-management/custom-certificates/certificate-signing-requests/). Required if the private key was generated via CSR.
+
+<Details header="Example: Update custom certificate">
+
+```sh
+curl --request PATCH \
+"https://api.cloudflare.com/client/v4/zones/{zone_id}/custom_hostnames/{custom_hostname_id}" \
+--header "X-Auth-Email: <EMAIL>" \
+--header "X-Auth-Key: <API_KEY>" \
+--header "Content-Type: application/json" \
+--data '{
+  "ssl": {
+      "custom_certificate": "<CERTIFICATE_STRING>",
+      "custom_key": "<PRIVATE_KEY_STRING>"
+  }
+}'
+```
+
+</Details>
+
 ## Fallback origins
 
 Our API includes the following endpoints related to the [fallback origin](/cloudflare-for-platforms/cloudflare-for-saas/start/getting-started/#1-create-fallback-origin) of a custom hostname: