From cf27730e45dc8d32fd9371db685575cf9f227885 Mon Sep 17 00:00:00 2001
From: Jeet <113221510+JEETDESAI25@users.noreply.github.com>
Date: Tue, 25 Nov 2025 17:25:57 -0800
Subject: [PATCH] fix: clarify organization_id and add import examples

---
 README.md                                      |  1 +
 docs/resources/branch.md                       | 11 +++++++++++
 docs/resources/project.md                      | 13 ++++++++++++-
 docs/resources/settings.md                     | 11 +++++++++++
 docs/schema.json                               |  2 +-
 examples/resources/supabase_branch/import.sh   |  2 ++
 examples/resources/supabase_project/import.sh  |  2 ++
 examples/resources/supabase_settings/import.sh |  2 ++
 internal/provider/project_resource.go          |  2 +-
 9 files changed, 43 insertions(+), 3 deletions(-)
 create mode 100644 examples/resources/supabase_branch/import.sh
 create mode 100644 examples/resources/supabase_project/import.sh
 create mode 100644 examples/resources/supabase_settings/import.sh

diff --git a/README.md b/README.md
index f159d0d..a4c434c 100644
--- a/README.md
+++ b/README.md
@@ -44,6 +44,7 @@ import {
 }
 
 resource "supabase_project" "production" {
+  # organization_id is your organization's slug (it can be found in the Supabase Dashboard under Organization Settings > Organization Details > Organization slug)
   organization_id   = "nknnyrtlhxudbsbuazsu"
   name              = "tf-project"
   database_password = "tf-example"
diff --git a/docs/resources/branch.md b/docs/resources/branch.md
index fea8090..a557f5c 100644
--- a/docs/resources/branch.md
+++ b/docs/resources/branch.md
@@ -49,3 +49,14 @@ Read-Only:
 - `status` (String) Status
 - `user` (String) User
 - `version` (String) Postgres version
+
+## Import
+
+Import is supported using the following syntax:
+
+The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
+
+```shell
+# The ID is the branch identifier.
+terraform import supabase_branch.development <branch_id>
+```
diff --git a/docs/resources/project.md b/docs/resources/project.md
index 7c75304..3f2b525 100644
--- a/docs/resources/project.md
+++ b/docs/resources/project.md
@@ -36,7 +36,7 @@ resource "supabase_project" "test" {
 
 - `database_password` (String, Sensitive) Password for the project database
 - `name` (String) Name of the project
-- `organization_id` (String) Reference to the organization
+- `organization_id` (String) Organization slug (found in the Supabase dashboard URL or organization settings)
 - `region` (String) Region where the project is located
 
 ### Optional
@@ -46,3 +46,14 @@ resource "supabase_project" "test" {
 ### Read-Only
 
 - `id` (String) Project identifier
+
+## Import
+
+Import is supported using the following syntax:
+
+The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
+
+```shell
+# The ID is the project reference.
+terraform import supabase_project.production <project_ref>
+```
diff --git a/docs/resources/settings.md b/docs/resources/settings.md
index b76569d..308e6b9 100644
--- a/docs/resources/settings.md
+++ b/docs/resources/settings.md
@@ -61,3 +61,14 @@ resource "supabase_settings" "production" {
 ### Read-Only
 
 - `id` (String) Project identifier
+
+## Import
+
+Import is supported using the following syntax:
+
+The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
+
+```shell
+# The ID is the project reference.
+terraform import supabase_settings.production <project_ref>
+```
diff --git a/docs/schema.json b/docs/schema.json
index 35f0301..9b00781 100644
--- a/docs/schema.json
+++ b/docs/schema.json
@@ -148,7 +148,7 @@
               },
               "organization_id": {
                 "type": "string",
-                "description": "Reference to the organization",
+                "description": "Organization slug (found in the Supabase dashboard URL or organization settings)",
                 "description_kind": "markdown",
                 "required": true
               },
diff --git a/examples/resources/supabase_branch/import.sh b/examples/resources/supabase_branch/import.sh
new file mode 100644
index 0000000..83c3217
--- /dev/null
+++ b/examples/resources/supabase_branch/import.sh
@@ -0,0 +1,2 @@
+# The ID is the branch identifier.
+terraform import supabase_branch.development <branch_id>
diff --git a/examples/resources/supabase_project/import.sh b/examples/resources/supabase_project/import.sh
new file mode 100644
index 0000000..71e0dc6
--- /dev/null
+++ b/examples/resources/supabase_project/import.sh
@@ -0,0 +1,2 @@
+# The ID is the project reference.
+terraform import supabase_project.production <project_ref>
diff --git a/examples/resources/supabase_settings/import.sh b/examples/resources/supabase_settings/import.sh
new file mode 100644
index 0000000..2e999ac
--- /dev/null
+++ b/examples/resources/supabase_settings/import.sh
@@ -0,0 +1,2 @@
+# The ID is the project reference.
+terraform import supabase_settings.production <project_ref>
diff --git a/internal/provider/project_resource.go b/internal/provider/project_resource.go
index f706475..1d9a495 100644
--- a/internal/provider/project_resource.go
+++ b/internal/provider/project_resource.go
@@ -52,7 +52,7 @@ func (r *ProjectResource) Schema(ctx context.Context, req resource.SchemaRequest
 
 		Attributes: map[string]schema.Attribute{
 			"organization_id": schema.StringAttribute{
-				MarkdownDescription: "Reference to the organization",
+				MarkdownDescription: "Organization slug (found in the Supabase dashboard URL or organization settings)",
 				Required:            true,
 			},
 			"name": schema.StringAttribute{