We strongly recommend reading the Introduction to Records guide first. The payload for updating a record follows the same structure as creating one, so that guide is also an essential prerequisite.

The fundamental rules for structuring field values (i.e., strings, numbers, objects, references) are the same for both creating and updating records. For a complete reference on how to format the value for every field type, please see the Field Types Overview in the main records guide.

When updating an existing record, you only need to provide the fields you want to change. Any fields you omit from your payload will remain untouched.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8

9
  const item = await client.items.update(itemId, {
10
    // we just pass the field that we want to change
11
    title: "[EDIT] My first blog post!",
12
  });
13

14
  console.log(item);
15
}
16

17
run();

1
{
2
  id: "hWl-mnkWRYmMCSTq4z_piQ",
3
  title: "My first blog post!",
4
  content: "Lorem ipsum dolor sit amet...",
5
  category: "24",
6
  image: {
7
    alt: "Alt text",
8
    title: "Image title",
9
    custom_data: {},
10
    focal_point: null,
11
    upload_id: "20042921",
12
  },
13
  meta: {
14
    created_at: "2020-04-21T07:57:11.124Z",
15
    updated_at: "2020-04-21T07:57:11.124Z",
16
    published_at: "2020-04-21T07:57:11.124Z",
17
    first_published_at: "2020-04-21T07:57:11.124Z",
18
    publication_scheduled_at: "2020-04-21T07:57:11.124Z",
19
    unpublishing_scheduled_at: "2020-04-21T07:57:11.124Z",
20
    status: "published",
21
    is_current_version_valid: true,
22
    is_published_version_valid: true,
23
    current_version: "4234",
24
    stage: null,
25
    has_children: true,
26
  },
27
  item_type: { type: "item_type", id: "DxMaW10UQiCmZcuuA-IkkA" },
28
}

The following sections highlight the rules and strategies that are specific to the update process.

Updating Block Fields

As with creation, you cannot edit blocks directly; you must update the parent record that contains them. The payload you send uses a mix of block IDs and block objects to define the desired final state.

The rules for adding, updating, keeping, deleting, and reordering blocks are covered in detail in the main records guide.

➡️ See the complete guide to Creating and Updating Blocks

When updating a block, you use destructuring to combine existing and updated content. Use Array.map() to go through the existing blocks one by one, keeping their current ordering.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  // These define what to update
8
  const recordId = "A4gkL_8pTZmcyJ-IlIEd2w"; // The record's unique ID
9
  const fieldWithBlocks = "modular_content_field"; // Which record field are the blocks in?
10
  const blockId = "ToBApjdYQaCgeFJxp_ty0A"; // ID of the block we want to update ("Example block #1")
11
  const blockFieldsToUpdate = {
12
    // Inside the block, what are we updating?
13
    title: "Example block #1 (Updated title)", // Update the title
14
  };
15

16
  // Get the current record
17
  const currentRecord = await client.items.find(recordId, {
18
    nested: true, // Also fetch the content of nested blocks, not just their IDs
19
  });
20

21
  console.log(
22
    "Current record before the update, with nested blocks",
23
    JSON.stringify(currentRecord, null, 2),
24
  );
25

26
  // Build the update before sending it
27
  const currentBlock = currentRecord[fieldWithBlocks].find(
28
    (block) => block.id === blockId,
29
  ); // The block's existing content
30
  const updatedBlock = {
31
    ...currentBlock, // Keep its existing metadata
32
    attributes: {
33
      ...currentBlock.attributes, // Keep existing attributes that we didn't update
34
      ...blockFieldsToUpdate, // Inject updated fields
35
    },
36
  };
37
  const updatedFieldWithBlocks = currentRecord[fieldWithBlocks].map(
38
    (
39
      block, // Map through existing blocks so we keep their ordering
40
    ) =>
41
      block.id === updatedBlock.id
42
        ? updatedBlock //  If it's the block we want to update, inject the updated data
43
        : block.id, // Otherwise, just provide the old block's ID and the API will know to keep it unchanged
44
  );
45

46
  // Perform the update by actually sending what we built to the API
