diff --git a/docs/reference/datasources.md b/docs/reference/datasources.md
index c1ff755..c10312a 100644
--- a/docs/reference/datasources.md
+++ b/docs/reference/datasources.md
@@ -59,6 +59,10 @@ cat datasource.json | gmc datasources create
 
 Input precedence: `--file` → flags → piped stdin. Passing both `--file` and flags is an error. `--json` returns the created `DataSource`.
 
+::: tip Read-after-write
+`create` returns the source (with its `dataSourceId`) immediately, but the Merchant API is eventually consistent: a `get` / `update` / `delete` in the next instant may briefly return `404` until it propagates — usually a few seconds, up to ~20s. If you script `create` followed by another call on the new id, allow a short delay or retry.
+:::
+
 Then push products into the new source:
 
 ```sh
diff --git a/docs/reference/regions.md b/docs/reference/regions.md
index d0e188b..550054f 100644
--- a/docs/reference/regions.md
+++ b/docs/reference/regions.md
@@ -58,6 +58,10 @@ flags (output-only — a region must cover enough area to be usable). `--json` e
 result (`{ "regions": [...] }` for list, the resource for get/create/update, `{ "deleted": "<id>" }`
 for delete).
 
+::: tip Read-after-write
+`create` returns the region immediately, but the Merchant API is eventually consistent: a `get` / `update` / `delete` / `list` in the next instant may briefly return `404` (or omit it) until it propagates — usually a few seconds, up to ~20s. If you script `create` followed by another call on the new id, allow a short delay or retry.
+:::
+
 ## Exit codes
 
 `0` success · `2` usage (no/both areas, missing `--region-code`, unreadable `--file`, bad