Custom Fields

Use custom fields to add extra structured data to your marketplace entities. Assign custom fields through attributes set up in your marketplace. Data entered in custom fields is validated based on the input type assigned when creating the attribute.

You can add custom fields to the following objects:

• User
• Product
• Variant
• Category
• Collection

Add custom fields by using a custom field template or by directly assigning an attribute without a template.

Manage custom field templates

Custom field templates allow for repeatable sets of attributes to be available when editing an object model. Templates apply across every instance of an object model.

For example, an attribute added to the User template is available as a custom field on every Customer and StaffMember.

Permission requirements

The creation of custom field templates is reserved for marketplace operators. You must have the "Manage marketplace" permission granted through your permission group to access this feature.

Assign custom fields to a template

1

(Optional)Query available attributes

2

Assign attribute to custom field template

Use the customAttributeAssign mutation to assign the attribute to the object model. This mutation requires the following arguments:

Argument	Usage
template	Specifies the type of object model to which the custom field is being assigned. Choose from USER, PRODUCT, VARIANT, CATEGORY, or COLLECTION.
operations	A list of attributes to assign as custom fields.
operations.id	The unique identifier (id) of the attribute to be assigned.
operations.type	Set to CUSTOM.

The following mutation adds the "Preferred Contact Time" attribute (id: QXR0cmlidXRlOjUy) to the User model, making this custom field available on every customer and staff member.

Request

mutation {
  customAttributeAssign(
    template: USER,
    operations: [
      {
        id: "QXR0cmlidXRlOjUy",
        type: CUSTOM
      }
    ]
  ) {
    customFieldTemplate {
      id
      createdAt
      updatedAt
      contentType
    }
    attributeErrors {
      field
      message
      code
      attributes
    }
  }
}

Show more ↓

3

Set custom field on an instance

Now that we've added that custom field to the User model, the next time you edit a staff member or customer, you can set that custom field.

note

Use the appropriate create or update mutation for the object you're setting the custom field on. For example, use productUpdate, productVariantUpdate, customerUpdate, staffUpdate, categoryUpdate, or collectionUpdate, respectively.

The following mutation updates an existing customer with a value for the "Preferred Contact Time" attribute (id: QXR0cmlidXRlOjUy), setting the value to Evening (5-9pm):

Request

mutation {
  customerUpdate(id: "VXNlcjoxMzg=", input: { customFields: [{id: "QXR0cmlidXRlOjUy", values: "Evening (5-9pm)"}] })
    user {
      id
      firstName
      lastName
      isActive
      customFields {
        attribute {
          name
        }
        values {
          id
          name
          slug
          type
        }
      }
    }
    accountErrors {
      field
      message
    }
  }
}

Show more ↓

Query custom field templates

To see which custom fields have been assigned to models, use the customFieldTemplates query:

Request

query{
  customFieldTemplates {
    id
    createdAt
    updatedAt
    contentType
    customAttributes(
      first: 10) {
      totalCount
      edges {
        node {
          id
          inputType
          name
          valueRequired
        }
      }
    }
  }
}

Show more ↓

Response

{
  "data": {
    "customFieldTemplates": [
      {
        "id": "Q3VzdG9tRmllbGRUZW1wbGF0ZTox",
        "createdAt": "2024-03-13T14:04:54.481148+00:00",
        "updatedAt": "2024-03-13T14:04:54.481180+00:00",
        "contentType": "USER",
        "customAttributes": {
          "totalCount": 1,
          "edges": [
            {
              "node": {
                "id": "QXR0cmlidXRlOjUy",
                "inputType": "DROPDOWN",
                "name": "Preferred Contact Time",
                "valueRequired": false
              }
            }
          ]
        }
      },
      {
        "id": "Q3VzdG9tRmllbGRUZW1wbGF0ZToy",
        "createdAt": "2024-03-13T14:04:54.491679+00:00",
        "updatedAt": "2024-03-13T14:04:54.491709+00:00",
        "contentType": "CATEGORY",
        "customAttributes": {
          "totalCount": 0,
          "edges": []
        }
      },
      {
        "id": "Q3VzdG9tRmllbGRUZW1wbGF0ZToz",
        "createdAt": "2024-03-13T14:04:54.502346+00:00",
        "updatedAt": "2024-03-13T14:04:54.502377+00:00",
        "contentType": "PRODUCT",
        "customAttributes": {
          "totalCount": 0,
          "edges": []
        }
      },
      {
        "id": "Q3VzdG9tRmllbGRUZW1wbGF0ZTo0",
        "createdAt": "2024-03-13T14:04:54.512830+00:00",
        "updatedAt": "2024-03-13T14:04:54.512859+00:00",
        "contentType": "VARIANT",
        "customAttributes": {
          "totalCount": 0,
          "edges": []
        }
      },
      {
        "id": "Q3VzdG9tRmllbGRUZW1wbGF0ZTo1",
        "createdAt": "2024-03-13T14:04:54.522955+00:00",
        "updatedAt": "2024-03-13T14:04:54.522982+00:00",
        "contentType": "COLLECTION",
        "customAttributes": {
          "totalCount": 0,
          "edges": []
        }
      }
    ]
  }
}

Show more ↓

Remove custom fields from a template

