Manage entries

Metaobjects let you store structured data with multiple related field values. This guide shows you how to create, read, update, and delete metaobject entries using the GraphQL Admin API.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the read_metaobjects and write_metaobjects access scopes.
• You've created a metaobject definition for your metaobject. The definition specifies the fields, validations, and permissions.

Anchor to Creating entriesCreating entries

Create metaobject entries to store instances of structured data based on your metaobject definitions.

Anchor to Create a basic entryCreate a basic entry

This example creates a size chart metaobject entry with basic field values. Both the field keys and type must match the existing metaobject definition.

Anchor to Create an entry with capabilitiesCreate an entry with capabilities

If your metaobject definition has capabilities enabled (such as publishable), set their initial state when creating entries. This example creates an author metaobject with publishable status set to active.

Anchor to Create entries in batchCreate entries in batch

When you need to create many metaobject entries, use bulk operations for better performance. This is more efficient than making separate requests for each entry.

Anchor to Reading entriesReading entries

Query metaobject entries to retrieve their data using various approaches.

Anchor to Query entries by typeQuery entries by type

Retrieve all metaobject entries of a specific type. This is useful when you need to list all entries, such as displaying all size charts or author profiles.

Anchor to Query a specific entry by handleQuery a specific entry by handle

Retrieve a single metaobject using its handle. Handles are URL-friendly identifiers for referencing specific entries.

Anchor to Query a specific entry by IDQuery a specific entry by ID

Retrieve a metaobject entry using its global ID. This is useful when you have the ID stored and need to fetch the entry's current state.

Anchor to Query specific fieldsQuery specific fields

Optimize queries by requesting only the fields you need.

Anchor to Query with filtersQuery with filters

Filter metaobject entries based on field values. This is useful for finding entries that match specific criteria, such as all size charts for "Large" sizes.

Anchor to Updating entriesUpdating entries

Modify existing metaobject entries to change field values or capability states.

Anchor to Update field valuesUpdate field values

Update one or more field values in a metaobject entry. Optimize the operation by including only the fields you want to change.

Anchor to Update published statusUpdate published status

For metaobjects with the publishable capability enabled, change their published status to control visibility on the storefront.

Anchor to Bulk update entriesBulk update entries

When you need to update many metaobject entries, use bulk operations for better performance.

Anchor to Deleting entriesDeleting entries

Remove metaobject entries that are no longer needed using the GraphQL Admin API.

Anchor to Delete a single entryDelete a single entry

Delete a metaobject entry using its global ID.

Anchor to Bulk delete entriesBulk delete entries

When you need to delete many metaobject entries, use bulk operations for better performance.

Anchor to Connecting metaobjects to resourcesConnecting metaobjects to resources

One of the most powerful patterns with metaobjects is connecting them to Shopify resources using metafields. Reference type metafields store links to metaobject entries, enabling you to create reusable structured data that can be attached to products, orders, and other resources.

How it works:

1. Create definitions (metaobject + metafield) in your TOML configuration and deploy
2. Create metaobject entries (such as "Waterproof", "Eco-friendly", "Durable")
3. Attach entries to products by setting the metafield value

Why use this pattern:

• Reusability: Create a feature (such as 'Waterproof') once, reference it from 100 products
• Maintainability: Update the feature entry, and it updates everywhere it's referenced
• Structure: Features have consistent fields (title, description, icon) defined by the metaobject definition

Reference types available:

• metaobject_reference - Link to a single metaobject entry
• list.metaobject_reference - Link to multiple entries of the same metaobject type
• mixed_reference - Link to entries from different metaobject types

Anchor to Step 1: Create definitionsStep 1: Create definitions

Define the metaobject structure and the metafield that references it:

Deploy the definitions:

Anchor to Step 2: Create metaobject entriesStep 2: Create metaobject entries

Anchor to Step 3: Attach metaobject entries to a productStep 3: Attach metaobject entries to a product

Anchor to Handle managementHandle management

Metaobject handles are URL-friendly identifiers used to reference entries.

Anchor to Auto-generated handlesAuto-generated handles

By default, Shopify generates handles from the display name:

Anchor to Custom handlesCustom handles

Specify a custom handle for more control:

Anchor to Error handlingError handling

Common errors when managing metaobject entries:

Anchor to Best practicesBest practices

• Use meaningful handles: Choose handles that clearly identify the entry's purpose.
• Validate before creating: Check that all required fields are provided and values match expected types.
• Use bulk operations for scale: When creating, updating, or deleting many entries, use bulk operations for better performance.
• Query only needed fields: Optimize API usage by requesting only the fields you need.
• Handle errors gracefully: Check userErrors in responses and provide clear feedback.
• Consider capability states: Set appropriate published/unpublished states for publishable metaobjects.

Anchor to TroubleshootingTroubleshooting

Common issues and solutions when working with metaobject entries:

Anchor to Next stepsNext steps

• Learn how to work with metaobject definitions.
• Learn how to enable advanced features.
• Learn about metaobject limits.