---
layout: article
title: Timestamp overrides
description: Set custom $createdAt and $updatedAt timestamps for your documents when using server SDKs.
---

When creating or updating documents, Appwrite automatically sets `$createdAt` and `$updatedAt` timestamps. However, there are scenarios where you might need to set these timestamps manually, such as when migrating data from another system or backfilling historical records.

{% info title="Server SDKs required" %}
To manually set `$createdAt` and `$updatedAt`, you must use a **server SDK** with an **API key**. These attributes can be passed inside the `data` parameter on any of the create, update, or upsert routes (single or bulk).
{% /info %}

# Setting custom timestamps {% #setting-custom-timestamps %}

You can override a document's timestamps by providing ISO 8601 strings (for example, `2025-08-10T12:34:56.000Z`) in the `data` payload. If these attributes are not provided, Appwrite will set them automatically.

Custom timestamps work with all document operations: create, update, upsert, and their bulk variants.

## Single document operations {% #single-document-operations %}

When working with individual documents, you can set custom timestamps during create, update, and upsert operations.

### Create with custom timestamps {% #create-custom %}

{% multicode %}
```server-nodejs
const sdk = require('node-appwrite');

const client = new sdk.Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<PROJECT_ID>')
    .setKey('<API_KEY>');

const databases = new sdk.Databases(client);

await databases.createDocument(
    '<DATABASE_ID>',
    '<COLLECTION_ID>',
    sdk.ID.unique(),
    {
        '$createdAt': new Date('2025-08-10T12:34:56.000Z').toISOString(),
        '$updatedAt': new Date('2025-08-10T12:34:56.000Z').toISOString(),
        // ...your attributes
    }
);
```
```server-php
use Appwrite\Client;
use Appwrite\ID;
use Appwrite\Services\Databases;

$client = (new Client())
    ->setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    ->setProject('<YOUR_PROJECT_ID>')
    ->setKey('<YOUR_API_KEY>');

$databases = new Databases($client);

$databases->createDocument(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    [
        '$createdAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
        '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
        // ...your attributes
    ]
);
```
```server-swift
import Appwrite
import Foundation

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<YOUR_PROJECT_ID>")
    .setKey("<YOUR_API_KEY>")

let databases = Databases(client)

let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let customDate = isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date()
let createdAt = isoFormatter.string(from: customDate)
let updatedAt = isoFormatter.string(from: customDate)

do {
    let created = try await databases.createDocument(
        databaseId: "<DATABASE_ID>",
        collectionId: "<COLLECTION_ID>",
        documentId: "<DOCUMENT_ID>",
        data: [
            "$createdAt": createdAt,
            "$updatedAt": updatedAt,
            // ...your attributes
        ]
    )
    print("Created:", created)
} catch {
    print("Create error:", error)
}
```
```server-python
from appwrite.client import Client
from appwrite.services.databases import Databases
from appwrite.id import ID
from datetime import datetime, timezone

client = Client()
client.set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
client.set_project('<PROJECT_ID>')
client.set_key('<API_KEY>')

databases = Databases(client)

iso = datetime(2025, 8, 10, 12, 34, 56, tzinfo=timezone.utc).isoformat()

databases.create_document(
        database_id='<DATABASE_ID>',
        collection_id='<COLLECTION_ID>',
        document_id=ID.unique(),
        data={
                '$createdAt': iso,
                '$updatedAt': iso,
                # ...your attributes
        }
)
```
```server-ruby
require 'appwrite'
require 'time'

include Appwrite

client = Client.new
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<YOUR_PROJECT_ID>')
    .set_key('<YOUR_API_KEY>')

databases = Databases.new(client)

custom_date = Time.parse('2025-08-10T12:34:56.000Z').iso8601

databases.create_document(
    database_id: '<DATABASE_ID>',
    collection_id: '<COLLECTION_ID>',
    document_id: ID.unique(),
    data: {
        '$createdAt' => custom_date,
        '$updatedAt' => custom_date,
        # ...your attributes
    }
)
```
```server-dotnet
using Appwrite;
using Appwrite.Models;
using Appwrite.Services;

Client client = new Client()
    .SetEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .SetProject("<YOUR_PROJECT_ID>")
    .SetKey("<YOUR_API_KEY>");

Databases databases = new Databases(client);

string customDate = DateTimeOffset.Parse("2025-08-10T12:34:56.000Z").ToString("O");

await databases.CreateDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: ID.Unique(),
    data: new Dictionary<string, object>
    {
        ["$createdAt"] = customDate,
        ["$updatedAt"] = customDate,
        // ...your attributes
    }
);
```
```server-dart
import 'package:dart_appwrite/dart_appwrite.dart';

Client client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<YOUR_PROJECT_ID>')
    .setKey('<YOUR_API_KEY>');

Databases databases = Databases(client);

String customDate = DateTime.parse('2025-08-10T12:34:56.000Z').toIso8601String();

await databases.createDocument(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: ID.unique(),
    data: {
        '\$createdAt': customDate,
        '\$updatedAt': customDate,
        // ...your attributes
    },
);
```
```rust
use appwrite::Client;
use appwrite::services::databases::Databases;
use appwrite::id::ID;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let databases = Databases::new(&client);

    let result = databases.create_document(
        "<DATABASE_ID>",
        "<COLLECTION_ID>",
        &ID::unique(),
        json!({
            "$createdAt": "2025-08-10T12:34:56.000Z",
            "$updatedAt": "2025-08-10T12:34:56.000Z"
            // ...your attributes
        }),
        None,
        None,
    ).await?;

    println!("Created: {:?}", result);
    Ok(())
}
```
{% /multicode %}

