blueprint3d / module-etsy-integration

v1.0.8 2026-09-12 14:31 UTC

Requires

• php: >=8.1.0 <8.6.0
• magento/framework: *

proprietary

• BluePrint3D Ltd

Published on Packagist.org on 2026-09-12 14:50 UTC

README

An enterprise-grade, direct-database Etsy v3 connector for Magento 2. Sync products, gallery images, smart tags, and dynamic personalizations to Etsy asynchronously in the background—without breaking cron schedules, causing Admin timeouts, or paying expensive monthly SaaS middleware fees.

🛑 The Problem

Most Magento 2 Etsy connectors rely on slow, synchronous HTTP requests during product save, causing Admin edit pages to crash or lock up. Worse still, existing tools treat custom options as broken variants, forcing merchants to build complex configurable products just to collect simple buyer text inputs or engraving choices.

🛠️ The Solution

The BluePrint3D Etsy Integration handles your catalogue sync using a lightweight, direct-database background queue worker. Built natively for the latest Etsy API v3, it automatically converts both native Magento Custom Options and BluePrint3D Shared Options into native Etsy Personalizations and custom dropdowns without risking catalogue corruption or inventory miscounts.

✨ Features

• Asynchronous Background Queue: Offloads heavy API lifting to a dedicated DB queue table (blueprint3d_etsy_queue) and cron worker. Product saves in Admin remain instant.
• Native Etsy Personalization Sync: Leverages Etsy's multi-question personalization API to automatically push text fields, text areas, and non-inventory dropdowns straight into Etsy's custom options box.
• BluePrint3D Shared Options Ready: Zero-config compatibility with BluePrint3D_SharedProductOptions, bypassing Admin/CLI area restrictions to read shared groups seamlessly.
• Smart Tag Generator: Extracts meta keywords, cleans forbidden characters, caps length at 20 characters, and automatically falls back to product titles if meta tags are missing.
• Automated Gallery Sync: Sorts and uploads up to 10 high-resolution product gallery images according to native Magento position rankings.
• Configurable Safeguards: Built-in Strict Mode (abort sync and alert admin) and Lenient Mode (strip unsupported options and log warnings) to protect listings from API rejection.

🚀 Free vs. Pro

This free edition syncs up to 20 products. For unlimited products, bulk operations, configurable variation support, and more, see Etsy Integration Pro.

📦 Installation

1. Install via Composer

composer require blueprint3d/module-etsy-integration

2. Enable the module

php bin/magento module:enable BluePrint3D_EtsyIntegration

3. Run the database upgrade

php bin/magento setup:upgrade

4. Compile and flush cache

php bin/magento setup:di:compile
php bin/magento cache:flush

⚙️ Quick Configuration

1. Navigate to Stores > Configuration > BluePrint3D > Etsy Settings in your Magento Admin.
2. Enter your Etsy OAuth API Credentials and Shop ID.
3. Configure your Unsupported Options Handling (Strict Mode or Lenient Mode).
4. Map your Magento Categories to Etsy Taxonomy IDs under Catalog > Categories.
5. Save any assigned product to queue it for immediate background sync!

📜 License & Support

Copyright © 2026 BluePrint3D Ltd. All rights reserved.

This software is licensed under a Commercial Proprietary End User License Agreement (EULA). Resale, redistribution, sublicensing, or public hosting of this source code is strictly prohibited.

For licensing updates, technical documentation, or dedicated integration support:

Website: www.blueprint3d.dev
Company: BluePrint3D Ltd (Company Registration Number: 13473806)
Support Email: [e-mail]