Shopify

📦Website

💰

Costs

Monthly:Free

Annual:Free

🔑

Access

CLIENT OWNEDINTERNALCLIENT ACCESS

ℹ️

ecommerce backend

Purpose: Website/e-commerce platform.

Last verified: December 2025

---

Account Details

• Notes: ecommerce backend
• Category: WEBSITE
• Account type: CLIENT_OWNED, INTERNAL, CLIENT_ACCESS
• Created: October 2025
• Account owner: Ben Power

---

Overview

Shopify is used as the ecommerce backend for managing products, orders, inventory, and customer data. This guide covers best practices for setting up product data structures, metafields, and integration workflows.

---

Setting Up Metafields

Metafields allow you to store custom data for products, collections, customers, and orders. They're essential for creating advanced filtering, displaying product specifications, and managing structured product data.

Accessing Metafields

1. Navigate to Settings → Custom data
2. Select the resource type (Products, Collections, Customers, Orders, etc.)
3. Click Add definition to create new metafield definitions

Metafield Definitions vs Values

Metafield definitions are templates that specify:

• What resource the metafield applies to (e.g., Products)
• What type of data it can store
• Validation rules for values

Metafield values are the actual data stored for each individual product/resource.

Content Types

Common content types for product metafields:

Content Type	Use Case	Example
Single line text	Simple text values	"White", "Thermoplastic"
Single line text (list)	Dropdown/choice lists	Colour options, Material types
Multi-line text	Longer descriptions	Feature lists, detailed specs
Integer	Whole numbers	Quantity, count
Decimal	Numbers with decimals	Dimensions, prices
Measurement	Dimensions with units	"44.5 cm", "2.5 kg"
File reference	Images/icons	Feature icons, material images
Date	Dates	Launch date, expiry date
URL	Links	Product videos, external resources
Color	Color values	Hex codes, color names
JSON	Structured data	Complex nested data
Reference	Links to other resources	Related products, collections

Standard vs Custom Definitions

• Standard definitions: Pre-configured by Shopify, universally compatible. Use these when possible.
• Custom definitions: Create when you need specific functionality not covered by standard definitions.

Creating Shared Fields

Fields used across multiple product types should be created once and reused:

Examples of shared fields:

• Colour/Color
• Material
• Dimensions (Width, Height, Depth)
• Brand
• Style

How to create:

1. Go to Settings → Custom data → Products
2. Click Add definition
3. Check for standard definitions first, or select Add custom definition
4. Configure:
   • Name: Descriptive name (e.g., "Color")
   • Namespace and key: Unique identifiers (e.g., custom.color)
   • Type/Content type: Choose appropriate type
   • Validations: Optional rules (character limits, ranges, etc.)
5. For choice lists, add all possible values
6. Click Save

Creating Product-Specific Fields

After shared fields, create fields specific to certain product types:

1. Follow the same process as shared fields
2. Name them clearly (e.g., "Hinge Technology", "Water Pressure")
3. Choose appropriate field type
4. Add description explaining purpose

Populating Metafield Values

1. Go to Products in Shopify admin
2. Open the product to edit
3. Scroll to Metafields section (appears after definitions are created)
4. Add values for each metafield:
   • Enter values from your spreadsheet
   • Ensure formats match (e.g., "44.5" not "44.5cm x 37.1cm")
   • For choice lists, select from dropdown
5. Save the product

---

Exporting Metafields and Metaobjects

Scripts are available to export all product metafields, metaobjects, and their definitions from Shopify for analysis and backup purposes.

Overview

The export toolkit provides automated scripts to:

• Export all product metafield definitions
• Export all metaobject definitions
• Export all products with their metafield values
• Export all metaobject entries
• Convert JSON exports to CSV for spreadsheet analysis

Quick Start

1. Install dependencies:

cd scripts
npm install

2. Get access token and run export:

npm run oauth

This single command:

• Uses Client Credentials Grant to get an access token
• Saves token to .env file
• Automatically runs the export
• Creates JSON files in exports/ directory

3. Convert to CSV:

npm run to-csv          # Convert all JSON files to CSV
npm run to-csv-wide     # Create wide-format products CSV (one row per product)

Available Scripts

Script	Purpose	Usage
oauth-get-token.js	Get access token via Client Credentials Grant	npm run oauth
export-shopify-metafields.js	Export all metafields and metaobjects	npm run export
json-to-csv.js	Convert JSON exports to CSV	npm run to-csv
json-to-csv-products-wide.js	Create wide-format products CSV	npm run to-csv-wide

Authentication Setup

Using Client Credentials Grant (Recommended):

This is the simplest method for apps you own installed in stores you own.

Requirements:

• App created in Dev Dashboard
• App installed in your store
• Client ID and Secret configured in script
• App scopes: read_products, read_metaobjects, read_metaobject_definitions

How it works:

1. Run npm run oauth
2. Script automatically exchanges client credentials for access token
3. Token is saved to .env file
4. Export runs automatically

Manual Token Setup:

If you prefer to set up the token manually:

