Shopify SKU Variant Validator

A Node.js package to validate and process Shopify product variants by SKU with supplier matching capabilities.

Installation

npm install shopify-sku-variant-validator

Features

• Find product variants by SKU in Shopify
• Validate supplier information from variant or product metafields
• Handle multiple variants with intelligent supplier matching
• Comprehensive error handling and status reporting
• Support for optional supplier parameter

Usage

Basic Setup

import ShopifySKUValidator from 'shopify-sku-variant-validator';

// Initialize the validator with your Shopify credentials
const validator = new ShopifySKUValidator({
  apiUrl: 'https://your-store.myshopify.com/admin/api/2024-01/graphql.json',
  accessToken: 'your-shopify-access-token'
});

Process SKU without Supplier

async function example() {
  // Process a SKU without supplier (works for single variants)
  const result = await validator.processSKUWithVariantValidation('SKU-12345');
  
  console.log(result);
  // {
  //   sku: 'SKU-12345',
  //   status: 'found',
  //   message: 'SKU SKU-12345 found with 1 variant',
  //   data: {
  //     variantId: 'gid://shopify/ProductVariant/12345',
  //     productId: 'gid://shopify/Product/67890',
  //     productTitle: 'Example Product',
  //     supplier: 'Supplier A'
  //   },
  //   variantCount: 1
  // }
}

Process SKU with Supplier

async function example() {
  // Process a SKU with supplier (required for multiple variants)
  const result = await validator.processSKUWithVariantValidation('SKU-12345', 'Supplier A');
  
  console.log(result);
  // {
  //   sku: 'SKU-12345',
  //   status: 'found',
  //   message: 'SKU SKU-12345 found - selected variant matching supplier "Supplier A"',
  //   data: {
  //     variantId: 'gid://shopify/ProductVariant/12345',
  //     productId: 'gid://shopify/Product/67890',
  //     productTitle: 'Example Product',
  //     supplier: 'Supplier A'
  //   },
  //   variantCount: 2,
  //   selectedVariant: { ... },
  //   allVariants: [ ... ]
  // }
}

Find All Variants by SKU

async function example() {
  // Get all variants for a SKU
  const variants = await validator.findAllVariantsBySKU('SKU-12345');
  
  console.log(variants);
  // [
  //   {
  //     sku: 'SKU-12345',
  //     variantId: 'gid://shopify/ProductVariant/12345',
  //     productId: 'gid://shopify/Product/67890',
  //     productTitle: 'Example Product',
  //     supplier: 'Supplier A'
  //   }
  // ]
}

API Reference

Constructor

new ShopifySKUValidator(config)

Parameters:

• config.apiUrl (string, required): Your Shopify GraphQL API URL
• config.accessToken (string, required): Your Shopify access token

Methods

processSKUWithVariantValidation(sku, supplier)

Process a SKU with optional supplier validation.

Parameters:

• sku (string, required): The SKU to process
• supplier (string, optional): Supplier name to match against

Returns: Promise

Response Object:

{
  sku: string,              // The processed SKU
  status: string,           // 'found', 'not_found', or 'error'
  message: string,          // Human-readable status message
  data: Object | null,      // Variant data if found
  variantCount: number,     // Number of variants found
  errorType: string,        // Error type if status is 'error'
  variants: Array           // All variants if error occurred
}

Status Types:

• found: Variant successfully found and validated
• not_found: SKU not found in Shopify
• error: Error occurred during processing

Error Types:

• supplier_missing: Supplier metafield not set or doesn't match
• supplier_required: Multiple variants found, supplier parameter required
• multiple_variants_same_supplier: Multiple variants with same supplier
• no_matching_supplier: No variant matches the provided supplier
• multiple_matching_suppliers: Multiple variants match the supplier

findAllVariantsBySKU(sku)

Find all variants for a given SKU.

Parameters:

• sku (string, required): The SKU to search for

Returns: Promise

Response Array Item:

{
  sku: string,
  variantId: string,
  productId: string,
  productTitle: string,
  supplier: string | null
}

Configuration Requirements

Shopify Setup

1. API Access Token: Generate an access token with the following permissions:

   • read_products
   • read_product_listings

2. Metafields: The package expects supplier information in metafields:

   • Namespace: custom
   • Key: supplier
   • Can be set on either variant or product level (variant takes precedence)

3. API URL Format:

   https://{shop-name}.myshopify.com/admin/api/{version}/graphql.json

Error Handling

All methods return detailed error information in the response object. Always check the status field:

const result = await validator.processSKUWithVariantValidation('SKU-12345');

if (result.status === 'error') {
  console.error(`Error: ${result.message}`);
  console.error(`Error Type: ${result.errorType}`);
  console.error(`Variants:`, result.variants);
} else if (result.status === 'found') {
  console.log('Success:', result.data);
}

Use Cases

Single Variant Products

• Works with or without supplier parameter
• Returns variant data directly

Multiple Variant Products

• Requires supplier parameter to disambiguate
• Validates supplier against metafields
• Returns specific variant matching supplier

Supplier Validation

• Checks variant metafield first
• Falls back to product metafield
• Case-insensitive matching
• Trims whitespace automatically

License

MIT

Support

For issues and feature requests, please create an issue on the GitHub repository.