How to Use the Webflow API: Step by Step Guide

Dozie Okeke
June 6, 2022
Try Memberstack for Free!

TABLE OF CONTENTS
GET STARTED
Try Memberstack

Learn how to use Webflow's APIs to manage collection items, and trigger actions when events occur – such as sending promotional emails to paying Memberstack members each time a new product item is added to a Webflow collection.

What is the Webflow API?

The Webflow API enables you to programatically store and read site data in the CMS associated with your Webflow site.

ezgif-1-d40c3ce3f0

It's an HTTP API that provides resources and methods to:

  • Get and list your sites, their domains, and collections. A collection can be visualised as an excel sheet, and in the CMS for each Webflow site we can have multiple collections.
  • Create, list, retrieve, and modify items in any of your site's Ecommerce or non-Ecommerce collections. An Ecommerce collection is a special type of collection created by Webflow for sellable items. Items in these collections are referred to as products, and are always linked to items in an SKU collection.
  • Create, list, retrieve and remove Webhooks.

What can you do with the Webflow API

The API enables you to:

  • import data from an existing database into your Webflow CMS.
  • export Webflow content to use in other apps.
  • synchronise with an existing CMS.
  • pull your Webflow CMS data in a mobile app.
  • fire actions when user events occur in Webflow.

Getting Started with the Webflow API

ezgif-2-e30272c034

This guide explains how to:

  • get authenticated access to Webflow's API using either OAuth or a personal API Key
  • add new ecommerce products using Webflow's APIs
  • poll your ecommerce collection for updates using Webflow's APIs
  • avoid rate limits using Webflow's webhooks

Along the way we'll imagine we're working on a simple app built with Webflow + Memberstack's seamless auth and payments service, to illustrate how important aspects of the Webflow API work.

At the end of the guide you will understand how to use Webflow's APIs to manage collection items, and trigger actions when events occur – such as sending promotional emails to paying Memberstack members each time a new product item is added to a Webflow collection.

Get a Webflow + Memberstack account

To use the Webflow APIs and follow along with this guide we suggest creating both Memberstack and Webflow accounts.

How to get the Webflow API auth tokens

Option A - Implement the Webflow OAuth flow

Use this option if you're building an app which needs access to other people's Webflow accounts.

1 - First register an application to get a client id

Open the integrations tab of account settings and click the “Register New Application” button. Fill in the details and copy the generated client id.

ezgif-2-e30272c034
image.png
image.png

2 - Plug the client id into Webflow's OAuth URL

The final URL should look like this, but substituted with your own client_id and optional state parameters:

https://webflow.com/oauth/authorize/?client_id=ed57c4a2324c5a0a5c183b0a882432cf065f3f42e23300800489bc517e7000d7&response_type=code

3 - Use Webflow's OAuth URL to retrieve an authorisation code from users

When users click it, they'll be prompted to authorise your application, and when they do, an authorisation code will be returned as a URL parameter

ezgif-5-78822fc98f

4 Use the authorisation code to obtain an access token

Once your application has retrieved the authorisation token from the redirect URLs code parameter, it can request for the Webflow API access token.


// Request
curl https://api.webflow.com/oauth/access_token \
    -d client_id="8151ef1a5613fe2340e62395008595d23b31e15edfd0c5b1a49ad3560d5ca16b" \
    -d client_secret="94cd4c5ac02604185a4ce2bca3f46c14c60ed9c5df86f76b43089997d8febfcf" \
    -d code="c64a5accd53542c485e97a90e287ac18f522ec828947696fb13feb5255e3c42f" \
    -d grant_type="authorization_code" \


// Response
{
  "token_type": "bearer",
  "access_token": "79f75b59455167fdb72d3f777409d390a3a93c048539ec6ddc34327cb312627e"
}

Option B - Issue a personal API key

Use this option If you are developing a private integration to Webflow and are only interacting with your own account.

1. Go to project settings

2. Click integrations

3. Scroll down to generate an API key

Note that these keys can only be generated on a per-site basis.

personal-api-key
image.png
image.png
image.png

What are the most important parts of the Webflow API?

Webflow CMS Collection Fields

Fields are the Webflow equivalent of spreadsheet columns and are by far the most important part of the Webflow API.

Without fields you can't have items – the Webflow equivalent of rows.

Without items you can't have collections – the Webflow equivalent of a single spreadsheet.

And without collections, you can't have a CMS – the Webflow equivalent of an excel file.

