Custom fields and models

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.

Unless specified in the content namespace, custom fields are not available through the Frontend API. Depending on how you define custom fields, there are two different ways to make fields publicly accessible via API.

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 can also 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 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
});

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

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