> This page is for Data API, version v2 (default).
> For other versions, use one of these documentation indexes:
> - v2 (default): https://developers.webflow.com/data/v2.0.0/llms.txt
> - v2 Beta: https://developers.webflow.com/data/v2.0.0-beta/llms.txt
> - v1: https://developers.webflow.com/data/v1.0.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.webflow.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.webflow.com/_mcp/server.

# Creating collection items

> Which CMS API endpoint to use to create collection items, how the older POST /items and POST /items/bulk endpoints differ, and how to move to Create Items.

Three endpoints create collection items. Use [Create Items](/data/reference/cms/collection-items/staged-items/create-items) (`POST /collections/{collection_id}/items/insert`) for new integrations. It covers everything the two older endpoints do, adds the ability to attach locale variants to an existing item, and is where new CMS create features will land.

The older endpoints keep working. They're no longer listed in the reference navigation, so this page links to their documentation and explains how each maps to Create Items.

## Which endpoint

| Endpoint             | Use it for            | Locales                                                                                                            | Reference                                                                               |
| -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| `POST /items/insert` | All new work          | Selected locales or all current site locales per new item, linked by one ID. Can add variants to an existing item. | [Create Items](/data/reference/cms/collection-items/staged-items/create-items)          |
| `POST /items`        | Existing integrations | One locale per item. Items aren't linked across locales.                                                           | [POST /items](/data/reference/cms/collection-items/staged-items/create-item)            |
| `POST /items/bulk`   | Existing integrations | Same content fanned out to several locales, linked by one item ID.                                                 | [POST /items/bulk](/data/reference/cms/collection-items/staged-items/create-items-bulk) |

All three create staged items, require the `cms:write` scope, and create items as drafts unless the request sets `isDraft: false`. Each can create up to 100 items in a request. The limit counts every item created, so an item created in three locales counts as three.

A live variant exists only for [`POST /items/live`](/data/reference/cms/collection-items/live-items/create-item-live). To create and publish with Create Items, follow it with [Publish Collection Item(s)](/data/reference/cms/collection-items/staged-items/publish-item).

## Why there are three

Create Items grew by extension. `POST /items` gained an `items` array so it could create several items at once, and `POST /items/bulk` was added so one item could be created in several locales under a shared ID. Each change kept existing requests working, and each left the endpoints accepting more than they validate. Adding locale linking to either one would have changed the result of requests that succeed today, so Create Items starts fresh: strict validation, one request shape, and no callers to break.

## Moving to Create Items

Create Items takes an `items` array where every entry is one item and the locales to create it in.

* **Single item on `POST /items`:** Move the top-level `fieldData` into one `items` entry. Replace `cmsLocaleId` with `cmsLocaleIds: ["<id>"]`.
* **`items` array on `POST /items`:** Keep the array. Replace each entry's `cmsLocaleId` with a one-element `cmsLocaleIds`.
* **`POST /items/bulk` with a `fieldData` object:** Send one entry with that `fieldData` and the same `cmsLocaleIds`. The item is created in every listed locale under one ID, exactly as before.
* **`POST /items/bulk` with a `fieldData` array:** Send one entry per array element, each carrying the same `cmsLocaleIds`.
* **`POST /items/live`:** No direct equivalent. Call Create Items, then Publish Items.

Create Items accepts `cmsLocaleIds` (plural) to select locales on each entry, or `allCmsLocales: true` to create a new item in every current site locale. Omit both selectors to create a new item in the primary locale only. Unrecognized properties, including the singular `cmsLocaleId`, return a `400`.

## What Create Items adds

* **New items in every current site locale.** Set `allCmsLocales: true` on an entry to create linked variants with the same `fieldData` in every locale, including the primary locale. You don't need to fetch and list locale IDs.
* **Locale variants of an existing item.** Set `id` to the item's ID and list the new locales in `cmsLocaleIds`. The variants share that ID.
* **Different content per locale.** Send several entries with the same `id`, one locale each, with their own `fieldData`.

### Create a new item in all locales

Send this body to `POST https://api.webflow.com/v2/collections/{collection_id}/items/insert`:

```json
{
  "items": [
    {
      "allCmsLocales": true,
      "fieldData": {
        "name": "Mostly Harmless",
        "slug": "mostly-harmless"
      }
    }
  ]
}
```

The response contains one item per current site locale, all sharing the same new `id` and content, with a different `cmsLocaleId` for each variant. On a site with three locales, this entry counts as three items toward the 100-item request limit. The limit applies across all entries, including requests that mix `allCmsLocales`, explicit locale IDs, and primary-locale items.

`allCmsLocales` accepts only `true`. Omit it instead of sending `false`; `false`, strings, and `null` return a `400`. You can't combine it with `cmsLocaleIds` (even an empty array) or `id` on the same entry. To add locales to an existing item, use `id` with explicit `cmsLocaleIds`.

See [Localization with the CMS API](/data/docs/working-with-the-cms/localization) for the full localization workflow.