### Update with custom timestamps {% #update-custom %}

When updating documents, you can also set a custom `$updatedAt` timestamp:

{% multicode %}
```server-nodejs
await databases.updateDocument(
    '<DATABASE_ID>',
    '<COLLECTION_ID>',
    '<DOCUMENT_ID>',
    {
        '$updatedAt': new Date('2025-08-10T12:34:56.000Z').toISOString(),
        // ...your attributes
    }
);
```
```server-php
$databases->updateDocument(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documentId: '<DOCUMENT_ID>',
    [
        '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
        // ...your attributes
    ]
);
```
```server-python
from datetime import datetime, timezone

databases.update_document(
    database_id='<DATABASE_ID>',
    collection_id='<COLLECTION_ID>',
    document_id='<DOCUMENT_ID>',
    data={
        '$updatedAt': datetime(2025, 8, 10, 12, 34, 56, tzinfo=timezone.utc).isoformat(),
        # ...your attributes
    }
)
```
```server-swift
import Appwrite
import Foundation

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<YOUR_PROJECT_ID>")
    .setKey("<YOUR_API_KEY>")

let databases = Databases(client)

let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let updatedAt = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())

do {
    let updated = try await databases.updateDocument(
        databaseId: "<DATABASE_ID>",
        collectionId: "<COLLECTION_ID>",
        documentId: "<DOCUMENT_ID>",
        data: [
            "$updatedAt": updatedAt,
            // ...your attributes
        ]
    )
    print("Updated:", updated)
} catch {
    print("Update error:", error)
}
```
```server-ruby
require 'appwrite'

include Appwrite

client = Client.new
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<YOUR_PROJECT_ID>')
    .set_key('<YOUR_API_KEY>')

databases = Databases.new(client)

custom_date = Time.parse('<CUSTOM_DATE>').iso8601

databases.update_document(
  database_id: '<DATABASE_ID>',
  collection_id: '<COLLECTION_ID>',
  document_id: '<DOCUMENT_ID>',
  data: {
    '$updatedAt' => custom_date,
    # ...your attributes
  }
)
```
```server-dotnet
using Appwrite;
using Appwrite.Models;
using Appwrite.Services;

Client client = new Client()
    .SetEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .SetProject("<YOUR_PROJECT_ID>")
    .SetKey("<YOUR_API_KEY>");

Databases databases = new Databases(client);

string customDate = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");

await databases.UpdateDocument(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documentId: "<DOCUMENT_ID>",
    data: new Dictionary<string, object>
    {
        ["$updatedAt"] = customDate,
        // ...your attributes
    }
);
```
```server-dart
import 'package:dart_appwrite/dart_appwrite.dart';

Client client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<YOUR_PROJECT_ID>')
    .setKey('<YOUR_API_KEY>');

Databases databases = Databases(client);

String customDate = DateTime.parse('<CUSTOM_DATE>').toIso8601String();

await databases.updateDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documentId: '<DOCUMENT_ID>',
  data: {
    '\$updatedAt': customDate,
    // ...your attributes
  },
);
```
```rust
use appwrite::Client;
use appwrite::services::databases::Databases;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let databases = Databases::new(&client);

    let result = databases.update_document(
        "<DATABASE_ID>",
        "<COLLECTION_ID>",
        "<DOCUMENT_ID>",
        Some(json!({
            "$updatedAt": "2025-08-10T12:34:56.000Z"
            // ...your attributes
        })),
        None,
        None,
    ).await?;

    println!("Updated: {:?}", result);
    Ok(())
}
```
{% /multicode %}

