Shopify integration

The Shopify integration connects your Shopify store to Avelero, automatically syncing products and variants to generate Digital Product Passports.

Features

Two-way product sync: Import products from Shopify with all variants, options, and metadata
Automatic updates: Products stay in sync via scheduled syncs and webhooks
OAuth authentication: Secure connection without sharing passwords
Field mapping: Control which data comes from Shopify vs. manual entry in Avelero
Variant matching: Match Shopify variants to existing Avelero products via SKU or barcode

Installation

There are two ways to install the Shopify integration:

Option A: Install from Avelero (recommended)

Navigate to integrations

Go to Settings → Integrations in your Avelero dashboard.

Connect Shopify

Click Connect on the Shopify card.

Authorize access

You’ll be redirected to Shopify. Log in to your store and click Install app.

Return to Avelero

After authorization, you’ll be redirected back to Avelero. Your integration is now active.

Option B: Install from Shopify App Store

Find Avelero in Shopify App Store

Search for “Avelero” in the Shopify App Store.

Install the app

Click Add app and authorize the required permissions.

Claim installation in Avelero

Log in to Avelero and go to Settings → Integrations → Shopify. Click Claim pending installation to link the app to your brand.

The Shopify integration requires the read_products permission to sync product data. No customer data is accessed or stored.

Authentication flow

The Shopify integration uses OAuth 2.0 for secure authentication: Technical details:

Authorization endpoint: https://admin.shopify.com/oauth/install
Token exchange: POST https://{shop}.myshopify.com/admin/oauth/access_token
Scopes: read_products
Credentials are encrypted using AES-256-GCM before storage

Syncing products

Initial sync

When you first connect Shopify:

Click Sync now or wait for the automatic sync to start
Avelero fetches all products from Shopify’s GraphQL Admin API
Products are created in Avelero with Shopify’s product structure
Digital Product Passports are generated automatically

What gets synced:

Product fields

object

handle: Product slug (used as unique identifier)
title: Product name
description: Product description (HTML)
status: Publication status (draft, active, archived)
productType: Product type/category
vendor: Manufacturer name
tags: Product tags (array)
featuredImage: Main product image URL
category: Shopify product category taxonomy

Variant fields

object

sku: Stock keeping unit
barcode: Product barcode (UPC, EAN, etc.)
title: Variant name (e.g., “Small / Red”)
price: Variant price
selectedOptions: Array of option values (size, color, etc.)
image: Variant-specific image URL

Scheduled syncs

By default, Shopify syncs every 24 hours. You can adjust this in integration settings:

Minimum interval: 1 hour
Maximum interval: 7 days
Default: 24 hours

Manual sync

Open integration settings

Go to Settings → Integrations → Shopify.

Trigger sync

Click Sync now.

Monitor progress

The sync status updates in real-time. You can close the page - the sync continues in the background.

Sync behavior

Creating products:

New Shopify products are created in Avelero
Product handle is used as the unique identifier
All variants are imported

Updating products:

Existing products (matched by handle) are updated
Only fields owned by Shopify integration are updated
Manual edits to non-owned fields are preserved

Deleting products:

Products deleted in Shopify are NOT deleted in Avelero
They remain in Avelero for historical/compliance purposes
You can manually archive them if needed

Webhooks

Shopify sends webhooks to Avelero for real-time updates:

Mandatory compliance webhooks

These webhooks are required by Shopify and handle GDPR compliance:

POST https://api.avelero.com/integrations/webhooks/compliance
X-Shopify-Topic: customers/data_request
X-Shopify-Hmac-Sha256: {signature}

{
  "shop_domain": "example.myshopify.com",
  "customer": {
    "id": 123456789,
    "email": "[email protected]"
  }
}

Webhook handling:

customers/data_request: No action (Avelero doesn’t store customer data)
customers/redact: No action (Avelero doesn’t store customer data)
shop/redact: Deletes brand integration record 48 hours after app uninstall

Verifying webhooks

Avelero verifies all Shopify webhooks using HMAC-SHA256:

import { createHmac } from 'crypto';

function verifyShopifyWebhook(
  rawBody: string,
  hmacHeader: string,
  secret: string
): boolean {
  const hash = createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('base64');
  
  return hash === hmacHeader;
}

Field mapping

Configure which Shopify fields map to Avelero fields and control ownership:

Open field mapping

Go to Settings → Integrations → Shopify → Field mapping.

Review default mappings

Shopify fields are mapped to Avelero fields automatically:

Shopify field	Avelero field	Ownership
`title`	Product name	Shopify
`description`	Product description	Shopify
`handle`	Product handle	Shopify
`vendor`	Manufacturer	Shopify
`productType`	Category	Shopify
`tags`	Tags	Shopify
`sku`	Variant SKU	Shopify
`barcode`	Variant barcode	Shopify

