@devxcommerce/provider-upload-shopify

Description

Upload provider for Strapi that stores files in Shopify using the Shopify Admin API. Files are uploaded to your Shopify store's Files section and can be managed through the Shopify admin.

Installation

# using yarn
yarn add @devxcommerce/provider-upload-shopify

# using npm
npm install @devxcommerce/provider-upload-shopify --save

Configuration

• provider defines the name of the provider
• providerOptions is passed during provider initialization
• actionOptions is passed directly to each method for custom options

Provider Configuration

./config/plugins.js or ./config/plugins.ts

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: "@devxcommerce/provider-upload-shopify",
      providerOptions: {
        storeDomain: env("SHOPIFY_STORE_DOMAIN"), // e.g., 'your-store.myshopify.com'
        accessToken: env("SHOPIFY_ADMIN_ACCESS_TOKEN"),
        apiVersion: env("SHOPIFY_API_VERSION", "2025-10"), // Optional, defaults to '2025-10'
      },
      actionOptions: {
        upload: {},
        uploadStream: {},
        delete: {},
      },
      breakpoints: {},
    },
  },
  // ...
});

Environment Variables

Create a .env file with the following:

SHOPIFY_STORE_DOMAIN=your-store.myshopify.com
SHOPIFY_ADMIN_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
SHOPIFY_API_VERSION=2025-10

Getting Shopify Credentials

1. Admin Access Token:
   • Go to your Shopify Admin → Settings → Apps and sales channels → Develop apps
   • Create a custom app or use an existing one

• Under Admin API access tokens, create a token with write_files and read_files permissions (required scopes)

2. Store Domain:
   • Your store's domain (e.g., your-store.myshopify.com)

Security Middleware Configuration

Update the Content Security Policy to allow Shopify CDN URLs:

./config/middlewares.js

module.exports = [
  // ...
  {
    name: "strapi::security",
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          "connect-src": ["'self'", "https:"],
          "img-src": ["'self'", "data:", "blob:", "market-assets.strapi.io", "cdn.shopify.com"],
          "media-src": ["'self'", "data:", "blob:", "market-assets.strapi.io", "cdn.shopify.com"],
          upgradeInsecureRequests: null,
        },
      },
    },
  },
  // ...
];

Features

• Upload files to Shopify Files
• Support for both stream and buffer uploads
• Automatic file deletion from Shopify
• File metadata storage (Shopify file ID, alt text)
• Support for images, videos, and generic files

Limitations and Edge Cases

File Size Limits

Shopify enforces different file size limits based on file type:

• Images: Maximum 20 MB per file
• Videos & Other Files: Maximum 256 MB per file

The provider automatically validates file sizes before upload and throws an error if limits are exceeded.

Image Resolution Limits

Images must not exceed 20 megapixels in resolution (width × height). For example:

• ✅ 5000 × 4000 pixels = 20 MP (valid)
• ❌ 6000 × 4000 pixels = 24 MP (exceeds limit)

The provider validates image dimensions when the optional image-size package is installed.

Supported File Types

The provider supports all file types that Shopify accepts:

• Images: JPEG, PNG, GIF, WebP, HEIC, SVG
• Videos: MP4, MOV, AVI, WebM, MPEG, WMV
• Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX
• Generic Files: ZIP, CSV, JSON, TXT, and others

Files are automatically categorized as IMAGE, VIDEO, or FILE based on MIME type.

API Rate Limits

Shopify GraphQL Admin API has the following rate limits:

• Standard: 50 points per second
• Plus: 100 points per second

Each file upload uses multiple API calls:

1. Staged upload creation (~10 points)
2. File record creation (~10 points)
3. Potential polling for CDN URL (~10 points per poll)

Recommendations:

• Avoid bulk uploads of 10+ files simultaneously
• Implement retry logic with exponential backoff for rate limit errors
• Consider queuing large batch uploads

Upload Process

Files are uploaded via Shopify's staged upload flow:

1. Request a staged upload target (Google Cloud Storage)
2. Upload file to GCS
3. Create file record in Shopify
4. Poll for CDN URL (up to 20 attempts with progressive delays)

This process typically takes 2-5 seconds per file but may be longer for large files or during high API load.

Known Issues

• CDN URL delays: Large video files may take longer to process. The provider polls up to 20 times with increasing delays (up to ~210 seconds total).
• Alt text: Set via alternativeText or caption fields in Strapi. If both are empty, defaults to filename.
• Image optimization: Shopify automatically optimizes images for web delivery. Original files are preserved.

Links

• Shopify Admin GraphQL API - stagedUploadsCreate
• Shopify Admin GraphQL API - fileCreate
• Shopify Admin GraphQL API - fileDelete
• Upload media to Shopify