## Bulk operations {% #bulk-operations %}

Custom timestamps also work with bulk operations, allowing you to set different timestamps for each document in the batch:

### Bulk create {% #bulk-create %}

{% multicode %}
```server-nodejs
await databases.createDocuments(
    '<DATABASE_ID>',
    '<COLLECTION_ID>',
    [
        {
            '$id': sdk.ID.unique(),
            '$createdAt': new Date('2024-01-01T00:00:00.000Z').toISOString(),
            '$updatedAt': new Date('2024-01-01T00:00:00.000Z').toISOString(),
            // ...your attributes
        },
        {
            '$id': sdk.ID.unique(),
            '$createdAt': new Date('2024-02-01T00:00:00.000Z').toISOString(),
            '$updatedAt': new Date('2024-02-01T00:00:00.000Z').toISOString(),
            // ...your attributes
        }
    ]
);
```
```server-python
databases.create_documents(
        database_id='<DATABASE_ID>',
        collection_id='<COLLECTION_ID>',
        documents=[
            {
                '$id': ID.unique(),
                '$createdAt': datetime(2024, 1, 1, tzinfo=timezone.utc).isoformat(),
                '$updatedAt': datetime(2024, 1, 1, tzinfo=timezone.utc).isoformat(),
                # ...your attributes
            },
            {
                '$id': ID.unique(),
                '$createdAt': datetime(2024, 2, 1, tzinfo=timezone.utc).isoformat(),
                '$updatedAt': datetime(2024, 2, 1, tzinfo=timezone.utc).isoformat(),
                # ...your attributes
            }
        ]
)
```
```server-php
use Appwrite\Client;
use Appwrite\ID;
use Appwrite\Services\Databases;

$client = (new Client())
    ->setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    ->setProject('<YOUR_PROJECT_ID>')
    ->setKey('<YOUR_API_KEY>');

$databases = new Databases($client);

$databases->createDocuments(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documents: [
        [
            '$id' => ID::unique(),
            '$createdAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            // ...your attributes
        ],
        [
            '$id' => ID::unique(),
            '$createdAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            // ...your attributes
        ],
    ]
);
```
```server-swift
import Appwrite
import Foundation

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<YOUR_PROJECT_ID>")
    .setKey("<YOUR_API_KEY>")

let databases = Databases(client)

let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]

let first = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())
let second = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())

do {
    let bulkCreated = try await databases.createDocuments(
        databaseId: "<DATABASE_ID>",
        collectionId: "<COLLECTION_ID>",
        documents: [
            [
                "$id": ID.unique(),
                "$createdAt": first,
                "$updatedAt": first,
                // ...your attributes
            ],
            [
                "$id": ID.unique(),
                "$createdAt": second,
                "$updatedAt": second,
                // ...your attributes
            ]
        ]
    )
    print("Bulk create:", bulkCreated)
} catch {
    print("Bulk create error:", error)
}
```
```server-ruby
require 'appwrite'

include Appwrite

client = Client.new
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<YOUR_PROJECT_ID>')
    .set_key('<YOUR_API_KEY>')

databases = Databases.new(client)

first = Time.parse('<CUSTOM_DATE>').iso8601
second = Time.parse('<CUSTOM_DATE>').iso8601

databases.create_documents(
  database_id: '<DATABASE_ID>',
  collection_id: '<COLLECTION_ID>',
  documents: [
    {
      '$id' => ID.unique(),
      '$createdAt' => first,
      '$updatedAt' => first,
      # ...your attributes
    },
    {
      '$id' => ID.unique(),
      '$createdAt' => second,
      '$updatedAt' => second,
      # ...your attributes
    }
  ]
)
```
```server-dotnet
using Appwrite;
using Appwrite.Models;
using Appwrite.Services;

Client client = new Client()
    .SetEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .SetProject("<YOUR_PROJECT_ID>")
    .SetKey("<YOUR_API_KEY>");

Databases databases = new Databases(client);

string first = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");
string second = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");

await databases.CreateDocuments(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documents: new List<object>
    {
        new Dictionary<string, object>
        {
            ["$id"] = ID.Unique(),
            ["$createdAt"] = first,
            ["$updatedAt"] = first,
            // ...your attributes
        },
        new Dictionary<string, object>
        {
            ["$id"] = ID.Unique(),
            ["$createdAt"] = second,
            ["$updatedAt"] = second,
            // ...your attributes
        }
    }
);
```
```server-dart
import 'package:dart_appwrite/dart_appwrite.dart';

Client client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<YOUR_PROJECT_ID>')
    .setKey('<YOUR_API_KEY>');

Databases databases = Databases(client);

String first = DateTime.parse('<CUSTOM_DATE>').toIso8601String();
String second = DateTime.parse('<CUSTOM_DATE>').toIso8601String();

await databases.createDocuments(
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documents: [
    {
      '\$id': ID.unique(),
      '\$createdAt': first,
      '\$updatedAt': first,
      // ...your attributes
    },
    {
      '\$id': ID.unique(),
      '\$createdAt': second,
      '\$updatedAt': second,
      // ...your attributes
    }
  ],
);
```
```rust
use appwrite::Client;
use appwrite::services::databases::Databases;
use appwrite::id::ID;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let databases = Databases::new(&client);

    let result = databases.create_documents(
        "<DATABASE_ID>",
        "<COLLECTION_ID>",
        vec![
            json!({
                "$id": ID::unique(),
                "$createdAt": "2024-01-01T00:00:00.000Z",
                "$updatedAt": "2024-01-01T00:00:00.000Z"
                // ...your attributes
            }),
            json!({
                "$id": ID::unique(),
                "$createdAt": "2024-02-01T00:00:00.000Z",
                "$updatedAt": "2024-02-01T00:00:00.000Z"
                // ...your attributes
            }),
        ],
        None,
    ).await?;

    println!("Bulk create: {:?}", result);
    Ok(())
}
```
{% /multicode %}