Everything we do with the Webflow API is about managing fields, but ironically we can't programatically create fields with the Webflow API. So to really get started with the Webflow API it's very important that you understand how to create fields.

How to Create Fields

There is ONLY ONE WAY to do this, and it involves using the Webflow UI.

1 - Create a Webflow site

2 - Create a collection in the Webflow site

This can be one of two types:

  • a generic collection that can contain any item types.
  • a Webflow ecommerce collection that comes with predefined Webflow product fields.

Creating a generic collection

  1. In the Webflow designer click on CMS
  2. Click create new collection
  3. Choose a template or fill in the fields to create a custom collection
image.png
image.png
image.png
image.png
image.png

Creating an ecommerce collection

  1. In the Webflow Designer click on Ecommerce
  2. You'll be warned that these collections cannot be deleted
  3. When you click Let's Do This a Product collection and a Categories collection are created for you
image.png
image.png

3 - Define the fields in your collection

As you define a field you will need to choose the field type.

image.png

Field types range from the typical types – Image, Color, Bool, Number, Video, to types that allow you to work across collections such as:

  • ItemRef: Field containing item referenced from another Collection
  • ItemRefSet: Field containing multiple items referenced from another Collection
  • ExtFileRef: An object containing name (string) and URL (string) properties

For a complete reference please see the official documentation.

Webflow CMS Collection Items

Items are the next most important aspect of the Webflow API and all items belong in a collection.

How to add a new Item to a collection

Here's how to add a new one to an existing collection:

1. Retrieve the ID of the collection you want to add the item to

The simple way to do this is to copy it from the collection settings.

image.png

2. Use the Create New Collection Item Endpoint

Make a POST request to

https://api.webflow.com/collections/:collection_id/items

In the request:

  • replace :collection_id with your collection's ID

Example request URL

https://api.webflow.com/collections/580e63fc8c9a982ac9b8b745/items

  • set the auth token we obtained earlier, in the request's Authorization header, remembering to prepend the string with Bearer.

Example authorization header:

Authorization: Bearer d59f681797fbb3758b2a0ce8e5f31a199e2733110cb468bb2bb0d77f23417b32

  • set your Accept-Version and Content-Type headers.

COPY


"accept-version: 1.0.0"
"Content-Type: application/json"

  • Populate the values in the item object you want to add, and pass it in the body of your request. Its property names should match the names of the collections's fields.

Example JSON body:


{"fields": {
        "name": "Exciting blog post title",
        "slug": "exciting-post",
        "_archived": false,
        "_draft": false,
        "color": "#a98080",
        "author": "580e640c8c9a982ac9b8b778",
        "post-body": "<p>Blog post contents...</p>",
        "post-summary": "Summary of exciting blog post",
        "main-image": "580e63fe8c9a982ac9b8b749"
   }
}


  • Send your request

Here's an example request:


curl 'https://api.webflow.com/collections/580e63fc8c9a982ac9b8b745/items' \
  -H "Authorization: Bearer d59f681797fbb3758b2a0ce8e5f31a199e2733110cb468bb2bb0d77f23417b32" \
  -H 'accept-version: 1.0.0' \
  -H "Content-Type: application/json" \
  --data-binary $'{
      "fields": {
        "name": "Exciting blog post title",
        "slug": "exciting-post",
        "_archived": false,
        "_draft": false,
        "color": "#a98080",
        "author": "580e640c8c9a982ac9b8b778",
        "post-body": "<p>Blog post contents...</p>",
        "post-summary": "Summary of exciting blog post",
        "main-image": "580e63fe8c9a982ac9b8b749"
      }
    }'


How to list all items in a collection

1. Retrieve the collection's ID

2. Use the Get All Items For a Collection Endpoint

Make a GET request to

https://api.webflow.com/collections/:collection_id/items

In the request:

  • replace :collection_id with your collection's ID
  • add a rate limit url query parameter limit. The limit parameter specifies the maximum number of items to be retured. The max limit is 100.

Example request URL

https://api.webflow.com/collections/580e63fc8c9a982ac9b8b745/items?limit=1

  • set the auth token we obtained earlier, in the request's Authorization header, remembering to prepend the string with Bearer.

Example authorization header:

Authorization: Bearer d59f681797fbb3758b2a0ce8e5f31a199e2733110cb468bb2bb0d77f23417b32

  • set your Accept-Version headers.

"accept-version: 1.0.0"


  • Send your request

Here's an example request:


