Custom Fields

Custom fields allow organizations to extend Riseact entities with custom fields, without modifying the base schema. They can be used to collect additional information about supporters or donations, and can be exposed in the donation form directly from the campaign configuration.

Key concepts

Custom fields are based on two distinct objects:

• CustomFieldDefinition - The field definition: name, type, options. It is a schema shared at the organization level for a specific entity.
• CustomField - The actual value saved on a specific supporter or donation instance.

Supported entities

Custom fields can be defined for two entities:

Value	Description
supporter	Additional fields on the supporter profile
donation	Additional fields on a donation

Field types

Type	Description
text	Free text
boolean	True/false value
select	Selection from a list of predefined options

Field key (key)

The key (key) is a unique identifier for the field within an organization and an entity. It is generated automatically from the field name at creation time (by slugifying the name, e.g. "Data di nascita" → "data-di-nascita"). If the generated key is already in use, an incremental numeric suffix is added (e.g. "data-di-nascita-2").

The key is immutable after creation and is used to reference the field in campaign configurations and checkout payloads.

Integration with campaigns

Custom fields of type supporter can be included in a campaign configuration through the shown_fields and required_fields fields, using the field key. This way the field will appear in the campaign's donation form:

• shown_fields - The field is visible in the form
• required_fields - The field is visible and required

When a custom field definition is deleted, the key is automatically removed from all campaign configurations that reference it.

Archiving and deletion

Custom field definitions are not physically deleted: they are archived (archived: true). Values already saved on supporters and donations remain unchanged. Archived fields are not returned by queries by default (unless you explicitly filter with archived: true).

Checkout

During a checkout, the custom field values collected in the form are saved in the checkout's supporter_custom_fields and donation_custom_fields fields (as JSON), even before the supporter or donation is created. This ensures that the data is not lost even if the checkout is not completed.

GraphQL API

Query

List definitions:

query {
  customfieldDefinitions(filters: { entity: supporter }) {
    id
    name
    key
    type
    options
    position
    archived
  }
}

Single definition:

query {
  customfieldDefinition(id: 1) {
    id
    name
    key
    type
  }
}

Mutations

Create a definition:

mutation {
  customfieldDefinitionCreate(data: {
    entity: supporter,
    name: "Professione",
    description: "Professione del sostenitore",
    type: text
  }) {
    customFieldDefinition {
      id
      key
    }
    userErrors {
      field
      message
    }
  }
}

Create a select type field:

mutation {
  customfieldDefinitionCreate(data: {
    entity: donation,
    name: "Destinazione fondi",
    description: null,
    type: select,
    options: ["Progetto A", "Progetto B", "Progetto C"]
  }) {
    customFieldDefinition {
      id
      key
      options
    }
    userErrors {
      field
      message
    }
  }
}

Update a definition:

mutation {
  customfieldDefinitionUpdate(id: 1, data: {
    name: "Professione aggiornata",
    position: 2
  }) {
    customFieldDefinition {
      id
      name
    }
    userErrors {
      field
      message
    }
  }
}

Archive (delete) a definition:

mutation {
  customfieldDefinitionDelete(id: 1) {
    customFieldDefinition {
      id
      archived
    }
    userErrors {
      field
      message
    }
  }
}