47
  const updatedRecord = await client.items.update(recordId, {
48
    [fieldWithBlocks]: updatedFieldWithBlocks, // The record field to update
49
    // We don't have to specify the other fields. The API will keep them the same.
50
  });
51

52
  console.log(
53
    "Updated record. Only block IDs are returned, not their content.",
54
    updatedRecord,
55
  );
56
}
57

58
run();

1
// Current record before the update, with nested blocks
2
{
3
  id: "A4gkL_8pTZmcyJ-IlIEd2w",
4
  type: "item",
5
  title: "This is an example record with blocks in a modular content field",
6
  modular_content_field: [
7
    {
8
      type: "item",
9
      attributes: {
10
        title: "Example block #1",
11
      },
12
      relationships: {
13
        item_type: {
14
          data: {
15
            id: "cR-9e-65SNat84KEs5M22w",
16
            type: "item_type",
17
          },
18
        },
19
      },
20
      id: "ToBApjdYQaCgeFJxp_ty0A",
21
    },
22
    {
23
      type: "item",
24
      attributes: {
25
        title: "Example block #2",
26
      },
27
      relationships: {
28
        item_type: {
29
          data: {
30
            id: "cR-9e-65SNat84KEs5M22w",
31
            type: "item_type",
32
          },
33
        },
34
      },
35
      id: "YGrrPYrkSNaq-dBaP7aSaQ",
36
    },
37
  ],
38
  item_type: {
39
    id: "LvTZuGYRTQO9aBVk0g35Jw",
40
    type: "item_type",
41
  },
42
  creator: {
43
    id: "627975",
44
    type: "organization",
45
  },
46
  meta: {
47
    created_at: "2024-09-06T17:19:59.151+01:00",
48
    updated_at: "2024-10-03T00:41:15.497+01:00",
49
    published_at: "2024-10-03T00:41:15.538+01:00",
50
    publication_scheduled_at: null,
51
    unpublishing_scheduled_at: null,
52
    first_published_at: "2024-09-06T17:19:59.215+01:00",
53
    is_valid: true,
54
    is_current_version_valid: true,
55
    is_published_version_valid: true,
56
    status: "published",
57
    current_version: "EFYp72wJQf24L_jL1C1_tw",
58
    stage: null,
59
  },
60
}
61

62

63
/* Updated record. Only block IDs are returned, not their content.
64
{
65
  id: 'A4gkL_8pTZmcyJ-IlIEd2w',
66
  type: 'item',
67
  title: 'This is an example record with blocks in a modular content field',
68
  modular_content_field: [ 'ToBApjdYQaCgeFJxp_ty0A', 'YGrrPYrkSNaq-dBaP7aSaQ' ],
69
  item_type: { id: 'LvTZuGYRTQO9aBVk0g35Jw', type: 'item_type' },
70
  creator: { id: '627975', type: 'organization' },
71
  meta: {
72
    created_at: '2024-09-06T17:19:59.151+01:00',
73
    updated_at: '2024-10-03T00:41:21.730+01:00',
74
    published_at: '2024-10-03T00:41:21.784+01:00',
75
    publication_scheduled_at: null,
76
    unpublishing_scheduled_at: null,
77
    first_published_at: '2024-09-06T17:19:59.215+01:00',
78
    is_valid: true,
79
    is_current_version_valid: true,
80
    is_published_version_valid: true,
81
    status: 'published',
82
    current_version: 'Af6ykuN7S6WGMcwD3XZUdQ',
83
    stage: null
84
  }
85
}
86
*/

You can reorder block records by changing their IDs position in the modular content field array.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8
  const item = await client.items.update(itemId, {
9
    // previous order was ['565346546', '565346547', '565346548']
10
    content: ["565346548", "565346547", "565346546"],
11
  });
12

13
  console.log(item);
14
}
15

16
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: "Title",
5
  content: ["565346548", "565346547", "565346546"],
6
  meta: {
7
    /* ... */
8
  },
9
  item_type: { type: "item_type", id: "44" },
10
  creator: { type: "access_token", id: "312" },
11
};