curl https://api.webflow.com/collections/580e63fc8c9a982ac9b8b745/items?limit=1 \
    -H "Authorization: Bearer d59f681797fbb3758b2a0ce8e5f31a199e2733110cb468bb2bb0d77f23417b32" \
    -H 'accept-version: 1.0.0'


If you have more than 100 items in your collection you will need to paginate, in which case you will need to use the offset URL query parameter. Assume you have 500 items. To get the 5th page of items one option is to set limit=100, and offset: 400

Here's an example request:


curl https://api.webflow.com/collections/580e63fc8c9a982ac9b8b745/items?limit=1&offset=400 \
    -H "Authorization: Bearer d59f681797fbb3758b2a0ce8e5f31a199e2733110cb468bb2bb0d77f23417b32" \
    -H 'accept-version: 1.0.0'

How to delete an Item from a collection

1. Retrieve the ID of the item you need to delete

If you do not know the item ID but know for instance the item name, you can do this:

  1. list all the items in the collection using the Get All Items For a Collection endpoint
  2. filter out the item object with the correct name property
  3. get the object's ID from it's _id field

2. Use the Remove Collection Item Endpoint

Make a DELTE request to

https://api.webflow.com/collections/:collection_id/items/:item_id

In the request:

  • replace :collection_id with your collection's ID
  • replace :item_id with the correct item's ID

Example request URL

https://api.webflow.com/collections/580e63fc8c9a982ac9b8b745/items/581d2d8256e14ea22daf82df'

  • set the auth token we obtained earlier, in the request's Authorization header, remembering to prepend the string with Bearer.

Example authorization header:

Authorization: Bearer

d59f681797fbb3758b2a0ce8e5f31a199e2733110cb468bb2bb0d77f23417b32

  • set your Accept-Version headers.

"accept-version: 1.0.0"


  • Send your request

Here's an example request:


curl -X DELETE 'https://api.webflow.com/collections/580e63fc8c9a982ac9b8b745/items/581d2d8256e14ea22daf82df' \
  -H "Authorization: Bearer d59f681797fbb3758b2a0ce8e5f31a199e2733110cb468bb2bb0d77f23417b32" \
  -H 'accept-version: 1.0.0'


How to use the Webflow Ecommerce APIs

So far we have explained how to use the Webflow APIs to create, list and delete items from a generic Webflow collection.

These are not the only actions we can perform on a generic Webflow collection – we can also patch and update individual items.

Further more, generic collections are not the only collections we can perform actions on – we can also add, list, update and delete items from Ecommerce collections.

When working with Ecommerce collections the same process applies:

  • Identify the action to perform – GET, POST, PUT, PATCH, or DELETE
  • Obtain the values for the endpoint's parameters
  • Set your headers
  • Make your request

However, when working with Ecommerce collections there are some important things to note as a minimum:

  • Ecommerce collections use different endpoints, so if your collection ID isn't working and you're confused, crosscheck that you're using the correct endpoint.
  • Items in Ecommerce collections are called products. When adding a new product item it needs to have at a minimum an SKU item.

Reference the official documentation to learn more about how to add values to SKU items, and why the product type of a Product defaults to Advanced when you add a new Ecommerce product.

The Usefulness of Webflow's Webhooks API

So far along the way in building our imaginary Memberstack + Webflow app, we've learned how to set up an Ecommerce store on Webflow and about some of the APIs we can use to manage our Products catalog programatically.

To achieve our goal of sending emails to our Memberstack members each time a new product is added, we could constantly list out the products in our collection to check if anything has changed,

then send an email to a list of our Memberstack members, whose emails we can get very similarly by using their Backend Members API or by exporting from their dashboard.

But polling would be a terrible idea, and would be subject to Webflow's API rate limit of 60 requests / minute.

A better option is to create Webflow API Webhooks which trigger each time a new collection item is created.

Refer to the official documentation for more info on how to do this.

image.png

Webflow API Endpoints Cheatsheet

