The Complete Guide to Shopify Bulk Operations: From £30k Chaos to Enterprise Control

mutation {
  bulkOperationRunQuery(
    query: """
    {
      products(first: 10000) {
        edges {
          node {
            id
            title
            variants {
              edges {
                node {
                  id
                  price
                  inventoryQuantity
                }
              }
            }
          }
        }
      }
    }
    """
  ) {
    bulkOperation {
      id
      status
      errorCode
      createdAt
      completedAt
    }
    userErrors {
      field
      message
    }
  }
}
                        

// Complete bulk operation with proper error handling
const initialiseBulkOperation = async (shopDomain, accessToken) => {
  const query = `
    mutation {
      bulkOperationRunQuery(
        query: """
        {
          products(first: 50000, query: "status:ACTIVE") {
            edges {
              node {
                id
                title
                handle
                status
                vendor
                productType
                tags
                variants {
                  edges {
                    node {
                      id
                      sku
                      price
                      compareAtPrice
                      inventoryQuantity
                      metafields(first: 20) {
                        edges {
                          node {
                            id
                            namespace
                            key
                            value
                            type
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
        """
      ) {
        bulkOperation {
          id
          status
          errorCode
          createdAt
        }
        userErrors {
          field
          message
        }
      }
    }
  `;

  try {
    const response = await fetch(`https://${shopDomain}/admin/api/2025-01/graphql.json`, {
      method: 'POST',
      headers: {
        'X-Shopify-Access-Token': accessToken,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ query })
    });

    const data = await response.json();

    if (data.errors) {
      throw new Error(`GraphQL errors: ${JSON.stringify(data.errors)}`);
    }

    if (data.data.bulkOperationRunQuery.userErrors.length > 0) {
      throw new Error(`User errors: ${JSON.stringify(data.data.bulkOperationRunQuery.userErrors)}`);
    }

    return data.data.bulkOperationRunQuery.bulkOperation;
  } catch (error) {
    console.error('Failed to initialise bulk operation:', error);
    // Implement retry logic here
    throw error;
  }
};
                        

// Webhook endpoint for bulk operation completion
app.post('/webhooks/bulk-operation-finish', async (req, res) => {
  const { admin_graphql_api_id, status, error_code, url } = req.body;

  // Verify webhook authenticity (CRITICAL for security)
  const hmac = req.get('X-Shopify-Hmac-Sha256');
  const hash = crypto
    .createHmac('sha256', process.env.SHOPIFY_WEBHOOK_SECRET)
    .update(req.rawBody, 'utf8')
    .digest('base64');

  if (hash !== hmac) {
    return res.status(401).send('Unauthorised');
  }

  // Handle completion based on status
  switch(status) {
    case 'completed':
      await processCompletedOperation(url);
      break;
    case 'failed':
      await handleFailedOperation(admin_graphql_api_id, error_code);
      break;
    case 'canceled':
      await handleCancelledOperation(admin_graphql_api_id);
      break;
    default:
      console.error(`Unknown status: ${status}`);
  }

  res.status(200).send('OK');
});
                        

// The JSONL Re-hydration Pattern - Exclusive to this guide
const readline = require('readline');
const fs = require('fs');

class JSONLRehydrator {
  constructor() {
    this.products = new Map();
    this.orphans = new Map();
  }

  async processJSONL(filePath) {
    const fileStream = fs.createReadStream(filePath);
    const rl = readline.createInterface({
      input: fileStream,
      crlfDelay: Infinity
    });

    for await (const line of rl) {
      if (!line.trim()) continue;

      try {
        const item = JSON.parse(line);
        this.processItem(item);
      } catch (error) {
        console.error(`Failed to parse line: ${error.message}`);
        // Log to error file for manual review
        fs.appendFileSync('jsonl-errors.log', `${line}\n`);
      }
    }

    // Resolve orphaned relationships
    this.resolveOrphans();

    return Array.from(this.products.values());
  }

  processItem(item) {
    // Handle the Shopify JSONL structure
    if (item.__typename === 'Product') {
      this.products.set(item.id, {
        ...item,
        variants: []
      });
    } else if (item.__typename === 'ProductVariant') {
      // Extract parent ID from variant's ID structure
      const parentId = this.extractParentId(item.id);

      if (this.products.has(parentId)) {
        this.products.get(parentId).variants.push(item);
      } else {
        // Store as orphan for later resolution
        if (!this.orphans.has(parentId)) {
          this.orphans.set(parentId, []);
        }
        this.orphans.get(parentId).push(item);
      }
    } else if (item.__typename === 'Metafield') {
      // Handle metafield attachment
      this.attachMetafield(item);
    }
  }