In this case, you must not pass an ID to buildBlockRecord.

It's not required the presence of all the fields in the payload. If it's easier for you to include all of them, just pass null, as it's a valid value for every field type.

When a field is not present in the payload, or its value is null, then the field's default value will be used (if available).

1
import { buildClient, buildBlockRecord } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8
  const item = await client.items.update(itemId, {
9
    // previous order was ['565346546', '565346547', '565346548']
10
    content: ["565346548", "565346547", "565346546"],
11
  });
12

13
  console.log(item);
14
}
15

16
run();
17

18
async function run() {
19
  // Make sure the API token has access to the CMA, and is stored securely
20
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
21

22
  const itemId = "4235";
23
  const blockModelId = "23455234";
24

25
  const item = await client.items.update(itemId, {
26
    content: [
27
      // new block record:
28
      buildBlockRecord({
29
        item_type: { type: "item_type", id: blockModelId },
30
        text: "new block record text",
31
        subtext: "another text",
32
      }),
33
      // existing block record IDs:
34
      "565346546",
35
      "565346547",
36
      "565346548",
37
    ],
38
  });
39

40
  console.log(item);
41
}
42

43
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: "Title",
5
  // block '565346549' has been added:
6
  content: ["565346549", "565346546", "565346547", "565346548"],
7
  meta: {
8
    /* ... */
9
  },
10
  item_type: { type: "item_type", id: "44" },
11
  creator: { type: "access_token", id: "312" },
12
};

To delete a block record, remove its ID from the modular content field array.

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8

9
  const item = await client.items.update(itemId, {
10
    // previous value was ['565346546', '565346547', '565346548'], let's remove '565346547'
11
    content: ["565346546", "565346548"],
12
  });
13

14
  console.log(item);
15
}
16

17
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: "Title",
5
  // block '565346547' has been removed!
6
  content: ["565346546", "565346548"],
7
  meta: {
8
    /* ... */
9
  },
10
  item_type: { type: "item_type", id: "44" },
11
  creator: { type: "access_token", id: "312" },
12
};

Updating Localized Fields

➡️ Before proceeding, ensure you have read the general guide on Localization

When you send an update request, the API follows these strict rules.

Rule 1: To change a locale value, send the whole set

When you update a translated field, you must provide the entire object for that field, including all the languages you want to keep unchanged. You can't just send the one language you're changing.

Correct: To update the Italian title, you send both English and Italian:
1 { 2 "title": { 3 "en": "Hello World", 4 "it": "Ciao a tutti! (Updated)" 5 } 6 }
Incorrect: If you only send the Italian value, the API will assume you want to delete the English one!

Rule 2: To add/remove a language, send all translated fields

This is the only time you can't just send the one field you're changing. To add or remove a language from an entire record, you must include all translated fields in your request. This is to enforce the Locale Sync Rule and ensure all fields remain consistent.

Example: To add French to a blog post that already has a translated title and content, your request must include both fields with the new fr locale.

Rule 3: Limited permissions? Only send what you can manage

If your API key only has permission for certain languages (e.g., only English), you must only include those languages in your update. The system is smart and will automatically protect and preserve the content for the languages you can't access (like Italian or French).

Update scenarios at a glance

This table shows what happens in different situations. The key takeaway is that your update payload defines the new final state for the languages you are allowed to manage.

Your Role manages	Record currently Has	Your payload sends	Result
English	English	English	✅ English is updated.
English, Italian	English	English, Italian	✅ English is updated. ➕ Italian is added.
English, Italian	English, Italian	English	✅ English is updated. ➖ Italian is removed.
English, Italian	English, Italian	English, Italian	✅ English is updated. ✅ Italian is updated.
Eng, Ita, Fre	English, Italian	English, French	✅ English is updated. ➖ Italian is removed. ➕ French is added.
English	English, Italian	English	✅ English is updated. 🛡️ Italian is preserved.
English, Italian	English, French	English, Italian	✅ English is updated. 🛡️ French is preserved. ➕ Italian is added.
English, Italian	English, French	Italian	➖ English is removed. 🛡️ French is preserved. ➕ Italian is added.