Resource Action Endpoint Documentation
Meta
Get Current Authorization Info GET api.webflow.com/info https://developers.webflow.com/#get-current-authorization-info
Get Current Authorized User GET https://api.webflow.com/user https://developers.webflow.com/#get-current-authorized-user
Sites
List of all sites the provided access token is able to access. GET https://api.webflow.com/sites https://developers.webflow.com/#list-sites
Get Specific Site GET /sites/:site_id https://developers.webflow.com/#get-specific-site
Publish Site POST /sites/:site_id/publish https://developers.webflow.com/#publish-site
Domains
List of all custom domains added to the given site GET /sites/:site_id/domains https://developers.webflow.com/#list-domains
Collections
List Collections GET /sites/:site_id/collections https://developers.webflow.com/#list-collections
Get Collection with Full Schema GET /collections/:collection_id https://developers.webflow.com/#get-collection-with-full-schema
Items
Get All Items For a Collection GET /collections/:collection_id/items https://developers.webflow.com/#get-all-items-for-a-collection
Get Single Item GET /collections/:collection_id/items/:item_id https://developers.webflow.com/#get-single-item
Create New Collection Item POST /collections/:collection_id/items https://developers.webflow.com/#create-new-collection-item
Create New Live Collection Item POST /collections/:collection_id/items?live=true https://developers.webflow.com/#create-new-live-collection-item
Update Collection Item PUT /collections/:collection_id/items/:item_id https://developers.webflow.com/#update-collection-item
Update Live Collection Item PUT /collections/:collection_id/items/:item_id?live=true https://developers.webflow.com/#update-live-collection-item
Patch Collection Item PATCH /collections/:collection_id/items/:item_id https://developers.webflow.com/#patch-collection-item
Patch Live Collection Item PATCH /collections/:collection_id/items/:item_id?live=true https://developers.webflow.com/#patch-live-collection-item
Remove Collection Item DELETE /collections/:collection_id/items/:item_id https://developers.webflow.com/#remove-collection-item
Ecommerce
Create New Product and Default SKU POST /sites/:site_id/products https://developers.webflow.com/#create-new-product-and-default-sku
Update Product PATCH /sites/:site_id/products/:product_id/skus/:sku_id https://developers.webflow.com/#update-product
Get All Products For a Site GET /sites/:site_id/products https://developers.webflow.com/#get-all-products-for-a-site
Get Single Product and SKUs GET /sites/:site_id/products/:product_id https://developers.webflow.com/#get-single-product-and-skus
Create SKUs POST /sites/:site_id/products/:product_id/skus https://developers.webflow.com/#create-skus
Update SKU PATCH /sites/:site_id/products/:product_id/skus/:sku_id https://developers.webflow.com/#update-sku
Get a list of all orders created for a given site. GET /sites/:site_id/orders https://developers.webflow.com/#get-all-orders
Update Order PATCH /sites/:site_id/order/:order_id/ https://developers.webflow.com/#update-order
Updates an order’s status to fulfilled POST /sites/:site_id/order/:order_id/fulfill https://developers.webflow.com/#fulfill-order

Continued...

Updates an order’s status to unfulfilled POST /sites/:site_id/order/:order_id/unfulfill https://developers.webflow.com/#unfulfill-order
Refund Order POST /sites/:site_id/order/:order_id/refund https://developers.webflow.com/#refund-order
Get the current inventory levels for a particular SKU item GET /collections/:collection_id/items/:item_id/inventory https://developers.webflow.com/#item-inventory
Update Item Inventory PATCH /collections/:collection_id/items/:item_id/inventory https://developers.webflow.com/#update-item-inventory
Retrieve ecommerce settings for a site GET /sites/:site_id/ecommerce/settings https://developers.webflow.com/#get-ecommerce-settings
Webhooks
List Webhooks GET /sites/:site_id/webhooks https://developers.webflow.com/#list-webhooks
Get specific webhook GET /sites/:site_id/webhooks/:webhook_id https://developers.webflow.com/#get-specific-webhook
Create a new webhook POST /sites/:site_id/webhooks https://developers.webflow.com/#create-new-webhook
Remove Webhook DELETE /sites/:site_id/webhooks/:webhook_id https://developers.webflow.com/#remove-webhook

Official Webflow API documentation

Please refer to Webflow's official documentation on the Webflow API for more information on any concept mentioned in this guide.

FAQ

  • Is there a Node SDK for Webflow's API? Yes and it's available on NPM
  • I don't have time to build out an app to consume these APIs, what do I do? Use third party tools like Zapier and Integromat. Zapier especialy will allow you to seamlessly integrate between Memberstack and Webflow without coding.
  • How do I create a new Live collection item? When adding new CMS items with the API, the default behavior is only to add the item as “staged” but not to include it in the published site. To override this default behaviour add the query parameter ?live=true
  • How do I update a live collection item? Very similarly to creating a new Live collection, add the query parameter ?live=true
  • The query parameter ?live=true is not working, what do I do? Re-publish your site to ensure all domains have the latest collection schema associated with them.