### Bulk upsert {% #bulk-upsert %}

{% multicode %}
```server-nodejs
await databases.upsertDocuments(
    '<DATABASE_ID>',
    '<COLLECTION_ID>',
    [
        {
            '$id': '<DOCUMENT_ID_OR_NEW_ID>',
            '$createdAt': new Date('2024-01-01T00:00:00.000Z').toISOString(),
            '$updatedAt': new Date('2025-01-01T00:00:00.000Z').toISOString(),
            // ...your attributes
        }
    ]
);
```
```server-python
databases.upsert_documents(
    database_id='<DATABASE_ID>',
    collection_id='<COLLECTION_ID>',
    documents=[
        {
            '$id': '<DOCUMENT_ID_OR_NEW_ID>',
            '$createdAt': datetime(2024, 1, 1, tzinfo=timezone.utc).isoformat(),
            '$updatedAt': datetime(2025, 1, 1, tzinfo=timezone.utc).isoformat(),
            # ...your attributes
        }
    ]
)
```
```server-php
use Appwrite\Client;
use Appwrite\ID;
use Appwrite\Services\Databases;

$client = (new Client())
    ->setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    ->setProject('<YOUR_PROJECT_ID>')
    ->setKey('<YOUR_API_KEY>');

$databases = new Databases($client);

$databases->upsertDocuments(
    databaseId: '<DATABASE_ID>',
    collectionId: '<COLLECTION_ID>',
    documents: [
        [
            '$id' => '<DOCUMENT_ID_OR_NEW_ID>',
            '$createdAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            '$updatedAt' => (new DateTime('<CUSTOM_DATE>'))->format(DATE_ATOM),
            // ...your attributes
        ],
    ]
);
```
```server-swift
import Appwrite
import Foundation

let client = Client()
    .setEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .setProject("<YOUR_PROJECT_ID>")
    .setKey("<YOUR_API_KEY>")

let databases = Databases(client)

let isoFormatter = ISO8601DateFormatter()
isoFormatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
let createdAt = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())
let updatedAt = isoFormatter.string(from: isoFormatter.date(from: "<CUSTOM_DATE>") ?? Date())

do {
    let bulkUpserted = try await databases.upsertDocuments(
        databaseId: "<DATABASE_ID>",
        collectionId: "<COLLECTION_ID>",
        documents: [
            [
                "$id": "<DOCUMENT_ID_OR_NEW_ID>",
                "$createdAt": createdAt,
                "$updatedAt": updatedAt,
                // ...your attributes
            ]
        ]
    )
    print("Bulk upsert:", bulkUpserted)
} catch {
    print("Bulk upsert error:", error)
}
```
```server-ruby
require 'appwrite'
require 'time'

include Appwrite

client = Client.new
    .set_endpoint('https://<REGION>.cloud.appwrite.io/v1')
    .set_project('<YOUR_PROJECT_ID>')
    .set_key('<YOUR_API_KEY>')

databases = Databases.new(client)

custom_date = Time.parse('<CUSTOM_DATE>').iso8601

databases.upsert_documents(
  database_id: '<DATABASE_ID>',
  collection_id: '<COLLECTION_ID>',
  documents: [
    {
      '$id' => '<DOCUMENT_ID_OR_NEW_ID>',
      '$createdAt' => custom_date,
      '$updatedAt' => custom_date,
      # ...your attributes
    }
  ]
)
```
```server-dotnet
using Appwrite;
using Appwrite.Models;
using Appwrite.Services;

Client client = new Client()
    .SetEndpoint("https://<REGION>.cloud.appwrite.io/v1")
    .SetProject("<YOUR_PROJECT_ID>")
    .SetKey("<YOUR_API_KEY>");

Databases databases = new Databases(client);

string createdAt = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");
string updatedAt = DateTimeOffset.Parse("<CUSTOM_DATE>").ToString("O");

await databases.UpsertDocuments(
    databaseId: "<DATABASE_ID>",
    collectionId: "<COLLECTION_ID>",
    documents: new List<object>
    {
        new Dictionary<string, object>
        {
            ["$id"] = "<DOCUMENT_ID_OR_NEW_ID>",
            ["$createdAt"] = createdAt,
            ["$updatedAt"] = updatedAt,
            // ...your attributes
        }
    }
);
```
```server-dart
import 'package:dart_appwrite/dart_appwrite.dart';

Client client = Client()
    .setEndpoint('https://<REGION>.cloud.appwrite.io/v1')
    .setProject('<YOUR_PROJECT_ID>')
    .setKey('<YOUR_API_KEY>');

Databases databases = Databases(client);

String createdAt = DateTime.parse('<CUSTOM_DATE>').toIso8601String();
String updatedAt = DateTime.parse('<CUSTOM_DATE>').toIso8601String();

await databases.upsertDocuments(
  databaseId: '<DATABASE_ID>',
  collectionId: '<COLLECTION_ID>',
  documents: [
    {
      '\$id': '<DOCUMENT_ID_OR_NEW_ID>',
      '\$createdAt': createdAt,
      '\$updatedAt': updatedAt,
      // ...your attributes
    }
  ],
);
```
```rust
use appwrite::Client;
use appwrite::services::databases::Databases;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let databases = Databases::new(&client);

    let result = databases.upsert_documents(
        "<DATABASE_ID>",
        "<COLLECTION_ID>",
        vec![
            json!({
                "$id": "<DOCUMENT_ID_OR_NEW_ID>",
                "$createdAt": "2024-01-01T00:00:00.000Z",
                "$updatedAt": "2025-01-01T00:00:00.000Z"
                // ...your attributes
            }),
        ],
        None,
    ).await?;

    println!("Bulk upsert: {:?}", result);
    Ok(())
}
```
{% /multicode %}

