diff --git a/src/routes/docs/products/databases/documents/+page.markdoc b/src/routes/docs/products/databases/documents/+page.markdoc
index f868d0b06..3bd5d8db2 100644
--- a/src/routes/docs/products/databases/documents/+page.markdoc
+++ b/src/routes/docs/products/databases/documents/+page.markdoc
@@ -256,6 +256,125 @@ query {
 ```
 {% /multicode %}
 
+# Upsert documents {% #upsert-documents %}
+{% info title="Permissions required" %}
+You must grant **create** and **update** permissions to users at the **collection level** before users can upsert documents. You can also grant **update** permissions at the document level instead.
+[Learn more about permissions](#permissions)
+{% /info %}
+
+In most use cases, you will upsert documents programmatically.
+
+{% multicode %}
+```client-web
+import { Client, Databases, ID } from "appwrite";
+
+const client = new Client()
+    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
+    .setProject('<PROJECT_ID>');
+
+const databases = new Databases(client);
+
+const promise = databases.upsertDocument(
+    '<DATABASE_ID>',
+    '[COLLECTION_ID]',
+    ID.unique(),
+    {}
+);
+
+promise.then(function (response) {
+    console.log(response);
+}, function (error) {
+    console.log(error);
+});
+```
+```client-flutter
+import 'package:appwrite/appwrite.dart';
+
+void main() async {
+    final client = Client()
+        .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
+        .setProject('<PROJECT_ID>');
+
+    final databases = Databases(client);
+
+    try {
+        final document = databases.upsertDocument(
+            databaseId: '<DATABASE_ID>',
+            collectionId: '[COLLECTION_ID]',
+            documentId: ID.unique(),
+            data: {}
+        );
+    } on AppwriteException catch(e) {
+        print(e);
+    }
+}
+```
+```client-apple
+import Appwrite
+import AppwriteModels
+
+func main() async throws {
+    let client = Client()
+        .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
+        .setProject("<PROJECT_ID>")
+
+    let databases = Databases(client)
+
+    do {
+        let document = try await databases.upsertDocument(
+            databaseId: "<DATABASE_ID>",
+            collectionId: "<COLLECTION_ID>",
+            documentId: ID.unique(),
+            data: [:]
+        )
+    } catch {
+        print(error.localizedDescription)
+    }
+}
+```
+```client-android-kotlin
+import io.appwrite.Client
+import io.appwrite.services.Databases
+
+suspend fun main() {
+    val client = Client(applicationContext)
+        .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
+        .setProject("<PROJECT_ID>")
+
+    val databases = Databases(client)
+
+    try {
+        val document = databases.upsertDocument(
+            databaseId = "<DATABASE_ID>",
+            collectionId = "<COLLECTION_ID>",
+            documentId = ID.unique(),
+            data = mapOf("a" to "b"),
+        )
+    } catch (e: Exception) {
+        Log.e("Appwrite", "Error: " + e.message)
+    }
+}
+```
+```graphql
+mutation {
+    databasesUpsertDocument(
+        databaseId: "<DATABASE_ID>",
+        collectionId: "<COLLECTION_ID>",
+        documentId: "[DOCUMENT_ID]",
+        data: "{}"
+    ) {
+        _id
+        _collectionId
+        _databaseId
+        _createdAt
+        _updatedAt
+        _permissions
+        data
+    }
+}
+```
+{% /multicode %}
+
 # Permissions {% #permissions %}
 In Appwrite, permissions can be granted at the collection level and the document level.
 Before a user can create a document, you need to grant create permissions to the user.