Skip to main content
Custom fields allow publishers to keep extra information about their members, such as a company name, a list of interests, or a shipping address. The custom fields resource manages the fields themselves: their names, types, options, and order. Each member’s values are read and written with the members resource, as documented in Custom field values. Publishers can also manage custom fields in Ghost Admin under Settings > Membership > Custom fields. Custom fields are member metafields in the custom namespace, so their endpoints live under /admin/members/metafields/custom/. Any staff user or integration can read custom fields. Only Administrators and custom integrations can create, update, reorder, or delete them.

​
The custom field object

Whenever you fetch, create, or edit a custom field, the API responds with an array of one or more custom field objects under members_metafields.

​
Parameters

When retrieving custom fields from the Admin API, it’s possible to use the filter parameter. Available filter values:
  • status:archived - for retrieving archived fields only
  • status:[active,archived] - for retrieving active and archived fields
By default, only active fields are returned, in the order they’re shown in Ghost Admin.

​
Retrieving a custom field

Returns a single field by its key, whether it’s active or archived.

​
Creating custom fields

Required fields: name, type
  • name - name of the field, up to 191 characters. Must be unique among the site’s custom fields, ignoring case, archived fields included
  • type - short_text, long_text, list, or address. Can’t be changed later
  • settings - required for list fields only. options is a list of 2 to 100 unique options, each up to 255 characters and without a |. multiple is true if a member can pick more than one
  • access - {member} set to none, read, or write. Defaults to none
Up to 100 fields can be created in one request:
A successful request returns a 201 response with the new fields, which are added to the end of the order. Each field’s key is generated from its name, so Shipping address becomes shipping_address. If that key is already taken, a number is added, as in shipping_address_2. If any field in the request is invalid, none are created. The 422 error’s property names the problem, and for a request with several fields, its context may name the field, for example Custom field 2 of 3.

​
Updating a custom field

The name, settings, access, and status of a field can be updated. Fields left out of the request are unchanged. New settings replace both options and multiple, and changing the options doesn’t change the options members have already picked. The key and type of a field can’t be changed.

​
Archiving a custom field

A field the site no longer uses can be archived by updating its status:
Archived fields are left out of the list of fields, their values are left out of member responses, and new values for them are refused. Their values are kept, and the field keeps its name and key. Setting status back to active restores the field and its values.

​
Reordering custom fields

The request lists every field’s key in the new order, archived fields included. A request that leaves out a field, names a field twice, or names a field that doesn’t exist is refused. The response contains every field, archived fields included, in the new order.

​
Deleting a custom field

Only archived fields can be deleted. Deleting a field permanently removes every member’s value for it, and frees its name and key. Delete requests have no payload in the request or response. Successful deletes return an empty 204 response.

​
Limits

By default, a site can have up to 100 custom fields, archived fields included. The limit can be changed with the maxDefinitions config option. Requests that would go over the limit are refused with a 403 error whose message states the limit, and nothing is created. Deleting an archived field makes room for another.