# Common use cases {% #use-cases %}

Custom timestamps are particularly useful in several scenarios:

## Data migration {% #data-migration %}
When migrating existing data from another system, you can preserve the original
creation and modification times:

{% multicode %}
```server-nodejs
await databases.createDocument(
  '<DATABASE_ID>',
  'blog_posts',
  sdk.ID.unique(),
  {
    '$createdAt': '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt': '<LAST_MODIFIED_ISO>',
    title: '<TITLE>',
    content: '<CONTENT>'
  }
)
```
```server-php
$databases->createDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'blog_posts',
  documentId: ID::unique(),
  [
    '$createdAt' => '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt' => '<LAST_MODIFIED_ISO>',
    'title' => '<TITLE>',
    'content' => '<CONTENT>'
  ]
);
```
```server-swift
let _ = try await databases.createDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "blog_posts",
  documentId: ID.unique(),
  data: [
    "$createdAt": "<ORIGINAL_CREATED_AT_ISO>",
    "$updatedAt": "<LAST_MODIFIED_ISO>",
    "title": "<TITLE>",
    "content": "<CONTENT>"
  ]
)
```
```server-python
databases.create_document(
  database_id='<DATABASE_ID>',
  collection_id='blog_posts',
  document_id=ID.unique(),
  data={
    '$createdAt': '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt': '<LAST_MODIFIED_ISO>',
    'title': '<TITLE>',
    'content': '<CONTENT>'
  }
)
```
```server-ruby
databases.create_document(
  database_id: '<DATABASE_ID>',
  collection_id: 'blog_posts',
  document_id: ID.unique(),
  data: {
    '$createdAt' => '<ORIGINAL_CREATED_AT_ISO>',
    '$updatedAt' => '<LAST_MODIFIED_ISO>',
    'title' => '<TITLE>',
    'content' => '<CONTENT>'
  }
)
```
```server-dotnet
await databases.CreateDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "blog_posts",
  documentId: ID.Unique(),
  data: new Dictionary<string, object>
  {
    ["$createdAt"] = "<ORIGINAL_CREATED_AT_ISO>",
    ["$updatedAt"] = "<LAST_MODIFIED_ISO>",
    ["title"] = "<TITLE>",
    ["content"] = "<CONTENT>"
  }
);
```
```server-dart
await databases.createDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'blog_posts',
  documentId: ID.unique(),
  data: {
    '\$createdAt': '<ORIGINAL_CREATED_AT_ISO>',
    '\$updatedAt': '<LAST_MODIFIED_ISO>',
    'title': '<TITLE>',
    'content': '<CONTENT>'
  },
);
```
```rust
use appwrite::Client;
use appwrite::services::databases::Databases;
use appwrite::id::ID;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let databases = Databases::new(&client);

    let result = databases.create_document(
        "<DATABASE_ID>",
        "blog_posts",
        &ID::unique(),
        json!({
            "$createdAt": "<ORIGINAL_CREATED_AT_ISO>",
            "$updatedAt": "<LAST_MODIFIED_ISO>",
            "title": "<TITLE>",
            "content": "<CONTENT>"
        }),
        None,
        None,
    ).await?;

    println!("Created: {:?}", result);
    Ok(())
}
```
{% /multicode %}

