Custom fields and models

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.

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.

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:

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:

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.

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:

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.

To create a new content model:

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

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:

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:

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.