=== SyncKube - Products Sync for Shopify ===
Contributors: sakurapixel
Tags: shopify products, product-sync, import, ecommerce
Requires at least: 6.4
Tested up to: 6.9
Stable tag: 1.0.2
Requires PHP: 8.2
License: GPL-3.0-only
License URI: https://www.gnu.org/licenses/gpl-3.0.txt

Seamlessly sync your Shopify products into WordPress.

== Description ==

SyncKube is a WordPress plugin that seamlessly synchronises your Shopify store products with WordPress. SyncKube acts as a Shopify custom app to automatically import products, manage collections, and display them on your WordPress site with integrated shopping cart functionality.

Perfect for businesses that want to showcase their Shopify products on WordPress while maintaining a seamless shopping experience through Shopify's secure checkout system.

[Home](https://sakuraleaf.com/products/synckube-products-sync-for-shopify) | [Showcase](https://sakuraleaf.com/showcase/shopypress/) | [Docs](https://sakuraleaf.com/showcase/shopypress/documentation/)

= Key Features =

* **Product Synchronization** - Import products from your Shopify store with a single click
* **Collection Management** - Select which Shopify collections to sync and control what appears on your site
* **Batch Processing** - Efficiently handle large product catalogs with intelligent batch processing
* **Real-Time Progress Tracking** - Monitor sync progress with detailed status updates and product counts
* **Shopping Cart Integration** - Display a functional Shopify cart on your WordPress site via shortcode
* **Custom Post Types** - Products imported as WordPress custom post types for easy management
* **Collection Taxonomy** - Collections imported as WordPress taxonomies for organized browsing
* **Product Variants** - Full support for Shopify product variants
* **Image Galleries** - Beautiful product image galleries with Swiper slider integration
* **Responsive Design** - Mobile-friendly product displays and shopping cart

#### In Pro version
- **All Free Features**  
  _Connect your WordPress site to Shopify using OAuth 2.0 authentication with secure credential management and automatic token refresh_

- **Advanced Product Filters**  
  _Multi-level filtering including collection filters, vendor filters, product options, and price range slider with mobile-optimized drawer UI_

- **Dynamic Filter Configuration**  
  _Drag-and-drop filter ordering with show/hide toggles per filter, automatic generation from product data, and configurable visibility settings_

- **Smart Load More**  
  _Infinite scroll alternative with configurable products per load, active filter persistence, and empty state handling for better UX_

- **Real-Time Updates**  
  _Automatic product update tracking via Shopify webhooks (create/update/delete) with HMAC-SHA256 signature verification for security_

- **Pending Changes Tracking**  
  _Monitor product changes from Shopify in real-time and trigger automatic re-sync to keep your WordPress catalog up-to-date_

- **Enhanced Shopping Experience**  
  _Preview products instantly without leaving the page with light modal overlay featuring product details, images, and add-to-cart functionality_

- **Advanced Data Management**  
  _Automatic extraction and aggregation of product options, price ranges, and variants after sync for enhanced filtering capabilities_


= How It Works =

1. Create a custom app in your Shopify admin with the required API scopes
2. Enter your Shopify credentials in the WordPress admin
3. Select which collections you want to sync
4. Start the sync process and monitor progress
5. Products appear as custom posts in WordPress
6. Add the cart shortcode to display shopping functionality
7. Customers can browse products in WordPress and checkout through Shopify

= Use Cases =

* **Content-Rich Product Pages** - Use WordPress's powerful content management to create detailed product pages while maintaining Shopify's checkout
* **SEO Optimization** - Leverage WordPress SEO plugins to optimize product pages for search engines
* **Multi-Site Networks** - Each site can connect to a different Shopify store (requires separate custom apps)

== Installation ==

= WordPress Plugin Installation =

**Automatic Installation**

1. Log in to your WordPress admin panel
2. Navigate to Plugins > Add New
3. Search for "SyncKube - Products Sync for Shopify"
4. Click "Install Now" and then "Activate"
5. Go to Settings > SyncKube to configure

**Manual Installation**

1. Download the plugin zip file
2. Log in to your WordPress admin panel
3. Navigate to Plugins > Add New > Upload Plugin
4. Choose the downloaded zip file and click "Install Now"
5. Activate the plugin
6. Go to Settings > SyncKube to configure

### Shopify App Configuration

Before you can use SyncKube, you need to create a custom app in your Shopify store to generate API credentials.

You need to create a custom app in your Shopify admin to allow **SyncKube** to access your products.

1. **Log in to Shopify Admin:** Go to your Shopify store admin panel.  
2. **Navigate to Apps:** Click **Settings → Apps and sales channels**.  
3. **Develop apps:** Click **Develop apps** (or **Manage app development** if apps already exist).  
4. **Enable custom app development:** If prompted, enable custom app development for your store.
5. **Create an app:** Click **Create an app**.
6. **Name your app:** Enter **"SyncKube"** (or any name you prefer).
7. **App URL:** Enter your website URL (any URL is fine).  
8. **Embed app in Shopify admin:** **Uncheck** *Embed app in Shopify admin*.  
9. **Configure API scopes:** Click **Configure Admin API scopes** and select (or paste) the following scopes:
```
write_checkouts,read_checkouts,read_products,unauthenticated_write_checkouts,unauthenticated_read_checkouts,unauthenticated_read_product_listings,unauthenticated_read_selling_plans
```

10. **Save configuration:** Click **Release**.  
11. **Copy credentials:** From the left menu, click **Settings**, then:
 - **API key (Client ID):** Copy this value  
 - **API secret key (Client Secret):** Click **Reveal** and copy this value  
12. **Install the app:** From the left menu, click **Home**, then:
 - Under **Distribution**, click **Select distribution method**  
 - Choose **Custom distribution**  
 - Enter your Shopify Domain (example: `your-shop.myshopify.com`)  
 - Uncheck **Allow multi-store install for one Plus organization**  
 - Click **Generate link** and copy it  
 - From the left menu, click **API access requests → Storefront API → Enable Storefront API**  
 - Paste the generated link into a new browser tab, accept permissions, and click **Install**



**Step 6: Enter Credentials in WordPress**

1. Go to your WordPress admin panel
2. Navigate to Settings > SyncKube
3. Enter the following information:
   * **Shop Domain** - Your Shopify store domain (e.g., mystore.myshopify.com)
   * **Client ID** - The API key from Shopify
   * **Client Secret** - The API secret key from Shopify
4. Click "Save Changes"

**Important Notes:**
* Each WordPress installation requires its own Shopify custom app (see "App Distribution" section below).
* Keep your API credentials secure and never share them publicly.

== How to Use ==

= Initial Setup =

1. After installing the plugin and entering your Shopify credentials (see Installation section), go to Settings > SyncKube
2. Navigate to the "Collections" tab
3. Click "Fetch Collections" to retrieve all collections from your Shopify store
4. Select which collections you want to sync by checking the "Import" checkbox
5. Click "Save Changes"

= Starting Product Sync =

1. Navigate to the "Product Sync" tab in Settings > SyncKube
2. Click "Start Sync" to begin importing products
3. Monitor the progress bar and status messages
4. The sync runs in batches and will continue automatically in the background
5. Once complete, you'll see "Sync completed successfully"

= Accessing Synced Products =

* **In WordPress Admin**: Navigate to "Shopify Products" in the admin menu to view all imported products
* **Product Collections**: Collections appear as a taxonomy (similar to categories)
* **Single Product Pages**: Each product has its own page at: yoursite.com/shopify-product/product-name
* **Product Archives**: View all products at: yoursite.com/shopify-product/
* **Collection Archives**: View products by collection at: yoursite.com/collection/collection-name

== Shortcodes ==

SyncKube provides two shortcodes to display products and shopping cart functionality on your WordPress pages.

= [synckube_all_products_grid] =

Display a responsive grid of all your Shopify products with images, titles, prices, and collections. Includes automatic pagination.

**Usage Examples:**

`[synckube_all_products_grid]`
Display products with default settings (12 per page)

`[synckube_all_products_grid products_per_page="24"]`
Display 24 products per page

`[synckube_all_products_grid products_per_page="6"]`
Display 6 products per page

**Attributes:**

* `products_per_page` - Number of products to display per page (default: 12, type: number)

**Features:**

* Responsive grid layout that adapts to screen sizes
* Product images with lazy loading
* Product titles, prices, and collections
* Automatic pagination for easy browsing
* "View" button overlay on hover (desktop)
* Price ranges for products with variants

= [synckube_cart_toggle] =

Display a shopping cart button anywhere on your site, typically in your header, navigation menu, or sidebar.

**Usage Examples:**

`[synckube_cart_toggle]`
Display cart button with default settings

= Customizing Product URLs =

1. Go to Settings > SyncKube
2. In the "Settings" tab, find the "Rewrite Slug" fields
3. **Product Rewrite Slug** - Change the URL structure for products (default: shopify-product)
4. **Collection Rewrite Slug** - Change the URL structure for collections (default: collection)
5. Click "Save Changes"
6. Go to Settings > Permalinks and click "Save Changes" to flush rewrite rules

= Managing Synced Products =

* **Re-sync Products**: Click "Start Sync" again to update existing products and add new ones
* **Reset Sync**: If sync gets stuck, use the "Reset Sync" button to clear the sync state
* **Delete data**: To remove all synced products and saved data, uninstall the plugin

== Frequently Asked Questions ==

= How do I connect my Shopify store? =

You need to create a custom app in your Shopify admin to generate API credentials (Client ID, Client Secret). See the Installation section for detailed step-by-step instructions.

= What happens to existing products when I re-sync? =

Existing products are updated with the latest information from Shopify. New products are added, and products that no longer exist in the selected collections are removed during the cleanup phase.

= How often does the sync run? =

The sync process uses WordPress cron to run in batches. After you manually start a sync, it continues automatically in the background until all products are imported.

= Can I customize product and collection URLs? =

Yes! Go to Settings > SyncKube and modify the "Product Rewrite Slug" and "Collection Rewrite Slug" fields. After saving, visit Settings > Permalinks and click "Save Changes" to update your URL structure.

= How do I display the shopping cart on my site? =

Use the shortcode `[synckube_cart_toggle]` anywhere on your site.

= What if the sync fails or gets stuck? =

If the sync appears stuck:
1. Check that your Shopify API credentials are correct
2. Try clicking "Reset Sync" to clear the sync state, then start a new sync
3. Check your PHP error logs for any server-side issues

= Can I use one custom app for multiple WordPress sites? =

No. Shopify custom apps are designed for single-store, single-domain use. Each WordPress installation requires its own custom app in Shopify. See the "App Distribution" section for details.

= Will synced products be deleted if I deactivate the plugin? =

No. Products remain in your WordPress database when you deactivate the plugin. However, if you uninstall the plugin (delete it), all synced products, collections, and settings will be permanently removed.

= Do customers checkout on WordPress or Shopify? =

Customers browse products on WordPress but checkout through Shopify's secure checkout system. The shopping cart widget redirects to your Shopify store for payment processing.

= Can I edit product information in WordPress? =

The plugin syncs product data from Shopify to WordPress. Any edits made in WordPress will be overwritten when you re-sync. All product edits should be made in your Shopify admin.

= What Shopify plan do I need? =

Custom apps are available on all Shopify plans, including the Basic plan. You just need store owner or staff access to create custom apps.

== External Services ==

This plugin connects to external third-party services to function properly. Below is detailed information about each service:

= Shopify Admin API =

**What it is:** Shopify's Admin API for accessing store data

**What it's used for:**
* Fetching product information (titles, descriptions, prices, variants, images...)
* Retrieving collection data
* Accessing shop metadata
* Authenticating API requests

= Shopify Storefront API =

**What it is:** Shopify's Storefront API for customer-facing shopping functionality

**What it's used for:**
* Displaying real-time product prices and availability to site visitors
* Enabling shopping cart functionality on your WordPress site
* Processing add-to-cart actions
* Managing checkout sessions

= Important Privacy Notes =

* This plugin does not collect, store, or process customer payment information
* All payment processing happens on Shopify's secure servers
* Product browsing data may be subject to Shopify's analytics and tracking
* Review Shopify's privacy policy and ensure your site's privacy policy reflects the use of Shopify services

== App Distribution and Single Domain Usage ==

**IMPORTANT: Shopify Custom Apps Are Single-Domain Only**

Shopify custom apps are designed for use with a single store and single domain. This is a Shopify platform limitation, not a plugin limitation.

= What This Means =

* Each WordPress installation requires its own Shopify custom app
* You cannot use one custom app across multiple WordPress sites
* If you have multiple WordPress sites, you'll need to create a separate custom app for each one
* Custom app credentials are tied to specific API access tokens that cannot be shared

= Why This Limitation Exists =

* **Security**: Shopify custom apps use OAuth authentication tied to specific domains
* **Access Control**: Each app has its own access token that should not be shared across domains
* **Terms of Service**: Sharing custom app credentials violates Shopify's API terms of service
* **Audit Trail**: Shopify tracks API usage per app for security and rate limiting

= Rate Limits =

Shopify enforces API rate limits per custom app:
* Admin API: 4 requests per second (40 points/second leaky bucket)
* Storefront API: Higher limits for customer-facing requests
* The plugin implements efficient batching to stay within limits


== Credits (third-party libraries) ==

This plugin uses the following open-source libraries:

* [Bootstrap](https://getbootstrap.com/) - Frontend framework for responsive design
* [Toastr](https://github.com/CodeSeven/toastr) - JavaScript notification library
* [Swiper](https://swiperjs.com/) - Modern touch slider for product image galleries
* [Shopify Web Components](https://github.com/Shopify/hydrogen) - Official Shopify storefront components

== Screenshots ==

1. Frontend popup product
2. Frontend - product list
3. Admin Shopify collections
4. Admin credentials

== Changelog ==

= 1.0.1 =
Update docs

= 1.0.0 =
Initial release of SyncKube - Seamlessly sync your Shopify products into WordPress with integrated shopping cart functionality.