How to use Custom Fields

In this example we take you through how to create and manage custom fields while using the Operator API

4 minute read

What you’ll learn

In this article, you’ll learn about Custom Fields, specifically:

What Custom Fields are & who can use them
The objects that are supported by Custom Fields
The queries & mutations that can be used to create and retrieve Custom Fields

What are custom fields?

Custom fields are a new feature that lets you expand the information you collect and store about sellers. For example, you might create a custom field to collect additional contact information, timezone, or addresses for returns.

Currently, custom fields can only be:

created as: text, boolean, URL or Email field types
- additionally, you can specify whether custom fields require a value or not using the required attribute
added to a seller’s profile (visible to you) and in the seller portal (visible to sellers).
created using the GraphQL API.

Similar to metadata, the purpose of custom fields is to allow you to define and use attributes that may not exist for an object in the default schema.

Read our article on Creating Custom Groups and Fields for more details.

Note

Custom fields are only available for use in Connected environments and are not supported in either Full-Stack or Headless configurations.

Structure of custom fields

When creating a custom field, operators will first need to create a Custom Field Group that the fields belong to.

Name	GraphQL Object	Description	Example
Custom Field Group	`customFieldGroup`	A custom field group is an object that one or more customs fields belong to. Creating a Group is a prerequisite for any Custom fields to be created. There is no limit to the number of custom field groups that can be created.	Additional Seller Information
Custom Field	`customField`	A custom field is the actual attribute that can be populated with data. Custom fields always belong to a Custom Field Group. There is no limit to the number of custom fields that can be created.	Billing contact, Return address, Delivery cut off time.

Creating & Managing Custom Field Groups & Custom Fields

Custom Field Groups and Fields can only be created and updated via the GraphQL API. Below are some examples of how to get started creating groups and fields.

Create a Custom Field Group

An example mutation for creating a new custom field group.

    mutation {
      customFieldGroupCreateOrUpdate(
        input: {
          attributes: {
            name: "New Custom Field Group"
            description: "Description"
            entity: SELLER
          }
        }
      ) {
        customFieldGroup {
          id
          name
          description
          entity
        }
      }
    }

Update a Custom Field Group

An example mutation for updating details of existing custom field groups, where id is the ID of the custom field group you intend on updating.

    mutation {
      customFieldGroupCreateOrUpdate(
        input: {
          id: "someID"
          attributes: {
            name: "New Custom Field Group Name"
            description: "Description"
            entity: SELLER
          }
        }
      ) {
        customFieldGroup {
          id
          name
          description
          entity
        }
      }
    }

Delete a Custom Field Group

An example mutation for deleting a Custom Field Group. Using this method will also delete any associated CustomFields.

    mutation {
      customFieldGroupDelete(input: { id: "someID" }) {
        customFieldGroup {
          id
        }
      }
    }

Create a Custom Field

An example mutation for creating a new or updating an existing custom field. The customFieldGroupId must already exist.

    mutation {
      customFieldCreateOrUpdate(
        input: {
          attributes: {
            customFieldGroupId: "someID"
            name: "New Custom Field"
            description: "Description"
            placeholder: "Placeholder"
            fieldType: TEXT
            required: true
          }
        }
      ) {
        customField {
          id
          name
          description
          placeholder
          fieldType
        }
      }
    }

Update a Custom Field

An example mutation for updating the attributes of an existing custom field, where id is the ID of the custom field that you intend on updating.

    mutation {
      customFieldCreateOrUpdate(
        input: {
          id: "someOtherID"
          attributes: {
            customFieldGroupId: "someID"
            name: "New Custom Field Name"
            description: "Description"
            placeholder: "Placeholder"
            fieldType: TEXT
          }
        }
      ) {
        customField {
          id
          name
          description
          placeholder
          fieldType
        }
      }
    }

Delete a Custom Field

An example mutation for deleting a custom field, where id is the ID of the custom field that you intend on updating.

    mutation {
      customFieldDelete(input: { id: "someOtherID" }) {
        customField {
          id
        }
      }
    }

IMPORTANT

Duplicate names of Custom Field Groups and Custom Fields are not allowed.

Retrieve all the custom field groups and fields created

An example of a query to retrieve all the Custom Field Groups and their associated fields that have been created for your marketplace.

    query {
      customFieldGroups {
        nodes {
          id
          name
          description
          entity
          customFields {
            edges {
              node {
                id
                name
                description
                placeholder
                fieldType
              }
            }
          }
        }
      }
    }

Retrieve custom field values

To retrieve the values that have been entered for custom fields, you can use a similar query to the below. Because custom fields are currently only available on the seller profile, we are using the sellerSearch query. Note that value is being used to retrieve the information that is entered in the field.

    {
      sellerSearch {
    	sellers {
            edges {
                node {
                    businessName
                    id
                    customFieldGroups {
                        nodes {
                            id
                            name
                            customFields {
                                edges {
                                    node {
                                        name
                                        value
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
      }
    }