Creating collection items

Three endpoints create collection items in the beta API. Use the https://api.webflow.com/beta base URL for the requests described here. Use Create Items (POST /collections/{collection_id}/items/insert) for new beta integrations. It supports the existing creation workflows and adds the ability to attach locale variants to an existing item.

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

POST /items gained an items array to create several items at once. POST /items/bulk added creation in several locales under a shared item ID.

Create Items combines these workflows in one request shape and adds locale variants to existing items. It validates every property while the older endpoints retain their existing behavior.

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 Collection Item(s).

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, without fetching and listing 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/beta/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. It cannot be combined 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 the Create Items examples for complete requests and responses.