  extractParentId(variantId) {
    // Shopify variant IDs contain parent product ID
    const match = variantId.match(/gid:\/\/shopify\/ProductVariant\/\d+\?product_id=(\d+)/);
    return match ? `gid://shopify/Product/${match[1]}` : null;
  }

  resolveOrphans() {
    for (const [parentId, orphanedVariants] of this.orphans) {
      if (this.products.has(parentId)) {
        this.products.get(parentId).variants.push(...orphanedVariants);
      } else {
        console.error(`Parent product ${parentId} not found for ${orphanedVariants.length} variants`);
      }
    }
  }

  attachMetafield(metafield) {
    // Attach metafield to appropriate parent
    const ownerId = metafield.owner_id;

    if (ownerId.includes('ProductVariant')) {
      // Find variant and attach
      for (const product of this.products.values()) {
        const variant = product.variants.find(v => v.id === ownerId);
        if (variant) {
          if (!variant.metafields) variant.metafields = [];
          variant.metafields.push(metafield);
          break;
        }
      }
    } else if (ownerId.includes('Product')) {
      // Attach to product
      const product = this.products.get(ownerId);
      if (product) {
        if (!product.metafields) product.metafields = [];
        product.metafields.push(metafield);
      }
    }
  }
}

// Usage
const rehydrator = new JSONLRehydrator();
const products = await rehydrator.processJSONL('bulk-operation-result.jsonl');
console.log(`Processed ${products.length} products with ${products.reduce((sum, p) => sum + p.variants.length, 0)} variants`);
                        

// Recovery pattern for partial failures
class BulkOperationRecovery {
  constructor(originalManifest, partialResultUrl) {
    this.originalManifest = originalManifest;
    this.partialResultUrl = partialResultUrl;
  }

  async identifyFailedRecords() {
    // Download partial results
    const successfulIds = await this.downloadPartialResults();

    // Compare against original manifest
    const failedRecords = this.originalManifest.filter(
      record => !successfulIds.has(record.id)
    );

    return failedRecords;
  }

  async createRetryManifest(failedRecords) {
    // Create new JSONL for retry
    const retryFile = 'retry-manifest.jsonl';
    const stream = fs.createWriteStream(retryFile);

    for (const record of failedRecords) {
      stream.write(JSON.stringify(record) + '\n');
    }

    stream.end();

    // Log for audit trail
    await this.logRetryAttempt(failedRecords);

    return retryFile;
  }

  async logRetryAttempt(records) {
    const logEntry = {
      timestamp: new Date().toISOString(),
      operation: 'BULK_RETRY',
      recordCount: records.length,
      recordIds: records.map(r => r.id),
      reason: 'PARTIAL_FAILURE_RECOVERY'
    };

    // Append to immutable audit log
    fs.appendFileSync('audit-log.jsonl', JSON.stringify(logEntry) + '\n');
  }
}
                        

// Idempotent bulk price update
class IdempotentBulkUpdate {
  constructor() {
    this.operationCache = new Map();
  }

  generateIdempotencyKey(operation) {
    // Create deterministic key from operation parameters
    const data = {
      type: operation.type,
      ids: operation.ids.sort(),
      values: operation.values,
      timestamp: Math.floor(Date.now() / 60000) // 1-minute window
    };

    return crypto
      .createHash('sha256')
      .update(JSON.stringify(data))
      .digest('hex');
  }

  async executeBulkUpdate(operation) {
    const key = this.generateIdempotencyKey(operation);

    // Check if operation was recently executed
    if (this.operationCache.has(key)) {
      const cached = this.operationCache.get(key);
      if (cached.status === 'completed') {
        console.log('Operation already completed, returning cached result');
        return cached.result;
      }
      if (cached.status === 'in_progress') {
        console.log('Operation in progress, waiting...');
        return await this.waitForOperation(key);
      }
    }

    // Mark as in progress
    this.operationCache.set(key, {
      status: 'in_progress',
      startTime: Date.now()
    });

    try {
      // Execute the actual bulk operation
      const result = await this.performBulkOperation(operation);

      // Cache successful result
      this.operationCache.set(key, {
        status: 'completed',
        result: result,
        completedAt: Date.now()
      });

      return result;
    } catch (error) {
      // Mark as failed
      this.operationCache.set(key, {
        status: 'failed',
        error: error.message,
        failedAt: Date.now()
      });

      throw error;
    }
  }
}
                        