1. Create .env file in scripts/ directory:

   SHOPIFY_STORE_URL=your-store.myshopify.com
   SHOPIFY_ACCESS_TOKEN=shpat_your_token_here

2. Run export:

   npm run export

Getting a token manually:

1. Go to Shopify admin → Settings → Apps and sales channels → Develop apps
2. Create and name an app, then click Create app
3. From the Configuration tab, click Configure under Admin API integration
4. Select required scopes: read_products, read_metaobjects, read_metaobject_definitions
5. Click Save
6. From API Credentials tab, click Install app
7. Click Reveal token once to expose the Admin API access token
8. Copy the token to your .env file

Export Output

Exports are saved to exports/shopify-export-{timestamp}/ with:

JSON Files:

• metafield-definitions.json - All metafield definitions (namespace, key, type, access permissions, validations)
• metaobject-definitions.json - All metaobject definitions (field definitions, capabilities, access settings)
• products-with-metafields.json - All products with metafields (product details + nested metafield arrays)
• metaobjects.json - All metaobject entries (metaobject details + field values)
• export-summary.json - Summary statistics (counts, groupings, metadata)

CSV Files (Generated):

• products-with-metafields.csv - Long format (one row per product-metafield combination)
• products-wide-format.csv - Wide format (one row per product, metafields as columns) - ideal for spreadsheet pivot tables
• metaobjects.csv - One row per metaobject, fields as columns
• metafield-definitions.csv - One row per definition
• metaobject-definitions.csv - One row per definition

Usage Examples

Complete workflow:

# 1. Get token and export
npm run oauth

# 2. Convert to CSV
npm run to-csv
npm run to-csv-wide

# 3. Open CSV files in Excel/Sheets
open exports/shopify-export-*/products-wide-format.csv

Export only (if you already have a token):

npm run export

Convert existing export:

# Convert most recent export
npm run to-csv

# Convert specific export directory
node json-to-csv.js ../exports/shopify-export-2026-01-19T15-46-34

Adding New Scopes

If you need additional scopes (e.g., read_metaobject_definitions):

1. Update app in Dev Dashboard:

   • Edit version → Add scopes → Release

2. Reinstall app:

   • Go to "Home" tab
   • Click "Install app"
   • Select store → Install

3. Get new token:

   npm run oauth

4. Re-run export:

   npm run export

Troubleshooting Export Scripts

"Access denied for metaobjectDefinitions"

Solution: Add read_metaobject_definitions scope to your app and reinstall.

"SHOPIFY_ACCESS_TOKEN environment variable is required"

Solution:

• Run npm run oauth to get a token automatically
• Or create .env file with your token

Token shows old scopes after adding new ones

Solution: Reinstall the app after releasing a new version with new scopes.

"Field doesn't exist" GraphQL errors

Solution: The script handles this automatically by removing unsupported fields. If you see errors, check the API version in the script.

Security Notes

• Never commit .env file - It contains your access token
• Rotate tokens regularly - Regenerate if compromised
• Use minimal scopes - Only request what you need
• Store tokens securely - Treat them like passwords

---

Filter-to-Column Mapping Strategy

When setting up product filters, align your spreadsheet columns with filter requirements.

Direct Mappings

Many filters map directly to spreadsheet columns:

Filter Name	Spreadsheet Column	Notes
Price	Price	Verify data populated
Type	Product Type	Verify data populated
Colour	Colour or Color	Standardize capitalization
Shape	Shape	Verify data populated
Material	Material	Verify data populated
Finish texture	Finish Texture	Verify data populated
Style	Design Style	Verify data populated
Mounting type	Mounting Type or Fixing Type	May need to standardize

Dimension Filters

Dimensions often need extraction from combined columns:

Common scenario:

• Spreadsheet has Size column: "44.5cm x 37.1cm"
• Filters need separate Width, Height, Depth columns

Action required:

1. Determine format (Width x Height? Length x Width?)
2. Extract values into separate columns
3. Standardize units (cm, mm, inches)
4. Ensure numeric values are extractable

Creating Missing Filter Columns

Some filters may not have corresponding columns:

Common additions:

• Promotions: TRUE/FALSE or promotion name
• Features: Key features (could combine existing fields)
• Guarantee: Warranty information (e.g., "2 years")

Standardizing Data Formats

Ensure consistency across all products:

• Dimensions: Consistent units (e.g., always "cm" not "centimeters")
• Colours: Consistent capitalization (e.g., "White" not "white" or "WHITE")
• Materials: Consistent naming (e.g., "Thermoplastic" not "Thermo Plastic")
• Boolean fields: Pick one format (TRUE/FALSE, Yes/No, Y/N) and stick to it

---

Spreadsheet Alignment Workflow

Step 1: Review Filter Requirements

1. Identify which filters apply to each product category
2. Map filters to spreadsheet columns
3. Identify gaps where columns don't exist

Step 2: Extract Combined Data

For columns with combined data (e.g., "44.5cm x 37.1cm"):

1. Determine the format
2. Extract into separate columns
3. Populate all relevant products
4. Standardize units and formats

Step 3: Create Missing Columns

1. Add columns for filters without corresponding data
2. Populate with data or mark as "N/A"
3. Document data sources

