Custom Fields Sync

Wash can sync WordPress custom fields — including Advanced Custom Fields (ACF) — to Shopify metafields. This enables rich, structured content on your Shopify blog.

ACF sync available on Business and Enterprise plans.

Supported Field Types

Basic Custom Fields

Standard WordPress custom fields (post meta) are synced automatically:

  • Text fields
  • Number fields
  • Date fields
  • URL fields

Advanced Custom Fields (ACF)

Wash supports most ACF field types:

  • Basic: Text, Textarea, Number, Email, URL, Password
  • Content: WYSIWYG, oEmbed
  • Choice: Select, Checkbox, Radio, True/False
  • Relational: Link, Page Link (as URLs)
  • Media: Image, File, Gallery (as URLs)
  • Date/Time: Date Picker, Date Time Picker, Time Picker

Complex Field Types

These require special handling:

  • Repeater fields — Synced as JSON array
  • Group fields — Synced as JSON object
  • Flexible Content — Synced as JSON with layout info

Configuration

Enabling Custom Field Sync

  1. In Shopify, go to Wash → Settings
  2. Enable Custom Fields Sync
  3. Configure field mappings

Field Mapping

You can map WordPress fields to Shopify metafields:

  1. Go to Wash → Field Mappings
  2. Click Add Mapping
  3. Select WordPress field name
  4. Enter Shopify metafield namespace and key
  5. Choose data type

Example Mapping

WordPress FieldShopify MetafieldType
product_skucustom.product_skusingle_line_text
reading_timecustom.reading_timenumber_integer
featured_videocustom.featured_videourl

Creating Shopify Metafield Definitions

For best results, create metafield definitions in Shopify:

  1. Go to Settings → Custom data → Articles
  2. Click Add definition
  3. Enter namespace, key, and type
  4. Optionally add validation rules

Benefits of definitions:

  • Type validation
  • Visible in Shopify admin
  • Usable in theme editor
  • Better API support

Using Metafields in Your Theme

Basic Output

{% if article.metafields.custom.reading_time %} <span class="reading-time"> {{ article.metafields.custom.reading_time }} min read </span>
{% endif %}

Conditional Display

{% if article.metafields.custom.featured_video %} <div class="video-embed"> {{ article.metafields.custom.featured_video | video_tag }} </div>
{% else %} {{ article.image | image_url: width: 1200 | image_tag }}
{% endif %}

Complex Data (JSON)

{% assign specs = article.metafields.custom.specifications | parse_json %}
{% for spec in specs %} <tr> <td>{{ spec.label }}</td> <td>{{ spec.value }}</td> </tr>
{% endfor %}

ACF-Specific Features

Image Fields

ACF image fields are converted to URLs pointing to your Shopify CDN:

  • Image ID becomes CDN URL
  • Alt text is preserved separately if mapped

Repeater Fields

Repeater data is stored as JSON:

[ {"title": "Feature 1", "description": "..."}, {"title": "Feature 2", "description": "..."}
]

Flexible Content

Flexible content includes layout type:

[ {"acf_fc_layout": "text_block", "content": "..."}, {"acf_fc_layout": "image_gallery", "images": [...]}
]

Best Practices

  • Use consistent naming — Follow a namespace convention
  • Document your fields — Keep a mapping reference
  • Test complex fields — Verify JSON structures work in your theme
  • Consider Shopify limits — Metafield values have size limits

Troubleshooting

Field Not Syncing

  • Verify the field has a value in WordPress
  • Check field mapping configuration
  • Ensure field name matches exactly (case-sensitive)

Wrong Data Type

  • Create a metafield definition with correct type
  • Update the field mapping type

JSON Parse Errors

  • Validate JSON structure in WordPress
  • Check for special characters that need escaping

Related Articles