Creating collection items

Three endpoints create collection items. Use 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

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. To create and publish with Create Items, follow it with Publish Collection Item(s).

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:

{
  "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 for the full localization workflow.