// SOX-Compliant Audit Trail Implementation
class SOXCompliantAuditTrail {
  constructor(immutableStorage) {
    this.storage = immutableStorage; // e.g., AWS S3 with Object Lock
  }

  async logBulkOperation(operation, changes) {
    const auditEntry = {
      // Immutable metadata
      id: crypto.randomUUID(),
      timestamp: new Date().toISOString(),
      timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,

      // Actor information
      actor: {
        type: operation.actorType, // 'user' | 'api' | 'system'
        id: operation.actorId,
        email: operation.actorEmail,
        ipAddress: operation.ipAddress,
        apiKey: operation.apiKey ? this.hashApiKey(operation.apiKey) : null
      },

      // Operation details
      operation: {
        type: operation.type,
        bulkOperationId: operation.shopifyBulkOpId,
        affectedCount: changes.length,
        status: operation.status,
        duration: operation.duration
      },

      // Individual changes (the critical part Shopify misses)
      changes: changes.map(change => ({
        resourceType: change.type,
        resourceId: change.id,
        field: change.field,
        previousValue: change.before,
        newValue: change.after,
        changeType: this.classifyChange(change.before, change.after)
      })),

      // Compliance metadata
      compliance: {
        requiresReview: this.requiresManualReview(changes),
        riskScore: this.calculateRiskScore(changes),
        dataClassification: this.classifyData(changes)
      },

      // Cryptographic proof
      checksum: null // Set after calculation
    };

    // Calculate checksum for tamper detection
    auditEntry.checksum = this.calculateChecksum(auditEntry);

    // Store in immutable storage
    await this.storage.writeOnce(
      `audit-logs/${auditEntry.timestamp}/${auditEntry.id}.json`,
      auditEntry,
      {
        legalHold: true,
        retentionYears: 7,
        encryption: 'AES-256'
      }
    );

    // If high-risk, trigger additional controls
    if (auditEntry.compliance.riskScore > 7) {
      await this.triggerComplianceReview(auditEntry);
    }

    return auditEntry.id;
  }

  calculateRiskScore(changes) {
    let score = 0;

    changes.forEach(change => {
      // Price reductions over 20% are high risk
      if (change.field === 'price' && change.after < change.before * 0.8) {
        score += 3;
      }

      // Inventory adjustments over £10,000 value
      if (change.field === 'inventory' && Math.abs(change.after - change.before) * change.unitCost > 10000) {
        score += 4;
      }

      // Mass deletions
      if (change.changeType === 'deletion' && changes.length > 100) {
        score += 5;
      }
    });

    return Math.min(score, 10);
  }
}
                        

// Secure API Key Management Pattern
class SecureAPIKeyManager {
  constructor() {
    this.vault = new HashiCorpVault(); // Or AWS Secrets Manager
    this.rotationSchedule = 30 * 24 * 60 * 60 * 1000; // 30 days
  }

  async getActiveKey(scope) {
    // Never store keys in code or environment variables
    const keyData = await this.vault.read(`shopify/keys/${scope}`);

    // Check if rotation needed
    if (Date.now() - keyData.createdAt > this.rotationSchedule) {
      await this.rotateKey(scope);
    }

    // Return decrypted key with usage logging
    return this.decrypt(keyData.encryptedKey);
  }

  async rotateKey(scope) {
    // Generate new key
    const newKey = await this.shopifyAdmin.createAPIKey(scope, {
      permissions: this.getMinimalPermissions(scope)
    });

    // Store encrypted
    await this.vault.write(`shopify/keys/${scope}`, {
      encryptedKey: this.encrypt(newKey),
      createdAt: Date.now(),
      previousKey: await this.getActiveKey(scope) // Keep for rollback
    });

    // Schedule old key deletion
    setTimeout(() => this.deleteOldKey(scope), 24 * 60 * 60 * 1000);

    // Audit log
    await this.auditLog('KEY_ROTATION', { scope, timestamp: Date.now() });
  }