Step 4: Populate Data

For each product category:

1. Check which filters apply
2. Ensure every applicable filter column has data
3. Mark missing data appropriately (N/A, blank, or research)

Step 5: Standardize Formats

1. Review all data for consistency
2. Standardize naming conventions
3. Ensure units are consistent
4. Fix capitalization issues

Step 6: Create Mapping Document

Document for future reference:

For each filter:

• Spreadsheet column name
• Product categories it applies to
• Data format requirements
• Examples of valid values
• Data source
• Shopify metafield location (after migration)
• Permission/ownership

---

Best Practices

Metafield Setup

1. Start small: Begin with one product as an example
2. Work systematically: Complete one product type before moving to the next
3. Create shared fields once: Reuse across all products
4. Use choice lists: For fields with limited options (ensures consistency)
5. Document everything: Create a reference guide as you work

Data Quality

1. Standardize early: Fix naming and format issues before migration
2. Validate data: Check for missing values, inconsistencies, duplicates
3. Test as you go: Verify data displays correctly after creating fields
4. Keep it simple: Don't create fields that aren't needed

Process Documentation

Document each metafield created:

Field Name: [Name]
Field Type: [Single line text, Choice list, etc.]
Applies To: [Product categories]
Format: [Data format]
Examples: [Valid values]
Shopify Location: [Settings → Custom data → Products → [Name]]
Permission: [Who can update]
Source: [Spreadsheet column name]
Notes: [Any special considerations]

Recommended Workflow

1. Planning: Finalize filter requirements and spreadsheet structure
2. One product example: Set up all metafields for one product
3. Test and refine: Verify filters work, adjust as needed
4. Scale up: Work through products systematically by category
5. Document: Create reference documentation for the team

---

Integration Considerations

Warehouse/Inventory Management

When integrating with warehouse management systems (e.g., MintSoft):

• SKU mapping: Ensure SKUs match between systems
• Inventory sync: Verify stock levels update correctly
• Order fulfillment: Test automated fulfillment workflows
• Order status updates: Confirm status updates flow correctly
• Delivery options: Map different delivery types (next day, standard, etc.)

Third-Party Apps

Common integrations:

• Search & Discovery: Requires product associations and search terms setup
• Email marketing (Klaviyo): Ensure customer data syncs correctly
• Payment providers: Configure payment options (Klarna, PayPal, etc.)
• Shipping apps: Connect shipping providers for label generation

Multi-Channel Sales

When selling across multiple channels:

• Product compatibility: Ensure product data works across all channels
• Order tracking: Plan how to attribute orders to different sources
• Inventory management: Consider how stock is allocated across channels
• Email flows: Decide if separate flows are needed for different channels

---

Common Field Types by Use Case

Use Case	Recommended Content Type	Notes
Colour/Color	Single line text (list) or Color	Create once, reuse. Use list for dropdown
Material	Single line text (list)	Create once, reuse. Use list for dropdown
Dimensions	Measurement or Decimal	Measurement allows units (cm). Decimal for numeric values
Shape	Single line text (list)	Use list for dropdown consistency
Finish/Texture	Single line text (list)	Use list for dropdown
Mounting Type	Single line text (list)	Use list for dropdown
Promotions	Single line text	TRUE/FALSE or promotion name
Features	Multi-line text	Or create as meta object for more structure
Description	Multi-line text	Already exists in Shopify, verify format
Price	Decimal	Already exists in Shopify (product price)

---

Troubleshooting

"I can't edit metafields"

• Check account permissions (need admin or staff permissions)
• Verify you're in the correct Shopify account
• Ensure no other processes are blocking access

"Field already exists but with different name"

• Check for duplicates in Settings → Custom data → Products
• Consider renaming or consolidating to avoid confusion
• Document the decision for your team

"I don't know what content type to use"

• Simple text = Single line text
• Long description = Multi-line text
• Whole numbers = Integer
• Numbers with decimals = Decimal
• Dimensions with units = Measurement
• Dropdown options = Single line text (list)
• Images = File reference
• Dates = Date
• Links = URL

"How do I know if a field is shared?"

• If it's used by 2+ product types, it's shared
• Create the definition once and reuse it across all products
• Examples: Color, Material, Width, Height
• The same definition can be used for all products, but each product has its own value

"I can't find the Metafields section on a product"

• Make sure you've created at least one metafield definition first
• The Metafields section only appears after definitions are created
• Go to Settings → Custom data → Products to create definitions

"Should I use standard or custom definitions?"

• Use standard definitions when possible - They're pre-configured and universally compatible
• Use custom definitions when you need something specific that standard definitions don't cover
• Check Shopify's standard definitions first: Settings → Custom data → Products → Add definition → Browse standard definitions

---

Official Shopify Resources

For the most up-to-date information, refer to Shopify's official documentation:

• Metafields Overview
• Creating Custom Metafield Definitions
• Adding Standard Metafield Definitions
• Adding Metafield Values
• Displaying Metafields on Your Online Store

Note: Shopify's interface may change over time. If you encounter any differences, refer to the official documentation or Shopify's help center for the most current instructions.