Webflow CMS Bulk Import & Sync

Bulk import, update, and upsert Webflow CMS items from Apify datasets or JSON. Built for recurring high-volume workflows such as job boards, directories, real-estate listings, events, content feeds, and scraped datasets.

Why use it

Instead of manually importing CSV files or writing one-off Webflow scripts, connect an Apify dataset to a Webflow CMS collection and run the Actor whenever your source data changes.

• Create, update, or upsert CMS items
• Read large Apify datasets in pages
• Use Webflow bulk writes of up to 100 items per request
• Match existing records by slug, a custom field, or Webflow item id
• Map nested source fields with dot paths
• Skip unchanged items to reduce API calls
• Normalize numbers, booleans, dates, images, option values, and references
• Automatically generate missing slugs
• Retry 429 and transient 5xx responses
• Respect Webflow's Retry-After header
• Isolate bad rows when one record causes a bulk request to fail
• Optional item publishing after sync
• Safe dry-run preview before any CMS changes
• Structured dataset results, run summary, and detected collection schema

Safe default run

The default input uses a built-in demo dataset and forces dry-run mode. It does not require a Webflow token and never changes a Webflow site.

This makes the Actor's first Store run useful instead of failing because credentials are missing.

Quick start with an Apify dataset

1. Create a Webflow API token with cms:read and cms:write access.
2. Copy the destination Webflow CMS collection ID.
3. Set Source to Apify dataset.
4. Enter the source dataset ID or name.
5. Configure field mapping.
6. Keep Dry run enabled for the first run.
7. Review the output, then disable dry run to sync.

Example input:

{
  "sourceType": "apifyDataset",
  "sourceDatasetId": "YOUR_DATASET_ID",
  "webflowToken": "YOUR_WEBFLOW_TOKEN",
  "collectionId": "YOUR_COLLECTION_ID",
  "mode": "upsert",
  "matchField": "slug",
  "fieldMapping": {
    "name": "title",
    "slug": "slug",
    "description": "content.html",
    "company": "company.name",
    "salary": "salary.amount",
    "featured": "isFeatured"
  },
  "dryRun": true,
  "publish": false
}

Field mapping

fieldMapping is a JSON object where:

Webflow field slug -> source property path

Dot paths are supported:

{
  "name": "job.title",
  "slug": "job.slug",
  "company": "company.name"
}

With Auto-map same-name fields enabled, source keys that already match Webflow field slugs are also mapped automatically.

Supported Webflow field handling

The Actor reads the collection schema before syncing and uses it to normalize values.

Webflow field	Accepted source value
Plain/Rich text, link, email, phone, color, video	string-compatible value
Number	number or numeric string
Switch / Bool	boolean, yes/no, true/false, 1/0
DateTime	valid date/time converted to ISO 8601
Image / File	public URL or { "url": ..., "alt": ... } / fileId object
Multi-image	array of public URLs or asset objects
Option	option ID or option name; names are resolved from the collection schema
Reference	Webflow item ID
Multi-reference	array of Webflow item IDs

Reference fields intentionally require item IDs in v1. The Actor does not guess which related record a name should reference.

Sync modes

Upsert

Recommended for recurring data pipelines.

• Match found -> update if mapped values changed
• No match -> create
• Unchanged -> skip the API write

Create only

Creates new records and never updates a matched record. Existing matches can be marked failed or skipped.

Update only

Updates matched records and never creates missing ones.

Matching and deduplication

slug is the safest default match field for most Webflow collections.

You can also use a stable custom key such as:

external-id
source-id
listing-id
job-id

If a custom match field exists in the source, the Actor persists it to newly created items even when same-name auto-mapping is disabled. This keeps future upsert runs matchable.

Duplicate source match values are detected. Ambiguous existing Webflow matches are rejected instead of updating an arbitrary record.

Dry run

Dry run still reads the Webflow collection schema and existing items, so its decisions reflect the real collection. It then outputs:

• would_create
• would_update
• unchanged
• skipped
• failed

No CMS writes or publishes are performed.

Publishing

Writes are staged first. When Publish synced items is enabled, successfully created or updated item IDs are sent to Webflow's CMS item publish endpoint.

If Webflow only confirms part of a bulk publish, the Actor retries the unconfirmed IDs individually so one publishing problem does not hide the others.

Failure isolation

A normal bulk integration can lose an entire 100-item batch because one record is invalid.

This Actor handles row-specific 400, 409, and 422 errors by recursively splitting the failed batch until it identifies the bad row. Valid records in the same original batch can still succeed.

Authentication, permission, collection-not-found, exhausted rate-limit, and persistent server/network failures remain fatal because retrying every row would only waste requests.

Output

The default dataset contains one row per processed source record with:

• source index
• status
• match field/value
• Webflow item ID
• publishing result
• mapped field count
• optionally mapped fieldData
• warnings
• row-level error code/message
• processing timestamp

The key-value store also contains:

• SUMMARY — counts and run metadata
• COLLECTION_SCHEMA — detected Webflow fields and types

Status values

Status	Meaning
created	Created in Webflow
updated	Existing Webflow item changed
would_create	Dry-run create preview
would_update	Dry-run update preview
unchanged	Mapped values already matched
skipped	Deliberately skipped duplicate/existing row
failed	Row could not be validated or synced

Large datasets

The source Apify dataset is streamed in pages instead of being loaded completely into memory. Webflow items are indexed for matching, and source rows are processed in configurable batches up to Webflow's current 100-item bulk limit.

The included test suite verifies a simulated 10,000-item import with 100 correctly bounded bulk requests.

Webflow API behavior used

This Actor targets the current Webflow Data API v2 CMS endpoints:

• GET /v2/collections/{collection_id}
• GET /v2/collections/{collection_id}/items
• POST /v2/collections/{collection_id}/items/insert
• PATCH /v2/collections/{collection_id}/items
• POST /v2/collections/{collection_id}/items/publish

Webflow currently limits CMS bulk create/update operations to 100 items per request and returns 429 Too Many Requests with Retry-After when rate limits are exceeded.

Security

• Webflow token is an Apify secret input.
• Token contents are never written to dataset rows, summaries, or logs.
• Debug logging only records request method/path and retry attempts.
• The default run is read/write-safe because it uses demo data and dry-run mode.

Deliberate v1 boundaries

• One Webflow collection per Actor run
• Primary CMS locale only
• Does not delete Webflow items missing from the source
• Reference and multi-reference values require Webflow item IDs
• CMS collections only; not Webflow Ecommerce products or static pages

These boundaries keep bulk sync predictable and safe.

Local development

npm install
npm run check
npm test
npm start

The automated suite covers input defaults, mapping, data coercion, pagination, Webflow endpoint payloads, 429 retry behavior, batching, bad-row isolation, publishing fallback, source dataset paging, and a 10,000-record simulated import.