  getMinimalPermissions(scope) {
    // Principle of Least Privilege
    const permissions = {
      'price_updates': ['read_products', 'write_products'],
      'inventory_sync': ['read_inventory', 'write_inventory'],
      'customer_tags': ['read_customers', 'write_customers'],
      'order_fulfillment': ['read_orders', 'write_fulfillments']
    };

    return permissions[scope] || ['read_products'];
  }
}
                        

// B2B Tiered Pricing Bulk Management
class B2BTieredPricingManager {
  async bulkUpdateTieredPricing(pricingRules) {
    // Step 1: Create Price Lists for each tier
    const priceLists = await this.createPriceLists(pricingRules);

    // Step 2: Bulk assign products to price lists
    const mutations = pricingRules.map(rule => ({
      priceListId: rule.listId,
      productVariantIds: rule.variants,
      pricing: {
        price: rule.basePrice * rule.multiplier,
        compareAtPrice: rule.comparePrice,
        minimumOrderQuantity: rule.moq || 1,
        volumePricing: rule.volumeBreaks || []
      }
    }));

    // Step 3: Assign customers to appropriate catalogs
    await this.bulkAssignCustomersToCatalogs(pricingRules);
  }

  async bulkAssignCustomersToCatalogs(rules) {
    const query = `
      mutation assignCompanyToCatalog($companyId: ID!, $catalogId: ID!) {
        companyLocationAssignCatalog(
          companyLocationId: $companyId
          catalogId: $catalogId
        ) {
          companyLocation {
            id
            catalog {
              id
              title
            }
          }
          userErrors {
            field
            message
          }
        }
      }
    `;

    // Process in batches to avoid rate limits
    for (const batch of this.chunk(rules, 10)) {
      await Promise.all(batch.map(rule =>
        this.graphqlClient.request(query, {
          companyId: rule.companyId,
          catalogId: rule.catalogId
        })
      ));

      // Rate limit compliance
      await this.sleep(1000);
    }
  }
}

// Usage Example: Supplier price increase across all tiers
const manager = new B2BTieredPricingManager();

await manager.bulkUpdateTieredPricing([
  {
    tier: 'WHOLESALE_GOLD',
    multiplier: 0.6,  // 40% off retail
    moq: 100,
    volumeBreaks: [
      { quantity: 500, percentageDecrease: 5 },
      { quantity: 1000, percentageDecrease: 10 }
    ]
  },
  {
    tier: 'WHOLESALE_SILVER',
    multiplier: 0.75, // 25% off retail
    moq: 50
  },
  {
    tier: 'TRADE',
    multiplier: 0.85, // 15% off retail
    moq: 10
  }
]);
                        

// UK VAT-Compliant Bulk Price Update
class UKVATBulkPriceUpdater {
  constructor() {
    this.standardVAT = 0.20;  // 20%
    this.reducedVAT = 0.05;   // 5%
    this.zeroVAT = 0.00;      // 0%
  }

  calculateVATInclusivePrice(basePrice, vatRate, supplierIncrease) {
    // Step 1: Apply supplier increase to base
    const newBasePrice = basePrice * (1 + supplierIncrease);

    // Step 2: Add VAT
    const priceIncVAT = newBasePrice * (1 + vatRate);

    // Step 3: Apply psychological pricing (£X.99)
    const finalPrice = Math.floor(priceIncVAT) + 0.99;

    return {
      basePrice: newBasePrice,
      vatAmount: newBasePrice * vatRate,
      finalPrice: finalPrice,
      displayPrice: finalPrice.toFixed(2)
    };
  }

  async bulkUpdateWithVAT(products, supplierIncrease) {
    const updates = products.map(product => {
      const vatRate = this.determineVATRate(product);
      const newPricing = this.calculateVATInclusivePrice(
        product.basePrice,
        vatRate,
        supplierIncrease
      );

      return {
        id: product.id,
        input: {
          variants: [{
            id: product.variantId,
            price: newPricing.displayPrice,
            metafields: [
              {
                namespace: 'tax',
                key: 'base_price_ex_vat',
                value: newPricing.basePrice.toString(),
                type: 'number_decimal'
              },
              {
                namespace: 'tax',
                key: 'vat_amount',
                value: newPricing.vatAmount.toString(),
                type: 'number_decimal'
              }
            ]
          }]
        }
      };
    });

    // Execute bulk mutation
    return await this.executeBulkProductUpdate(updates);
  }

