Shopify

Shopify Developer Documentation: Product Tagging & Enrichment Pipeline

Welcome to the Helium Pulse developer documentation for Shopify integration. This guide walks you through the end-to-end setup required to enable automated product tagging and enrichment for Shopify stores. Brands using this integration will install a private app via a secure link, which enables our system to access their store data, enrich product metadata using AI, and sync it back seamlessly.

1. App Installation by Brands

1.1 Installation via Private App Link

You will receive a private app installation link from our team.
Clicking the link will prompt you to approve permissions and install the Helium Tagging Engine on your Shopify store.
Upon installation, Helium Pulse securely receives an access token scoped to your store, which enables us to perform enrichment and synchronization tasks.

1.2 Required Permissions (Scopes)

Our app requests the following API access scopes:

read_products
write_products
read_metafields
write_metafields
read_metafield_definitions
write_metafield_definitions

These scopes allow us to fetch products, apply AI-generated tags, write those tags back as Shopify metafields, and manage metafield definitions programmatically.

2. Product Fetching

2.1 Fetch Products via Shopify Admin GraphQL API

We use Shopify's Admin GraphQL API to fetch your store’s products in batches, utilizing cursor-based pagination:

query productsQuery($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        title
        productType
        tags
        bodyHtml
        images(first: 1) {
          edges {
            node {
              originalSrc
            }
          }
        }
        metafields(first: 10, namespace: "auto_enrichment") {
          edges {
            node {
              key
              value
            }
          }
        }
      }
    }
  }
}

2.2 Example Request (Node.js)

const axios = require('axios');

async function fetchProducts(storeDomain, accessToken, cursor = null) {
  const query = `
    query productsQuery($first: Int!, $after: String) {
      products(first: $first, after: $after) {
        pageInfo {
          hasNextPage
          endCursor
        }
        edges {
          node {
            id
            title
            productType
            tags
            bodyHtml
            images(first: 1) {
              edges {
                node {
                  originalSrc
                }
              }
            }
            metafields(first: 10, namespace: "auto_enrichment") {
              edges {
                node {
                  key
                  value
                }
              }
            }
          }
        }
      }
    }
  `;

  const variables = {
    first: 250, // Max items per page for products in GraphQL
    after: cursor
  };

  const url = `https://${storeDomain}/admin/api/2023-10/graphql.json`;
  const response = await axios.post(url, { query, variables }, {
    headers: {
      'X-Shopify-Access-Token': accessToken,
      'Content-Type': 'application/json',
    }
  });
  return response.data.data.products;
}

3. Change Detection & Sync Triggers

3.1 Webhook Support (Optional)

We optionally listen for the following webhook events:

products/create
products/update

3.2 Daily Sync Option

For stores not using webhooks, we perform a scheduled sync once a day by fetching products updated since the last sync. While GraphQL primarily uses cursors for pagination, filtering by updatedAt is possible in some contexts or achieved by re-syncing recently updated products.

# Example of fetching products updated after a specific time (conceptual, actual implementation may vary)
# The `updatedAtMin` filter is often handled by iterating through recent products or relying on webhooks.
# For full daily sync, we'd typically paginate through all products as shown in 2.1.

4. Enrichment Pipeline

Once products are fetched, our AI pipeline:

Analyzes product title, type, tags, body HTML, and images
Determines category, subcategory, visual style, usage scenarios, and suitable personas
Outputs this enriched data in a structured format for syncing

5. Sync to Shopify (Metafields)

5.1 Metafield Structure and Definitions

We store enriched data in metafields under the namespace auto_enrichment. Before writing data, we ensure that the corresponding metafield definitions exist to provide structure and validation.

Example Metafield Definition Creation:

mutation metafieldDefinitionCreate($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    metafieldDefinition {
      id
      key
      namespace
      name
      type {
        name
      }
      ownerType
    }
    userErrors {
      field
      message
    }
  }
}

Variables for metafieldDefinitionCreate (e.g., for 'category'):

{
  "definition": {
    "name": "Category",
    "namespace": "auto_enrichment",
    "key": "category",
    "description": "AI-generated product category",
    "ownerType": "PRODUCT",
    "type": "single_line_text_field"
  }
}

Example keys for enriched data:

category
subcategory
visual_tags
persona
usage

5.2 Create/Update Metafields on a Product

We use the productUpdate mutation to create or update metafields on a product.

mutation productUpdateMetafields($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      id
      metafields(first: 10, namespace: "auto_enrichment") {
        edges {
          node {
            key
            value
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

Variables for productUpdateMetafields:

{
  "input": {
    "id": "gid://shopify/Product/123456789",
    "metafields": [
      {
        "namespace": "auto_enrichment",
        "key": "persona",
        "value": "genz_fashion",
        "type": "single_line_text_field"
      },
      {
        "namespace": "auto_enrichment",
        "key": "category",
        "value": "Apparel",
        "type": "single_line_text_field"
      }
    ]
  }
}

6. Optional: Native Tag Injection

We can also push the top 2–3 enrichment tags directly to Shopify’s native product tags field using the productUpdate mutation:

mutation productUpdateTags($input: ProductInput!) {
  productUpdate(input: $input) {
    product {
      id
      tags
    }
    userErrors {
      field
      message
    }
  }
}

Variables for productUpdateTags:

{
  "input": {
    "id": "gid://shopify/Product/123456789",
    "tags": ["floral", "summer", "traveler"]
  }
}

7. Daily Enrichment Summary

7.1 Delta CSV & Summary Report

Every enrichment cycle creates a CSV with the delta changes.
Includes: Product ID, updated metafields, timestamp.

7.2 Email Notification

An automated summary email is sent daily to your brand team.
It includes the number of products enriched and a downloadable CSV report.

8. Best Practices

Rate Limits: Shopify's GraphQL API uses a cost-based rate limiting system. We manage our API calls to stay within the allocated bucket size and restore rate to avoid throttling.
Redundant Sync Avoidance: We hash each product’s metadata and skip updates unless content has changed.
Error Resilience: We use retry logic with exponential backoff.
Testing: Our systems are validated on Shopify development stores and sandboxed production replicas.

9. Technical References

This documentation can be extended to include:

Client-side SDK integration for deeper brand-side observability
Webhook signature validation
Advanced error logging and structured retry handling

For any questions, please contact your Helium Pulse onboarding engineer.

PreviousAttribute groups NextKibo

Last updated 2 months ago