> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Manage Items

## Article: Manage Items

## Article Link: https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/manage-items.md

## Article Content:

# Manage Items

Use the [Data API](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/about-the-data-api.md) to add, update, and remove items in a site's collections. This article covers each operation and its bulk version.

The examples call the Data API from site code, such as a backend extension. They use `await`, so run them inside an `async` function. Each call succeeds only if the caller has [permission](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/introduction/about-collections.md#permissions) for the operation.

## Insert an item

[Insert Data Item](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/insert-data-item?apiView=SDK.md) adds an item to a collection. Pass the collection ID and the item's data. The response is the new item, including its [system fields](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/introduction/about-collection-fields.md#system-fields).

If you don't set `_id`, Wix generates one. If you set an `_id` that already exists in the collection, the insert fails.

This example adds a listing to the `Listings` collection:

```javascript
import { items } from "@wix/data";

const newListing = {
  _id: "listing-001", // Optional custom ID
  title: "Modern Downtown Apartment",
  price: 350000,
  bedrooms: 2,
  bathrooms: 1,
  squareFootage: 1200,
  status: "available",
};

const result = await items.insert("Listings", newListing);
console.log("Created listing:", result);
```

You can also call [Save Data Item](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/save-data-item?apiView=SDK.md) to add an item. If an item with the same `_id` already exists, it updates that item instead.

## Update an item

[Update Data Item](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/update-data-item?apiView=SDK.md) replaces an existing item. Pass the collection ID and the complete item, including its `_id`. The response is the updated item.

Update Data Item replaces the whole item. Any field that you leave out loses its value. To keep the fields you aren't changing, get the item first and update a copy of it, or [patch the item](#change-some-fields-of-an-item) instead.

This example changes the price and status of a listing:

```javascript
import { items } from "@wix/data";

// Get the current item
const existingListing = await items.get("Listings", "listing-001");
if (!existingListing) {
  throw new Error("Listing not found");
}

// Update a copy that keeps every other field
const updatedListing = {
  ...existingListing,
  price: 375000,
  status: "pending",
};

const result = await items.update("Listings", updatedListing);
console.log("Updated listing:", result);
```

## Change some fields of an item

[Patch Data Item](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/patch-data-item?apiView=SDK.md) changes only the fields that you specify and leaves the item's other fields as they are. You don't need to get the item first, and you don't overwrite changes that someone else made to other fields in the meantime.

Call `items.patch()` with the collection ID, the item's ID, and an array of field modifications. Each modification sets a `fieldPath`, an `action` such as `SET_FIELD` or `INCREMENT_FIELD`, and a `value`.

This example changes a listing's status and increments its days on market:

```javascript
import { items } from "@wix/data";

const result = await items.patch("Listings", "listing-001", [
  { fieldPath: "status", action: "SET_FIELD", value: "pending" },
  { fieldPath: "daysOnMarket", action: "INCREMENT_FIELD", value: 1 },
]);

console.log("Patched listing:", result);
```

You can't patch items in Wix app collections.

## Remove an item

[Remove Data Item](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/remove-data-item?apiView=SDK.md) deletes an item from a collection. Pass the collection ID and the item's ID. The response is the deleted item.

This example removes a listing:

```javascript
import { items } from "@wix/data";

const result = await items.remove("Listings", "listing-001");
console.log("Removed listing:", result);
```

## Work with many items at once

To add, update, or remove several items, use the bulk methods. They're faster than calling the single-item methods in a loop, and each call accepts up to 1000 items. Each single-item method has a bulk version, such as:

- [Bulk Insert Data Items](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-insert-data-items?apiView=SDK.md)
- [Bulk Update Data Items](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-update-data-items?apiView=SDK.md)
- [Bulk Remove Data Items](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/bulk-remove-data-items?apiView=SDK.md)

This example adds three listings in one call:

```javascript
import { items } from "@wix/data";

const listings = [
  { title: "Cozy Studio", price: 180000, bedrooms: 0 },
  { title: "Family Home", price: 450000, bedrooms: 3 },
  { title: "Luxury Condo", price: 650000, bedrooms: 2 },
];

const result = await items.bulkInsert("Listings", listings);
console.log(`Inserted ${result.inserted}, skipped ${result.skipped} of ${listings.length}`);

// Report the items that failed
for (const error of result.errors) {
  console.error(`Item ${error.originalIndex} failed: ${error.message}`);
}
```

The response reports the number of items inserted, and their IDs in `insertedItemIds`. Items that fail individually appear in `errors`, with their position in the request array in `originalIndex`, and the call itself still succeeds. Items whose `_id` already exists in the collection aren't inserted, and are counted in `skipped`. Skipped items don't appear in `errors`. To find them, compare the IDs you sent with `insertedItemIds`. If the caller doesn't have permission to insert items in the collection, the whole call fails.

## Handle errors

A Data API call fails, and its promise is rejected, in cases such as these:

- The caller doesn't have [permission](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/introduction/about-collections.md#permissions) for the operation.
- An insert sets an `_id` that already exists in the collection.

To handle a failure, wrap the call in `try...catch`. For the error codes and what they mean, see [Wix Data Error Codes](https://dev.wix.com/docs/api-reference/business-solutions/cms/wix-data-error-codes?apiView=SDK.md). For example:

```javascript
import { items } from "@wix/data";

try {
  await items.insert("Listings", { _id: "listing-001", title: "Garden Flat" });
} catch (error) {
  console.error("Couldn't add the listing:", error.message);
}
```

Right after you change data, a query might not include the change yet. See [Eventual consistency](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/about-the-data-api.md#eventual-consistency).

## See also

- [Query Items](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/query-items.md)
- [About Collection Fields](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/introduction/about-collection-fields.md)
- [About Data Events](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/about-data-events.md)
- [About Cached Queries](https://dev.wix.com/docs/studio-two/code-your-site/work-with-data/data-api/about-cached-queries.md)
- [Data Items API](https://dev.wix.com/docs/api-reference/business-solutions/cms/data-items/introduction?apiView=SDK.md)