  determineVATRate(product) {
    // UK VAT rules complexity
    if (product.productType === 'FOOD_ESSENTIAL') return this.zeroVAT;
    if (product.productType === 'CHILDREN_CLOTHING') return this.zeroVAT;
    if (product.productType === 'ENERGY_SAVING') return this.reducedVAT;
    return this.standardVAT;
  }
}
                        

// Subscription Price Change Orchestrator
class SubscriptionPriceChangeOrchestrator {
  async executePriceChange(productId, newPrice, strategy) {
    // Step 1: Identify all active subscriptions
    const activeContracts = await this.fetchActiveContracts(productId);

    console.log(`Found ${activeContracts.length} active subscriptions`);

    // Step 2: Segment by strategy
    const segments = this.segmentContracts(activeContracts, strategy);

    // Step 3: Process each segment appropriately
    const results = {
      immediate: await this.processImmediate(segments.immediate, newPrice),
      nextCycle: await this.scheduleNextCycle(segments.nextCycle, newPrice),
      grandfathered: await this.applyGrandfathering(segments.grandfathered),
      notification: await this.sendNotifications(segments.all, newPrice)
    };

    // Step 4: Generate compliance report
    await this.generateComplianceReport(results);

    return results;
  }

  segmentContracts(contracts, strategy) {
    const segments = {
      immediate: [],
      nextCycle: [],
      grandfathered: [],
      all: contracts
    };

    contracts.forEach(contract => {
      // Grandfather long-term customers
      if (this.isLongTermCustomer(contract)) {
        segments.grandfathered.push(contract);
      }
      // Immediate for month-to-month
      else if (contract.billingPolicy.interval === 'MONTH') {
        segments.nextCycle.push(contract);
      }
      // Delay for annual
      else if (contract.billingPolicy.interval === 'YEAR') {
        segments.grandfathered.push(contract);
      }
      // Default strategy
      else {
        segments.nextCycle.push(contract);
      }
    });

    return segments;
  }

  async processImmediate(contracts, newPrice) {
    const mutation = `
      mutation updateSubscriptionContract($contractId: ID!, $input: SubscriptionContractUpdateInput!) {
        subscriptionContractUpdate(contractId: $contractId, input: $input) {
          contract {
            id
            lines {
              currentPrice {
                amount
              }
            }
          }
          userErrors {
            field
            message
          }
        }
      }
    `;

    const results = [];

    // Process in careful batches
    for (const batch of this.chunk(contracts, 5)) {
      const batchResults = await Promise.all(
        batch.map(contract =>
          this.updateContractPrice(contract, newPrice, mutation)
        )
      );

      results.push(...batchResults);

      // Aggressive rate limiting for sensitive operations
      await this.sleep(2000);
    }

    return results;
  }

  async sendNotifications(contracts, newPrice) {
    // Legal requirement: 30-day notice for price increases
    const template = `
      Important: Price Update for Your Subscription

      Dear {{customer_name}},

      We're writing to inform you of a price change to your subscription.

      Current price: £{{current_price}}
      New price: £{{new_price}} ({{percentage_change}}% change)
      Effective date: {{effective_date}}

      Why the change?
      {{reason}}

      Your options:
      1. No action needed - your subscription will continue
      2. Change your plan - explore alternatives
      3. Cancel anytime - no penalties

      Questions? Reply to this email or call {{support_phone}}.

      Thank you for being a valued customer.
    `;

    // Bulk email via your ESP
    return await this.emailService.bulkSend(
      contracts.map(contract => ({
        to: contract.customer.email,
        template: 'subscription_price_change',
        data: {
          customer_name: contract.customer.firstName,
          current_price: contract.currentPrice,
          new_price: newPrice,
          percentage_change: ((newPrice - contract.currentPrice) / contract.currentPrice * 100).toFixed(1),
          effective_date: this.calculateEffectiveDate(contract),
          reason: this.getPriceChangeReason()
        }
      }))
    );
  }
}
                        

// POD Bulk Variant Generator
class PODBulkVariantGenerator {
  async generateVariantsForDesign(design, templates) {
    const products = [];

    for (const template of templates) {
      // Work around the 3-option limit
      const product = await this.createProductWithVariants(design, template);

      // Handle the 250-media limit
      await this.assignMockupsIntelligently(product, design, template);

      // Sync with POD provider
      await this.syncWithProvider(product, design, template);

      products.push(product);
    }

    return products;
  }