Customize ownership

Click Edit on any field to:

Enable/disable ownership
Choose alternative source options
View which integration currently owns the field

Disabling ownership for a field means manual edits in Avelero will be preserved, but that field won’t be updated from Shopify during syncs.

Variant matching (secondary integration)

If Shopify is connected as a secondary integration (not primary), variants are matched to existing products: Matching strategies:

By SKU (default): Shopify variants are matched to Avelero variants with the same SKU
By barcode: Match using barcode instead (configure in integration settings)

Match behavior:

If a match is found, the variant is enriched with Shopify data (based on field ownership)
If no match is found, the variant is skipped (not created)
Unmatched variants are logged in the sync report

Troubleshooting

Connection fails with 'Invalid signature' error

Cause: OAuth flow was interrupted or tampered with.Solution:

Disconnect the integration in Avelero
Uninstall the Avelero app from Shopify admin
Reconnect using the “Install from Avelero” flow

Sync shows 'Authentication failed' error

Cause: Shopify access token expired or was revoked.Solution:

Go to Shopify admin → Apps
Verify Avelero app is still installed
If installed, disconnect and reconnect in Avelero
If not installed, reinstall from Avelero

Products are syncing but images aren't appearing

Cause: Shopify image URLs are CDN links that may require authentication.Solution:

Images are referenced by URL, not downloaded
Verify image URLs are publicly accessible
Check that featuredImage.url exists in Shopify’s GraphQL response

Some products are missing after sync

Cause: Products may be filtered by status or location.Solution:

Check product status in Shopify (must be published)
Verify products exist in the primary location
Review sync job logs in Settings → Integrations → Shopify → Sync history

Variant options aren't syncing correctly

Cause: Shopify uses a different attribute structure than Avelero.Solution:

Shopify options (Size, Color) are synced as Avelero attributes
Option values become attribute values
Review attribute mappings in Catalog → Attributes

API reference

Shopify GraphQL queries

Avelero uses Shopify’s GraphQL Admin API version 2025-07:

query GetProducts($first: Int!, $after: String) {
  products(first: $first, after: $after) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        handle
        title
        description
        descriptionHtml
        status
        productType
        vendor
        tags
        onlineStoreUrl
        featuredImage {
          url
        }
        category {
          id
          name
          fullName
        }
        variants(first: 100) {
          edges {
            node {
              id
              sku
              barcode
              title
              price
              selectedOptions {
                name
                value
              }
              image {
                url
              }
            }
          }
        }
      }
    }
  }
}

Rate limiting

Shopify enforces GraphQL rate limits based on query cost:

Maximum available: 2000 points
Restore rate: 100 points/second
Product query cost: ~50-150 points (depending on fields)

Avelero automatically throttles requests to stay within limits:

Rate limit handling

if (extensions?.cost?.throttleStatus) {
  const { currentlyAvailable, restoreRate } = extensions.cost.throttleStatus;
  
  if (currentlyAvailable < 100) {
    const deficit = 100 - currentlyAvailable;
    const delayMs = Math.ceil((deficit / restoreRate) * 1000);
    await new Promise(resolve => setTimeout(resolve, delayMs));
  }
}

Next steps

Bulk import/export

Supplement Shopify data with bulk imports for supply chain and sustainability info.

Product data structure

Learn how product data is structured and inherited.

Get Started

Core Features

Integrations

Compliance

Shopify integration

Features

Installation

Option A: Install from Avelero (recommended)

Option B: Install from Shopify App Store

Authentication flow

Syncing products

Initial sync

Scheduled syncs

Manual sync

Sync behavior

Webhooks

Mandatory compliance webhooks

Verifying webhooks

Field mapping

Variant matching (secondary integration)

Troubleshooting

API reference

Shopify GraphQL queries

Rate limiting

Next steps

Bulk import/export

Product data structure

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Compliance

​Features

​Installation

​Option A: Install from Avelero (recommended)

​Option B: Install from Shopify App Store

​Authentication flow

​Syncing products

​Initial sync

​Scheduled syncs

​Manual sync

​Sync behavior

​Webhooks

​Mandatory compliance webhooks

​Verifying webhooks

​Field mapping

​Variant matching (secondary integration)

​Troubleshooting

​API reference

​Shopify GraphQL queries

​Rate limiting

​Next steps

Bulk import/export

Product data structure

Build docs developers (and LLMs) love

Features

Installation

Option A: Install from Avelero (recommended)

Option B: Install from Shopify App Store

Authentication flow

Syncing products

Initial sync

Scheduled syncs

Manual sync

Sync behavior

Webhooks

Mandatory compliance webhooks

Verifying webhooks

Field mapping

Variant matching (secondary integration)

Troubleshooting

API reference

Shopify GraphQL queries

Rate limiting

Next steps