Access to custom fields

Due to the fact that ACF stores the values of custom fields in Shopify Metafields, you can leverage Shopify’s API for handling those Metafields to update any field value inside ACF.

The field values for the various Shopify objects (shop level included) are just normal Metafields with the namespace and key as defined by you in ACF via your field definitions.

Using Shopify’s API you can create, update and delete Metafields as you see fit, but:

Note

To ensure ACF keeps working with any content you create or edit outside ACF itself, please respect the Metafield data type and content restrictions (see below) for each field type

Also, please adhere to the general ACF rule stating that if a value of a custom field is (completely) empty, its corresponding Metafield does not exist

ACF’s internal field definitions are stored as shop-level Metafields in your store with some special namespaces unique to ACF. For uninterrupted service by ACF, don’t update these Metafields via the Shopify API.

Field types and value restrictions

Field type: Text

Metafield type: string or json_string*

No value restrictions.

Field type: Markdown text

Metafield type: json_string

Must contain a stringified JSON object of this structure:

{
  markdown: "# Heading level 1",
  html: "<h1>Heading level 1</h1>"
}

The markdown property should contain valid markdown text and the html property the rendered version of that markdown. ACF internally uses the npm package markdown-it to render the HTML.

Field type: HTML

Metafield type: string or json_string*

No value restrictions as such, but should contain valid HTML. An invalid structure risks getting “cleaned” by the Froala editor if a user edits the content after API updates.

Field type: Checkbox

Metafield type: string or json_string*

Create a Metafield with the value “true” to indicate a checked checkbox. An unchecked checkbox should not have an existing Metafield (so you’ll never see a Metafield with the value “false” for a checkbox field).

Field type: Selection

Metafield type: string or json_string*

Any field value provided should be one of the defined options. Multiple tags must be separated by a pipe symbol (|) e.g. “In Stock|2 Weeks Delivery Time”.

Field type: Tags

Metafield type: string or json_string*

Multiple tags must be separated by a pipe symbol (|) e.g. “Blue|Used|1 Year Warranty”.

Field type: Number

Metafield type: string or json_string*

Should contain a valid number with or without decimal points (.). The Metafield is a string to allow for non-integer values.

Field type: Date

Metafield type: string or json_string*

Should contain a valid date in the format defined in the ACF field definition.

Field type: Color

Metafield type: string or json_string*

Should contain a valid RGB color code in hex (#RRGGBB).

Field type: Custom Object (JSON)

Metafield type: json_string

Should contain a valid stringified JSON object.

Field type: Media upload

Metafield type: string or json_string*

The content of a media upload field is determined by ACF. To upload an image to ACF’s image storage from outside the editor (including from another store), you’ll need to use the Media upload API function.

Field type: Reference field

Metafield type: string or json_string*

Reference fields should contain one or more handles of the referenced object(s). Variant reference fields should contain the product’s handle and the referenced variant’s id in the form handle:id. Multiple handles must be separated by a pipe symbol (“|”) e.g. “my-awesome-product|my-other-awesome-product”.

*Considerations for repeatable fields

All fields in ACF can be repeated. Whenever a field is defined as repeatable, any Metafields created for that field definition automatically become a json_string type with the value being an array of the field value(s).

The content restrictions for the field type still apply, but now for every element in the array. If an element in the array doesn’t exist, you should use an empty string (“”) as a placeholder.

If multiple repeatable fields “belong together” (like a FAQ setup with questions and associated answers), the array structure for each field should match each other, so the individual values share the same index in their respective arrays.

*Considerations for multi-language fields

Multi-language fields are structured in JSON objects with the individual language locales as keys.