## Backdating records {% #backdating %}
For historical data entry or when creating records that represent past events:

{% multicode %}
```server-nodejs
await databases.createDocument(
  '<DATABASE_ID>',
  'transactions',
  sdk.ID.unique(),
  {
    '$createdAt': '2023-12-31T23:59:59.000Z',
    '$updatedAt': '2023-12-31T23:59:59.000Z',
    amount: 1000,
    type: 'year-end-bonus'
  }
)
```
```server-php
$databases->createDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'transactions',
  documentId: ID::unique(),
  [
    '$createdAt' => '2023-12-31T23:59:59.000Z',
    '$updatedAt' => '2023-12-31T23:59:59.000Z',
    'amount' => 1000,
    'type' => 'year-end-bonus'
  ]
);
```
```server-swift
let _ = try await databases.createDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "transactions",
  documentId: ID.unique(),
  data: [
    "$createdAt": "2023-12-31T23:59:59.000Z",
    "$updatedAt": "2023-12-31T23:59:59.000Z",
    "amount": 1000,
    "type": "year-end-bonus"
  ]
)
```
```server-python
databases.create_document(
  database_id='<DATABASE_ID>',
  collection_id='transactions',
  document_id=ID.unique(),
  data={
    '$createdAt': '2023-12-31T23:59:59.000Z',
    '$updatedAt': '2023-12-31T23:59:59.000Z',
    'amount': 1000,
    'type': 'year-end-bonus'
  }
)
```
```server-ruby
databases.create_document(
  database_id: '<DATABASE_ID>',
  collection_id: 'transactions',
  document_id: ID.unique(),
  data: {
    '$createdAt' => '2023-12-31T23:59:59.000Z',
    '$updatedAt' => '2023-12-31T23:59:59.000Z',
    'amount' => 1000,
    'type' => 'year-end-bonus'
  }
)
```
```server-dotnet
await databases.CreateDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "transactions",
  documentId: ID.Unique(),
  data: new Dictionary<string, object>
  {
    ["$createdAt"] = "2023-12-31T23:59:59.000Z",
    ["$updatedAt"] = "2023-12-31T23:59:59.000Z",
    ["amount"] = 1000,
    ["type"] = "year-end-bonus"
  }
);
```
```server-dart
await databases.createDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'transactions',
  documentId: ID.unique(),
  data: {
    '\$createdAt': '2023-12-31T23:59:59.000Z',
    '\$updatedAt': '2023-12-31T23:59:59.000Z',
    'amount': 1000,
    'type': 'year-end-bonus'
  },
);
```
```rust
use appwrite::Client;
use appwrite::services::databases::Databases;
use appwrite::id::ID;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let databases = Databases::new(&client);

    let result = databases.create_document(
        "<DATABASE_ID>",
        "transactions",
        &ID::unique(),
        json!({
            "$createdAt": "2023-12-31T23:59:59.000Z",
            "$updatedAt": "2023-12-31T23:59:59.000Z",
            "amount": 1000,
            "type": "year-end-bonus"
        }),
        None,
        None,
    ).await?;

    println!("Created: {:?}", result);
    Ok(())
}
```
{% /multicode %}