  async createProductWithVariants(design, template) {
    // Smart variant creation within Shopify's limits
    const variantGroups = this.optimiseVariantGroups(template.options);

    const products = [];

    for (const group of variantGroups) {
      const product = {
        title: `${design.name} - ${template.name} ${group.suffix || ''}`,
        productType: template.type,
        vendor: design.artist,
        tags: [...design.tags, ...template.tags],
        options: group.options, // Max 3 options per product
        variants: this.generateVariantCombinations(group.options)
      };

      // Handle the 2048 variant limit
      if (product.variants.length > 2048) {
        // Split into multiple products
        const chunks = this.chunk(product.variants, 2048);
        chunks.forEach((chunk, i) => {
          products.push({
            ...product,
            title: `${product.title} - Part ${i + 1}`,
            variants: chunk
          });
        });
      } else {
        products.push(product);
      }
    }

    return products;
  }

  optimiseVariantGroups(allOptions) {
    // Intelligent grouping to work around 3-option limit
    const groups = [];

    if (allOptions.length <= 3) {
      groups.push({ options: allOptions });
    } else {
      // Strategic split: Size + Colour + Style, then Size + Colour + Material
      groups.push({
        options: [allOptions[0], allOptions[1], allOptions[2]],
        suffix: 'Style Collection'
      });

      if (allOptions[3]) {
        groups.push({
          options: [allOptions[0], allOptions[1], allOptions[3]],
          suffix: 'Premium Materials'
        });
      }
    }

    return groups;
  }

  async assignMockupsIntelligently(product, design, template) {
    // Work around 250-media limit
    const mockups = await this.generateMockups(design, template);

    if (mockups.length <= 250) {
      // Simple case: assign all
      return await this.bulkAssignMedia(product.id, mockups);
    }

    // Complex case: intelligent selection
    const prioritisedMockups = this.prioritiseMockups(mockups, product.variants);

    // Assign top 250
    await this.bulkAssignMedia(product.id, prioritisedMockups.slice(0, 250));

    // Store remainder in metafields for lazy loading
    await this.storeAdditionalMockupsInMetafields(
      product.id,
      prioritisedMockups.slice(250)
    );
  }

  prioritiseMockups(mockups, variants) {
    // Smart prioritisation: bestselling colours, hero angles
    const priorityRules = [
      { color: 'Black', weight: 10 },
      { color: 'White', weight: 9 },
      { color: 'Navy', weight: 8 },
      { angle: 'front', weight: 10 },
      { angle: 'lifestyle', weight: 8 }
    ];

    return mockups.sort((a, b) => {
      const scoreA = this.calculateMockupPriority(a, priorityRules);
      const scoreB = this.calculateMockupPriority(b, priorityRules);
      return scoreB - scoreA;
    }).slice(0, 250);
  }
}
                        

// Digital License Bulk Manager
class DigitalLicenseBulkManager {
  async bulkGenerateAndAssign(productId, quantity) {
    // Generate unique license keys
    const licenses = await this.generateLicenses(quantity);

    // Store in Shopify metafields
    await this.storeLicensesInShopify(productId, licenses);

    // Set up automated delivery
    await this.configureAutomatedDelivery(productId);

    // Monitor and replenish
    await this.setupReplenishmentMonitor(productId);
  }

  async generateLicenses(quantity) {
    const licenses = [];

    for (let i = 0; i < quantity; i++) {
      licenses.push({
        key: this.generateSecureKey(),
        status: 'available',
        createdAt: new Date().toISOString(),
        expiresAt: null,
        assignedTo: null
      });
    }

    return licenses;
  }

  generateSecureKey() {
    // Format: XXXX-XXXX-XXXX-XXXX
    const segments = [];
    for (let i = 0; i < 4; i++) {
      segments.push(
        crypto.randomBytes(2).toString('hex').toUpperCase()
      );
    }
    return segments.join('-');
  }

  async setupReplenishmentMonitor(productId) {
    // Webhook for low inventory
    const webhook = {
      topic: 'products/update',
      address: 'https://your-app.com/webhooks/license-monitor',
      format: 'json',
      metafieldNamespaces: ['licenses']
    };

    await this.shopifyAdmin.webhook.create(webhook);

    // Background job for checking
    this.scheduler.schedule('*/10 * * * *', async () => {
      const availableCount = await this.countAvailableLicenses(productId);

      if (availableCount < 100) {
        await this.replenishLicenses(productId, 1000);
        await this.notifyAdmin('License pool replenished', productId);
      }
    });
  }
}