1

Unassign the attribute from the custom field template

Use the customAttributeUnassign mutation to remove an attribute from a custom field template. This mutation requires the following arguments:

Argument	Usage
attributeIds	The unique identifier (id) of the attribute to be removed.
template	Specifies the type of object model to which the custom field is being removed. Choose from USER, PRODUCT, VARIANT, CATEGORY, or COLLECTION.

Request

mutation {
  customAttributeUnassign(attributeIds: ["QXR0cmlidXRlOjUy"], template: USER) {
    customFieldTemplate {
      id
      createdAt
      updatedAt
      contentType
      customAttributes(first:10) {
        edges {
          node {
            id
            inputType
            name
          }
        }
      }
    }
    attributeErrors {
      field
      message
    }
  }
}

Show more ↓

Manually add custom fields to an instance

If your marketplace supports flexible attribute usage, you can assign a custom field to individual object instances without a custom field template.

info

Direct assignment of custom fields without a template is only allowed when MarketplaceConfiguration.attributeTemplateStrategy is set to FLEXIBLE.

For example, a seller might want to add a specific attribute like "Limited Edition Number" to a collectible item, which doesn't apply to other products. By manually adding a custom field to this particular product instance, the seller can provide additional, unique information without altering the template used for other products.

Assign a custom field to an instance

1

(Optional)Query available attributes

2

Add the custom field to an instance

Once you have the identifier for the attribute you want to assign, you can update the specific object instance you wish to target.

note

Use the appropriate create or update mutation for the object you're adding the custom field to. For example, use productUpdate, productVariantUpdate, customerUpdate, staffUpdate, categoryUpdate, or collectionUpdate, respectively.

The following mutation adds the "Limited Edition Number" attribute (id: QXR0cmlidXRlOjUz) as a custom field to a one-off product instance, without modifying fields available on other products in the catalog.

Request

mutation {
  productUpdate(
    id: "UHJvZHVjdDoxNTk="
    input: {
      customFields: [{ id: "QXR0cmlidXRlOjUz", values: "409" }]
    }
  ) {
    productErrors {
      message
      field
    }
    product {
      id
      name
      customFields {
        templated
        attribute {
          name
        }
         values {
          id
          name
          slug
          plainText
          type
        }
      }
    }
  }
}

Show more ↓

Remove a custom field from an instance

1

Unassign the custom field

Use the instanceAttributeUnassign mutation to remove an custom field from a specific instance. This mutation takes the following arguments:

Argument	Usage
instanceId	The unique identifier (id) of the object instance for which the custom field is being removed. For example, a product or category id.
custom	Set to true.
attributeId	The unique identifier (id) of the attribute to be removed.

For example, the following mutation removes the "Limited Edition Number" attribute (id: QXR0cmlidXRlOjUz) custom field from the product it was added to above:

Request

mutation {
  instanceAttributeUnassign(
    instanceId: "UHJvZHVjdDoxNTk="
    custom: true
    attributeId: "QXR0cmlidXRlOjUz"
  ) {
    instance {
      __typename
      ... on Product {
        id
        name
        customFields {
          templated
          attribute {
            name
          }
        }
      }
    }
    attributeErrors {
      field
      message
    }
  }
}

Show more ↓

Example use cases

Example: Mandatory product condition

As a marketplace on Nautical, you want to ensure every product, regardless of its type, displays a condition status. The status should be one of the following: New, Used, or Like New.

1. Create the attribute:
   • Create an attribute named "Condition" with the dropdown input type.
   • Set the attribute as required (valueRequired=True).
   • Add three options: New, Used, and Like New.
2. Update your marketplace configuration to set attributeTemplateStrategy to strict.
3. Add the Condition attribute to the Product custom field template.
   This ensures the condition field requirement applies to all products.

Example: Customer credit limits

As a marketplace on Nautical, you want to apply your own credit limit logic for certain customers.

1. Create the attributes:
   • Create an attribute named "Credit Limit" with the money input type.
   • Create an attribute named "Balance" with the money input type.
2. Update your marketplace configuration to set attributeTemplateStrategy to flexible, allowing you to assign these custom fields for specific customers only.
3. Implement the following checkout process:
   • During checkout, if a customer has the Credit Limit custom field, allow them to select an amount to fund up to the Balance amount.
   • Generate a dummy payment for the funded amount during checkout.
     This ensures the customer only needs to pay the remaining balance via card or bank.
4. Upon successful checkout, trigger the order_created webhook to update the Balance.amount custom field for the relevant user, reflecting the new balance.

Example: Bundled product offering

As a marketplace on Nautical, I offer two products: a PlayStation 5 bundle, which includes the console and a Call of Duty game, and the PlayStation 5 console by itself. I aim to encourage customers to purchase the bundle by featuring a prominent call-to-action (CTA).

1. Create an attribute named "Related Product" with the Reference input type.
2. Update your marketplace configuration to set attributeTemplateStrategy to flexible, allowing you to assign the Related Product custom field to select products only.
3. For the PlayStation 5 console (not grouped), set the Reference custom field to the ID of the grouped product.
4. Ensure the Reference custom field is displayed on the storefront.
   This enables linking to the grouped product page or can be used in subqueries for additional information display.