Merge pull request #4247 from ClickHouse/rsickles-patch-6

Updated api overview doc with new pricing migration information

Author: Blargian

docs/cloud/manage/api/api-overview.md

@@ -25,6 +25,13 @@ consume the ClickHouse Cloud API docs, we offer a JSON-based Swagger endpoint
 via https://api.clickhouse.cloud/v1. You can also find the API docs via
 the [Swagger UI](https://clickhouse.com/docs/cloud/manage/api/swagger).
 
+:::note 
+If your organization has been migrated to one of the [new pricing plans](https://clickhouse.com/pricing?plan=scale&provider=aws&region=us-east-1&hours=8&storageCompressed=false), and you use OpenAPI you will be required to remove the `tier` field in the service creation `POST` request.
+
+The `tier` field has been removed from the service object as we no longer have service tiers.  
+This will affect the objects returned by the `POST`, `GET`, and `PATCH` service requests. Therefore, any code that consumes these APIs may need to be adjusted to handle these changes.
+:::
+
 ## Rate limits {#rate-limits}
 
 Developers are limited to 100 API keys per organization. Each API key has a 
@@ -43,6 +50,17 @@ You can view the Terraform provider docs in the [Terraform registry](https://reg
 If you'd like to contribute to the ClickHouse Terraform Provider, you can view 
 the source [in the GitHub repo](https://github.com/ClickHouse/terraform-provider-clickhouse).
 
+:::note 
+If your organization has been migrated to one of the [new pricing plans](https://clickhouse.com/pricing?plan=scale&provider=aws&region=us-east-1&hours=8&storageCompressed=false), you will be required to use our [ClickHouse Terraform provider](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs) version 2.0.0 or above. This upgrade is required to handle changes in the `tier` attribute of the service since, after pricing migration, the `tier` field is no longer accepted and references to it should be removed.
+
+You will now also be able to specify the `num_replicas` field as a property of the service resource.
+:::
+
+## Terraform and OpenAPI New Pricing: Replica Settings Explained
+The number of replicas each service will be created with defaults to 3 for the Scale and Enterprise tiers, while it defaults to 1 for the Basic tier.
+For the Scale and the Enterprise tiers it is possible to adjust it by passing a `numReplicas` field in the service creation request. 
+The value of the `numReplicas` field must be between 2 and 20 for the first service in a warehouse. Services that are created in an existing warehouse can have a number of replicas as low as 1.
+
 ## Support {#support}
 
 We recommend visiting [our Slack channel](https://clickhouse.com/slack) first to get quick support. If