Learn how to create and update custom fields within Swell models, including how to update permissions for those fields to be editable through the Frontend API—as well as how to fetch and create records for these custom models using the Backend API. Overall, there are endless customization possibilities with Swell's content fields feature.

Swell models support the creation of custom fields, and these fields can be leveraged by both Frontend and Backend APIs depending on how you configure the custom fields.

To illustrate the ability to create custom fields within Swell models, let's update the /accounts model to include some additional fields that we’d like our customers to be able to update.

For this example, let’s add a “birthday” field to our /accounts model. Typically this would be part of the UI on our storefront and implemented with Swell’s Frontend API.

  1. Navigate to the Dashboard and select Developer > Models.
  2. Select the Customers model > Select “Add field” > Choose the “Date” type.
  3. Add “Birthday” under Label > Advanced options. Ensure you’re selecting “Content” for the API namespace. This will ensure this field is accessible with the Frontend API, otherwise, it will be restricted to the Backend API.

Custom fields that are defined without the "Content" namespace selected will not be accessible from the Frontend API and are limited to interaction via our Backend API.

Now that we’ve added our field to the model, we still have to open the permission for this field to be editable through the Frontend API. By default, content fields are read-only, meaning they won’t be editable through the Frontend API.

To open the content permissions, follow the detailed steps in this guide to fetch the id of the public key that you're using.

Editing content fields with the Frontend API is currently limited to swell-js and is not currently possible via GraphQL.

Using the developer console, make a PUT request to /:clients with the /:self/keys/<id> as the URI. In the body of the request, specify the model name to configure, along with the field.

You’ll notice we’re only modifying the input permission since fields created with the content namespace are automatically returned with the Frontend API. For more details relating to opening content permissions, see this guide.

Now we can include a customer’s birthday when creating their account. Using swell-js, we’ll include the birthday field in the account.create method:

Create an account
await swell.account.create({
      email: "customer@mail.com",
      password: 'password',
      content: {
        birthday: "1995-10-21T05:00:00.000Z"

You’ll also be able to update content fields on the /accounts model by using the account.update() method:

Updating content fields
await swell.account.update({
  content: {
    favorite_food: "Pizza"

Custom fields can be used in lots of other ways as well, such as updating a cart with some value during the checkout process. For updating a content field on the /cart model, you can use the cart.update() method.

Updating cart content
await swell.cart.update({
  content: {
    store_pickup: true

This is also useful with subscriptions. With content fields, you can create additional fields to store data that can be updated on a customer portal. Let’s say we have a content field named pet_name that stores the name of a customer’s pet for their pet food subscription. To update this field, you would do the following:

Updating subscription model
await swell.subscription.update({
  content: {
    pet_name: "Zoe"

In both of these scenarios, you would have to ensure that you’ve correctly set the appropriate permissions as shown in the steps above—ensuring you have set the correct model and field names.

Swell also supports creating custom models to store additional data within your Swell store. Similar to custom fields, custom models can also be declared with the content namespace, allowing you to query custom content on your storefront.

Unlike content fields, content models are currently read-only with the Frontend API.

To create a new content model:

  1. Navigate to Developer > Models > Create new model
  2. Under namespace, select Content.
  3. Add the name and desired fields.

To query content models using swell-js, you can use the content.get() method:

Query a content model
await swell.content.get('vehicles');

In the case where you want to retrieve a specific record, you can also pass in the id of the record:

Retrieve a specific record
await swell.content.get('vehicles', '<id>');

Custom model records can only be created or edited with the Backend API. Using the same /vehicles model that we used above, we can create a new record using swell-node:

Create a new record
await swell.post('/content/vehicles', {
  make: 'Swell',
  model: 'Roadster',
  year: 2023

Similar to other models in Swell, you’ll also be able to get, put, or delete records using the Backend API.

Swell’s content fields feature allows for endless customization possibilities, allowing you to introduce creative elements into your storefront whether this is at the time of checkout, account creation, on a customer portal, or beyond.