Block fields

The rules about localization work in combination with the rules for updating blocks: you use full block objects to create/update and block IDs to leave unchanged, but you do so within the object for a specific locale.

Example: Updating a block in one locale

This payload updates the title of an existing block in the en locale, while leaving the second English block and all Italian blocks untouched. The it locale needs to be included in the payload, or the Italian locale will be deleted!

1
{
2
  "content_blocks": {
3
    "en": [
4
      {
5
        "id": "dhVR2HqgRVCTGFi0bWqLqA",
6
        "type": "item",
7
        "attributes": { "title": "Updated English Title" }
8
      },
9
      "kL9mN3pQrStUvWxYzAbCdE"
10
    ],
11
    "it": [
12
      "dhVR2HqgRVCTGFi_0bWqLqA",
13
      "kL9mN3pQrStUvWxYzAbCdE"
14
    ]
15
  }
16
}

Example: Adding a new block to one locale

This payload adds a new block to the it locale only. The en locale needs to be included in the payload, or the Italian locale will be deleted!

1
{
2
  "content_blocks": {
3
    "en": [
4
      "dhVR2HqgRVCTGFi_0bWqLqA",
5
      "kL9mN3pQrStUvWxYzAbCdE"
6
    ],
7
    "it": [
8
      "fG8hI1jKlMnOpQrStUvWxY",
9
      {
10
        "type": "item",
11
        "attributes": { "title": "Nuovo Blocco" },
12
        "relationships": {
13
          "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } }
14
        }
15
      },
16
      "dhVR2HqgRVCTGFi0bWqLqA"
17
    ]
18
  }
19
}

Example: Adding a new locale

To add a new locale to an existing record, you must provide values for all localized fields for that new locale, and include existing locales that you want to preserve.

1
{
2
  "title": {
3
    "en": "English Title",
4
    "fr": "Titre Français",
5
  },
6
  "content_blocks": {
7
    "en": [
8
      "dhVR2HqgRVCTGFi_0bWqLqA",
9
      "kL9mN3pQrStUvWxYzAbCdE"
10
    ],
11
    "fr": [
12
      {
13
        "type": "item",
14
        "attributes": { "title": "Nouveau Bloc Français" },
15
        "relationships": {
16
          "item_type": { "data": { "id": "BxZ9Y2aKQVeTnM4hP8wLpD", "type": "item_type" } }
17
        }
18
      }
19
    ]
20
  }
21
}

If the 'All locales required?' option in a model is turned off, then its records do not need all environment's locales to be defined for localized fields, so you're free to add/remove locales during an update operation.

Suppose your environment's locales are English, Italian and German (['en', 'it', 'de']) and the following record currently defines en and it locales on its localized fields (title and content):

1
const item = {
2
  id: '4235',
3
  // localized field
4
  title: {
5
    en: 'My title',
6
    it: 'Il mio titolo'
7
  },
8
  // localized field
9
  content: {
10
    en: 'Article content',
11
    it: 'Contenuto articolo',
12
  },
13
  // non-localized field
14
  votes_count: 10,
15
  meta: { /* ... */ },
16
  item_type: { type: 'item_type', id: '44' },
17
  creator: { type: 'access_token', id: '312' },
18
}

To add the de locale to this record, you have to send an update request containing all localized fields. For each one of these, you must define the exiting locales plus the ones you want to add:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8

9
  const item = await client.items.update(itemId, {
10
    title: {
11
      en: "My title",
12
      it: "Il mio titolo",
13
      de: "Mein Titel",
14
    },
15
    content: {
16
      en: "Article content",
17
      it: "Contenuto articolo",
18
      de: "Artikelinhalt",
19
    },
20
  });
21

22
  console.log(item);
23
}
24

25
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: {
5
    en: "My title",
6
    it: "Il mio titolo",
7
    de: "Mein Titel",
8
  },
9
  content: {
10
    en: "Article content",
11
    it: "Contenuto dell'articolo",
12
    de: "Artikelinhalt",
13
  },
14
  votes_count: 10,
15
  meta: {
16
    /* ... */
17
  },
