Core Functionalities
Metafield API

Working with Metafields in ShipReady

ShipReady provides a powerful Metafield class to simplify working with Shopify's metafields. This guide will walk you through each method of the Metafield class with practical examples.

Initializing the Metafield Class

First, import and initialize the Metafield class:

import { Metafield } from "../entities/metafield.js";
 
const metafield = new Metafield(admin);

Creating a Metafield

Use the create method to add a new metafield:

const newMetafield = await metafield.create({
  namespace: 'my_app',
  key: 'product_rating',
  value: 4.5,
  ownerId: 'gid://shopify/Product/1234567890',
});
 
console.log(newMetafield);
// Output: { id: 'gid://shopify/Metafield/1234', namespace: 'my_app', key: 'product_rating', value: '4.5', type: 'number_decimal' }

Updating a Metafield

To update an existing metafield, use the update method:

const updatedMetafield = await metafield.update({
  id: 'gid://shopify/Metafield/1234',
  namespace: 'my_app',
  key: 'product_rating',
  value: 4.7,
  ownerId: 'gid://shopify/Product/1234567890',
});
 
console.log(updatedMetafield);
// Output: { id: 'gid://shopify/Metafield/1234', namespace: 'my_app', key: 'product_rating', value: '4.7', type: 'number_decimal' }

Deleting a Metafield

To remove a metafield, use the delete method:

const deletedId = await metafield.delete('gid://shopify/Metafield/1234');
 
console.log(deletedId);
// Output: 'gid://shopify/Metafield/1234'

Getting the Current App's Owner ID

To get the ID of the current app installation:

const appOwnerId = await metafield.getCurrentAppOwnerId();
 
console.log(appOwnerId);
// Output: 'gid://shopify/AppInstallation/1234567890'

Retrieving Metafields

Get a Specific Metafield

To fetch a metafield for a specific resource:

const productMetafield = await metafield.getMetafield(
  'product',
  'gid://shopify/Product/1234567890',
  'my_app',
  'product_rating'
);
 
console.log(productMetafield);
// Output: { id: 'gid://shopify/Metafield/1234', namespace: 'my_app', key: 'product_rating', value: '4.7', type: 'number_decimal' }

Get Current App's Metafield

To retrieve a metafield for the current app:

const appMetafield = await metafield.getCurrentAppMetafield('my_app', 'installation_date');
 
console.log(appMetafield);
// Output: { id: 'gid://shopify/Metafield/5678', namespace: 'my_app', key: 'installation_date', value: '2023-07-01', type: 'single_line_text_field' }

Resource-Specific Metafield Retrieval

ShipReady provides convenience methods for common resources:

// Get Product Metafield
const productMeta = await metafield.getProductMetafield('gid://shopify/Product/1234567890', 'my_app', 'color');
 
// Get Product Variant Metafield
const variantMeta = await metafield.getProductVariantMetafield('gid://shopify/ProductVariant/9876543210', 'my_app', 'size');
 
// Get Customer Metafield
const customerMeta = await metafield.getCustomerMetafield('gid://shopify/Customer/1122334455', 'my_app', 'loyalty_points');
 
// Get Discount Metafield
const discountMeta = await metafield.getDiscountMetafield('gid://shopify/DiscountNode/9988776655', 'my_app', 'usage_limit');

Best Practices

  1. Use meaningful namespace and key combinations to organize your metafields.
  2. Handle potential errors when creating, updating, or deleting metafields.
  3. Be mindful of metafield value types and use appropriate data types.
  4. Use metafields judiciously to avoid cluttering the Shopify admin.

For more information on metafields and their usage in Shopify, refer to the official Shopify documentation (opens in a new tab).

If you encounter any issues or have questions about using metafields in ShipReady, please check our Troubleshooting page or contact our support team.

App Theme ExtensionsMetaobject API