## Synchronization {% #synchronization %}
When synchronizing data between systems while maintaining timestamp consistency:

{% multicode %}
```server-nodejs
await databases.upsertDocument(
  '<DATABASE_ID>',
  'users',
  '<DOCUMENT_ID_OR_NEW_ID>',
  {
    '$updatedAt': '<EXTERNAL_LAST_MODIFIED_ISO>',
    profile: '<PROFILE_DATA>'
  }
)
```
```server-php
$databases->upsertDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'users',
  documentId: '<DOCUMENT_ID_OR_NEW_ID>',
  [
    '$updatedAt' => '<EXTERNAL_LAST_MODIFIED_ISO>',
    'profile' => '<PROFILE_DATA>'
  ]
);
```
```server-swift
let _ = try await databases.upsertDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "users",
  documentId: "<DOCUMENT_ID_OR_NEW_ID>",
  data: [
    "$updatedAt": "<EXTERNAL_LAST_MODIFIED_ISO>",
    "profile": "<PROFILE_DATA>"
  ]
)
```
```server-python
databases.upsert_document(
  database_id='<DATABASE_ID>',
  collection_id='users',
  document_id='<DOCUMENT_ID_OR_NEW_ID>',
  data={
    '$updatedAt': '<EXTERNAL_LAST_MODIFIED_ISO>',
    'profile': '<PROFILE_DATA>'
  }
)
```
```server-ruby
databases.upsert_document(
  database_id: '<DATABASE_ID>',
  collection_id: 'users',
  document_id: '<DOCUMENT_ID_OR_NEW_ID>',
  data: {
    '$updatedAt' => '<EXTERNAL_LAST_MODIFIED_ISO>',
    'profile' => '<PROFILE_DATA>'
  }
)
```
```server-dotnet
await databases.UpsertDocument(
  databaseId: "<DATABASE_ID>",
  collectionId: "users",
  documentId: "<DOCUMENT_ID_OR_NEW_ID>",
  data: new Dictionary<string, object>
  {
    ["$updatedAt"] = "<EXTERNAL_LAST_MODIFIED_ISO>",
    ["profile"] = "<PROFILE_DATA>"
  }
);
```
```server-dart
await databases.upsertDocument(
  databaseId: '<DATABASE_ID>',
  collectionId: 'users',
  documentId: '<DOCUMENT_ID_OR_NEW_ID>',
  data: {
    '\$updatedAt': '<EXTERNAL_LAST_MODIFIED_ISO>',
    'profile': '<PROFILE_DATA>'
  },
);
```
```rust
use appwrite::Client;
use appwrite::services::databases::Databases;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()
        .set_endpoint("https://<REGION>.cloud.appwrite.io/v1")
        .set_project("<PROJECT_ID>")
        .set_key("<API_KEY>");

    let databases = Databases::new(&client);

    let result = databases.upsert_document(
        "<DATABASE_ID>",
        "users",
        "<DOCUMENT_ID_OR_NEW_ID>",
        Some(json!({
            "$updatedAt": "<EXTERNAL_LAST_MODIFIED_ISO>",
            "profile": "<PROFILE_DATA>"
        })),
        None,
        None,
    ).await?;

    println!("Upserted: {:?}", result);
    Ok(())
}
```
{% /multicode %}

{% info title="Timestamp format and usage" %}
- Values must be valid ISO 8601 date-time strings (UTC recommended). Using `toISOString()` (JavaScript) or `datetime.isoformat()` (Python) is a good default.
- You can set either or both attributes as needed. If omitted, Appwrite sets them automatically.
{% /info %}