18
  item_type: { type: "item_type", id: "44" },
19
  creator: { type: "access_token", id: "312" },
20
};

Let's suppose your environment's locales are English (en), Italian (it) and German (de) and the following record currently defines en and it locales on its localized fields (title and content):

1
const item = {
2
  id: '4235',
3
  // localized field
4
  title: {
5
    en: 'My title',
6
    it: 'Il mio titolo'
7
  },
8
  // localized field
9
  content: {
10
    en: 'Article content',
11
    it: 'Contenuto articolo',
12
  },
13
  // non-localized field
14
  votes_count: 10,
15
  meta: { /* ... */ },
16
  item_type: { type: 'item_type', id: '44' },
17
  creator: { type: 'access_token', id: '312' },
18
}

To remove the it locale from this record, you have to send an update request containing all localized fields. For each one fo these, you must define the exiting locales, except the ones you want to remove:

1
import { buildClient } from "@datocms/cma-client-node";
2

3
async function run() {
4
  // Make sure the API token has access to the CMA, and is stored securely
5
  const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
6

7
  const itemId = "4235";
8
  const item = await client.items.update(itemId, {
9
    title: {
10
      en: "My title",
11
    },
12
    content: {
13
      en: "Article content",
14
    },
15
  });
16

17
  console.log(item);
18
}
19

20
run();

1
const result = {
2
  type: "item",
3
  id: "4235",
4
  title: {
5
    en: "My title",
6
  },
7
  content: {
8
    en: "Article content",
9
  },
10
  votes_count: 10,
11
  meta: {
12
    /* ... */
13
  },
14
  item_type: { type: "item_type", id: "44" },
15
  creator: { type: "access_token", id: "312" },
16
};

Optimistic Locking

To prevent clients from accidentally overwriting each other's changes, the update endpoint supports optimistic locking. You can include the record's current version number in the meta object of your payload.

If the version on the server is newer than the one you provide, the API will reject the update with a 422 STALE_ITEM_VERSION error, indicating that the record has been modified since you last fetched it.

1
import { ApiError, buildClient } from "datocms-client";
2

3
// Make sure the API token has access to the CMA, and is stored securely
4
const client = buildClient({ apiToken: process.env.DATOCMS_API_TOKEN });
5

6
async function updateRecordByIncrementingCounter(itemId) {
7
  // first we get the record we want to update
8
  const record = await client.items.find(itemId);
9

10
  try {
11
    // now we increment the counter value, passing the current version
12
    // to enable optimistic-locking
13
    client.items.update(itemId, {
14
      counter: record.counter + 1,
15
      meta: { current_version: record.meta.current_version },
16
    });
17

18
    console.log("Done!");
19
  } catch (e) {
20
    // if we get a STALE_ITEM_VERSION error, this means that the
21
    // the record changed in-between the find and update operations, so we have
22
    // to fetch the latest version of the record and try again
23
    if (e instanceof ApiError && e.findError("STALE_ITEM_VERSION")) {
24
      console.log("Stale version, retrying...");
25
      return updateRecordByIncrementingCounter();
26
    }
27

28
    throw e;
29
  }
30
}
31

32
await updateRecordByIncrementingCounter("1230982");

1
> node example.js
2

3
Stale version, retrying...
4
Stale version, retrying...
5
Done!

Body parameters

meta.created_at string Optional

Date of creation

meta.first_published_at null, string Optional

Date of first publication

meta.current_version string Optional

The ID of the current record version (for optimistic locking, see the example)

Example:

"4234"

meta.stage string, null Optional

The new stage to move the record to

item_type Optional

The record's model

Type: ResourceLinkage<"item_type">

creator Optional

The entity (account/collaborator/access token/sso user) who created the record

Type: ResourceLinkage<"account">, ResourceLinkage<"access_token">, ResourceLinkage<"user">, ResourceLinkage<"sso_user">, ResourceLinkage<"organization">

Returns

Returns a resource object of type item

Did this doc help you?

Need help?

Explore our forum, contact support, or connect with our sales team . You can also chat live with other users in our Slack channel.