Supsystic Gallery Ecommerce: detailed tutorial

This tutorial explains how the Ecommerce module works, how to configure it from the WordPress admin area,
how customers see restrictions on the frontend, how access is granted after purchase, and how protected
image delivery works for thumbnails, popups, resolutions, watermarks, and original files.

The goal of Ecommerce is to let a site owner sell access to gallery content without turning the whole
gallery into a separate shop. A purchasable Ecommerce Item can protect a gallery group, a gallery, or
selected gallery images. Depending on the item settings, visitors can either buy private access to the
protected content or buy full-resolution downloads while still seeing a smaller preview.

Table of contents

1. Implementation and setup plan
2. Core concepts
3. Admin tabs overview
4. Main Settings
5. Payment Providers
6. Checkout Page
7. Design & Labels
8. Ecommerce Items
9. Entity Type
10. Unlock Mode
11. Access Type
12. Image Delivery Settings
13. Gallery image Ecommerce modal
14. Frontend flow: Private access
15. Frontend flow: Full resolution
16. Login and access restore flow
17. Checkout and payment flow
18. Orders and access management
19. Protected image delivery
20. Watermark behavior
21. Original file protection
22. Troubleshooting

1. Implementation and setup plan

A complete Ecommerce setup should be done in this order. This order prevents most confusion because each
later step depends on data from the previous step.

1. Enable Ecommerce.
   Go to Ecommerce > Main Settings and enable Ecommerce restrictions and checkout.
2. Review protection options.
   Keep the default protection options enabled unless you have a specific reason to expose restricted images
   through srcset, REST responses, or sitemaps.
3. Configure currency.
   Prices are stored in cents. For example, 500 means 5.00 USD.
4. Configure payment providers.
   Enable PayPal or Stripe and add credentials. Test mode can be used while checking the flow.
5. Configure the checkout page.
   Set the page URL and customer-facing checkout labels.
6. Configure Design & Labels.
   Set popup labels, thumbnail labels, login modal labels, colors, and button text before publishing.
7. Create Ecommerce Items.
   Choose what each item protects: a gallery group, one gallery, or one or more gallery images.
8. Choose Unlock Mode.
   Use Private access when the content itself should be hidden until access is granted. Use Full resolution
   when previews can remain visible but high-quality downloads require purchase.
9. Choose Access Type.
   Use Access Key, Email + Password, or WordPress User depending on how customers should prove access.
10. Set resolutions and watermark behavior.
    Configure free image size, paid resolutions, and whether the original should be shown without watermark.
11. Save and test as logged-out and logged-in customers.
    Always test both states because thumbnails, popup sidebars, download buttons, and login controls change
    depending on access.

Back to top

2. Core concepts

Ecommerce Item

An Ecommerce Item is the central rule that says: this entity is protected, this is the price, this is the
access term, this is the unlock behavior, and these are the image delivery rules. Orders and access rows are
created from Ecommerce Items.

Entity

Entity means the gallery content controlled by an item. The module supports three entity types:

• Gallery Group: protects all galleries that belong to the selected group.
• Gallery: protects every image in one gallery.
• Gallery Image: protects specific image records. Multiple gallery images can be selected.

Access

Access is the permission created after a paid order is completed or manually marked as paid. Access has a
status, a start date, and an expiration date. Frontend checks read the current visitor identity and compare it
against active access rows.

Additional JSON

Additional JSON stores image delivery rules that do not deserve separate database columns: free image size,
paid resolution list, popup/sidebar options, placeholder image, and watermark override flags.

Protected image URL

Paid downloads are served through a dynamic admin-ajax endpoint instead of exposing the original file URL
directly. The endpoint validates access, generates the requested resolution when needed, optionally applies
the gallery watermark, and streams the result.

Back to top

3. Admin tabs overview

The Ecommerce admin has several tabs. Each tab controls a different part of the customer journey.

Tab	Purpose	When to use it
Main Settings	Turns Ecommerce on and controls protection behavior.	Use first, before creating production items.
Payment Providers	Stores PayPal and Stripe settings.	Use before public checkout.
Checkout Page	Controls the checkout URL and checkout labels.	Use when embedding the checkout shortcode/page.
Design & Labels	Controls frontend text, popup labels, login labels, and visual colors.	Use before publishing to match the website language and design.
Items	Creates purchasable protection rules.	Use for every gallery, group, or image that should be sold.
Orders	Shows purchases and lets admin manage access.	Use for support, manual payment, revoke, and restore actions.

Back to top

4. Main Settings

Ecommerce is active

This checkbox turns on the customer-facing restrictions, checkout routes, and access checks. If this is off,
Ecommerce Items can still exist in the database, but frontend locking should not be treated as active.

Currency

Currency is the three-letter currency code used for display and payment validation. Examples: USD, EUR, GBP.
Prices in Items are stored as minor units, so 500 means 5.00 in the selected currency.

Hide restricted originals from srcset

WordPress can output multiple image sizes through srcset. When a restricted original is included in srcset,
a visitor or crawler may discover a direct uploads URL. This option removes restricted attachments from srcset
output.

Hide restricted originals from REST

WordPress REST attachment responses can include direct image URLs. This option removes sensitive URL fields
for attachments covered by active restriction items.

Exclude from sitemap

This excludes restricted attachments from WordPress core attachment sitemaps. It reduces the chance that
search engines or third-party tools discover direct uploads URLs.

Exclude from Yoast sitemap

This adds restricted attachment IDs to Yoast SEO sitemap exclusions and filters sitemap entries when needed.
Use it if Yoast SEO is installed.

Exclude from Rank Math sitemap

This filters restricted attachment entries from Rank Math sitemap output. Use it if Rank Math is installed.

Regenerate protected filenames

This action renames original files for attachments covered by active Ecommerce restriction items. WordPress
resized thumbnails are intentionally left unchanged. The goal is to make original file URLs hard to guess.

Original filename regeneration also runs automatically when Ecommerce Items are saved or when image-level
Ecommerce settings are saved.

Back to top

5. Payment Providers

The module supports PayPal and Stripe provider classes. A provider is available only when it is enabled and
required credentials are present.

PayPal

• Enable PayPal in Ecommerce > Payment Providers.
• Add the PayPal email used to receive payments.
• Use test mode while checking the purchase cycle.
• When PayPal confirms payment, the module validates order ID, amount, and currency before granting access.

Stripe

• Enable Stripe in Ecommerce > Payment Providers.
• Add public and secret keys.
• Use test mode while checking card payments.
• The provider creates a checkout URL from the pending order and redirects the customer to Stripe.

Back to top

6. Checkout Page

Checkout settings control where the customer is sent after clicking Buy and what labels are shown during
checkout. The checkout page should contain the Ecommerce checkout output and should be reachable from the
public frontend.

• Checkout URL: page where the checkout flow is rendered.
• Title: heading shown on the checkout page.
• Description: optional explanatory text.
• Buy label: text for the main purchase button.
• Authorize label: text for access authorization actions.
• Payment Method label: label above available payment providers.
• Total label: label before the total price.
• Success/Pending/Failed/Expired labels: messages shown after payment or access state changes.

Back to top

7. Design & Labels

Design & Labels is where the admin customizes frontend text and visual settings without editing code.
The module separates popup styles from thumbnail styles because those surfaces behave differently.

Restrict Texts

• Popup title: title shown in the popup side panel.
• Popup description: short text below the popup title.
• Price label: label shown before the price.
• Resolutions label: heading above the available resolution list.
• Popup buy button: text of the Buy license button inside the popup.
• Thumbnail buy button: text of the Buy button on thumbnail overlays.

Access Login Texts

• Or label: separator between Buy and Login actions.
• Login button: opens the access modal for access key or email/password.
• WordPress login URL: used only for WordPress User access type.
• Login modal title and description: text shown above access fields.
• Access key label and placeholder: shown when the item uses Access Key.
• Email and password labels/placeholders: shown when the item uses Email + Password.
• Submit button: button used inside the modal.
• Success label: message after access is confirmed.
• Error label: message after access validation fails.

Popup Styles

Popup styles control the right-side popup Ecommerce panel: title color, title size, description color,
description size, body text color, resolution heading color, resolution borders, Buy button colors, Login
button colors, Download button colors, and popup button font size.

Thumbnail Styles

Thumbnail styles control the overlay shown on locked thumbnails: overlay background, title color, text color,
Buy button colors, Login button colors, and thumbnail button font size.

Back to top

8. Ecommerce Items

Items are the most important part of the module. Every frontend restriction starts from an active item.
An item can be active or inactive. Inactive items remain saved but should not lock content or appear in
checkout.

Item fields

• Name: public name shown in checkout and stored as an order snapshot.
• Description: customer-facing description. On locked thumbnails it can appear as help/tooltip text.
• Entity Type: decides whether the item controls a group, gallery, or gallery image.
• Entity: AJAX searchable selector for the selected entity.
• Active: controls whether the item is currently enforced.
• Unlock Mode: Private access or Full resolution.
• Term, days: how long access remains active after successful payment.
• Price, cents: minor currency units. 500 means 5.00 USD.
• Access Type: how the customer proves access later.
• Image Delivery Settings: free/pro resolutions, watermark override, placeholder, popup placement.
• Sort Order: lower values are preferred when more than one item can match the same photo.

Item priority

A photo can be covered by several items: one image item, one gallery item, and one group item. The module
resolves the best matching item using entity priority and sort order. Image-specific items are the most direct,
then gallery items, then group items. Sort order helps when more than one item could apply at the same level.

Back to top

9. Entity Type

Gallery Group

Use Gallery Group when one purchase should unlock every gallery inside a group. This is useful for collections,
events, clients, categories, or albums that contain several galleries.

Gallery

Use Gallery when one purchase should unlock every image inside one gallery. This is the simplest option for
most paid galleries.

Gallery Image

Use Gallery Image when only specific images should be purchasable or protected. The entity selector supports
multiple selected images. When searching gallery images, the label is shown as gallery name, then image name
after a dash, for example: Wedding Gallery - IMG_1024.

If multiple gallery images are selected and saved, the module creates or updates separate Ecommerce Items for
those selected images while keeping the same delivery settings.

Back to top

10. Unlock Mode

Private access

Private access is used when the protected content itself should not be available until the customer has access.
Locked visitors see the restriction only on the thumbnail. There is no “Where to show access restricts” selector
for Private access because private content is locked at thumbnail level by design.

After the visitor becomes authorized, the normal thumbnail is shown. If the gallery has popup enabled, the popup
can also show the resolution sidebar when “Show resolution sidebar in popup” is enabled for that item.

Full resolution

Full resolution is used when visitors may see previews but need to pay for high-quality downloads. This mode
supports “Where to show access restricts”:

• On thumbnail: the buy/login overlay is shown on the thumbnail.
• On popup (slidebox): the thumbnail remains visually normal, and the Ecommerce panel appears inside the popup.

In Full resolution mode, free image size controls what non-authorized visitors can see. Paid users receive
maximum-quality protected downloads according to the configured paid resolution list.

Back to top

11. Access Type

The admin label is “Access Type”. The database column is still named user_type for compatibility.

Access Key

The customer receives or enters an access key. The key is stored as a secure hash in the access table. On the
frontend, the Login button opens a modal with an access key field. If the key matches active access for the
current item, a secure cookie remembers the key.

Email + Password

The customer enters email and password. The password is generated when access is created and stored as a WordPress
password hash. On successful validation, a secure access-session cookie is stored.

WordPress User

The customer must be logged in as the WordPress user connected to the order. The gallery does not perform
WordPress authorization itself. The Login button sends the visitor to the WordPress login URL configured in
Design & Labels.

Back to top

12. Image Delivery Settings

Show original without watermark

When enabled, paid protected image delivery can show the original without adding the gallery watermark. When
disabled and the gallery watermark is enabled, paid downloads are streamed with watermark applied.

Image resolution free

Free resolution controls the size used for non-authorized preview images. Width and height are numbers in pixels.
If one side is set to 0, the module calculates it automatically using the original aspect ratio.

Examples:

• width: 400, height: 0 means create a 400px wide image and calculate height proportionally.
• width: 0, height: 300 means create a 300px high image and calculate width proportionally.
• width: 400, height: 267 means create exactly 400 by 267 without crop.

Image resolution pro

Paid resolutions are shown in the popup sidebar. For authorized visitors, each paid resolution has a Download
button. For non-authorized visitors, the resolution list can be shown without download buttons so the customer
understands what will be available after purchase.

Where to show access restricts

This setting exists only for Full resolution items. It controls whether restriction UI is shown on the thumbnail
or inside the popup. Private access always restricts on thumbnail before authorization.

Show resolution sidebar in popup

This setting is for Private access after authorization. If enabled, authorized users see the popup sidebar with
resolution download buttons. If disabled, the popup behaves like the normal gallery popup.

Image placeholder

Placeholder is available for Private access. Before authorization, the selected placeholder image can be shown
on the thumbnail instead of the locked original thumbnail. The placeholder uses cover behavior so it fills the
thumbnail area cleanly. The text inside the placeholder comes from the Ecommerce Item description.

Back to top

13. Gallery image Ecommerce modal

In the gallery Images List, each image can open an Ecommerce settings modal. This is a quick image-level editor
for the settings that concern the image delivery itself.

The modal can show:

• Current image-level Ecommerce Item state.
• A link to open the full Ecommerce Item settings.
• Show original without watermark checkbox.
• Image resolution free width and height.
• Image resolution pro rows.
• Show JSON button with readonly Additional JSON preview.

Saving this modal updates or creates a gallery-image Ecommerce Item. The item may be inactive by default if it
was created only to store image delivery settings. Saving also triggers protected original filename regeneration
for the affected image item.

Back to top

14. Frontend flow: Private access

Visitor without access

• The image is considered locked if an active Private access item matches it.
• The restriction appears on the thumbnail.
• If a placeholder is configured, the placeholder image is shown instead of the protected thumbnail.
• If the Ecommerce Item description is filled, it can appear inside the placeholder and/or help tooltip where relevant.
• The visitor sees Buy and Login actions.
• Clicking Buy sends the visitor to checkout.
• Clicking Login opens access-key or email/password modal, or redirects to WordPress login for WordPress User access.

Authorized visitor

• The normal thumbnail is shown.
• The locked tooltip/help icon is not shown because the visitor already has access.
• If gallery popup is enabled, the popup opens normally.
• If “Show resolution sidebar in popup” is enabled, the popup also shows resolution downloads.

Back to top

15. Frontend flow: Full resolution

Restriction on thumbnail

When placement is “On thumbnail”, the visitor sees the gallery thumbnail with the Ecommerce overlay. The image
still respects the gallery thumbnail sizing and crop behavior; the restriction layer should not distort the
gallery layout.

Restriction on popup

When placement is “On popup (slidebox)”, the thumbnail remains normal. The popup opens and shows the Ecommerce
sidebar on the right side. This sidebar includes item name, description, price, available resolutions, Buy button,
and Login action.

Authorized visitor

After access is confirmed, the popup sidebar changes from purchase mode to download mode. Paid resolutions show
Download buttons. The image itself should be delivered in maximum quality for the requested resolution.

Back to top

16. Login and access restore flow

Login is not the same as payment. Login means the visitor already has access and needs to prove it again.

Access Key login

1. Visitor clicks Login.
2. Modal opens with access key input.
3. Visitor enters the key.
4. Frontend sends an AJAX validation request.
5. Backend hashes the entered key and looks for active access rows matching the current image, gallery, or group.
6. If valid, the key is remembered in a secure cookie.
7. The page can reload or refresh the protected image state.

Email + Password login

1. Visitor clicks Login.
2. Modal opens with email and password fields.
3. Backend finds active access rows by email.
4. Password is checked with WordPress password hashing.
5. If valid, an access-session cookie is created.

WordPress User login

The frontend redirects the visitor to the configured WordPress login URL. The module then relies on normal
WordPress login state and current user ID.

Back to top

17. Checkout and payment flow

1. Visitor clicks Buy from thumbnail or popup.
2. The checkout page receives the selected Ecommerce Item ID.
3. The checkout form creates a pending order from the item snapshot.
4. The order stores item name, description, entity type, entity ID, unlock mode, access type, term, amount, currency, and additional JSON snapshot.
5. The selected payment provider creates a checkout URL.
6. Visitor completes payment through the provider.
7. The provider callback or admin action marks the order paid.
8. The module creates or activates access.
9. The customer receives or uses the correct access method.

The order stores a snapshot of the item at the time of purchase. This is important because future changes to
the Ecommerce Item should not rewrite the historical order description or payment amount.

Back to top

18. Orders and access management

The Orders tab is used for support and manual control.

• Orders list: shows orders with pagination and search.
• View order: shows order data, provider payload, and access row.
• Mark paid: manually completes an order and creates access.
• Mark failed: marks payment failed and revokes access.
• Revoke access: disables access without deleting the order.
• Restore access: reactivates an existing access row.

When manual payment creates a new access key or password, the admin view temporarily shows those credentials
through a short-lived transient. This protects credentials from being displayed forever in the admin.

Back to top

19. Protected image delivery

Protected image delivery is handled by an admin-ajax endpoint. The URL contains gallery ID, photo ID, attachment
ID, and optional requested width and height.

https://example.com/wp-admin/admin-ajax.php?action=sg_ecommerce_image&gallery_id=52&photo_id=151&attachment_id=2159&sgg_width=400&sgg_height=267

The endpoint does the following:

1. Reads gallery ID, photo ID, attachment ID, width, and height from the request.
2. Validates that the photo really uses the requested attachment.
3. Builds the access state for the photo.
4. Blocks the request with 403 if the photo is still locked.
5. Finds the original attachment file on disk.
6. Generates a resized file if width or height is requested.
7. If only width or only height is set, calculates the missing side by aspect ratio.
8. Applies watermark to the streamed download when needed.
9. Sends no-cache headers, content type, content length, and streams the image.

This is why paid download buttons should point to protected URLs instead of direct uploads URLs.

Back to top

20. Watermark behavior

Watermark behavior depends on both Ecommerce Item settings and gallery watermark settings.

• If gallery watermark is disabled, Ecommerce cannot apply that gallery watermark during protected download.
• If “Show original without watermark” is enabled, paid delivery may return the original without watermark.
• If “Show original without watermark” is disabled and gallery watermark is enabled, protected downloads are watermarked.
• Free previews should obey free image size and normal gallery watermark rules.
• Paid downloads should use the protected endpoint and maximum available quality for the requested resolution.

The protected endpoint uses the Pro attachment watermark engine. The module passes the gallery watermark settings
into that engine, asks it to create a watermarked file if one does not already exist, and streams the watermarked
file instead of the clean resized file.

Back to top

21. Original file protection

The current first-stage original protection is based on encoded original filenames. When a gallery, group, or
image is covered by an active restriction item, the original attachment filename can be renamed to a long generated
name. A visitor cannot guess the original URL unless some other mechanism reveals it.

Important limitation

This is not the same as server-level private storage. Files are still physically in wp-content/uploads. Therefore
the practical security goal is to avoid exposing exact original URLs.

Admin controls that help

• Hide restricted originals from srcset.
• Hide restricted originals from REST attachment responses.
• Exclude restricted originals from WordPress core sitemaps.
• Exclude restricted originals from Yoast SEO sitemaps.
• Exclude restricted originals from Rank Math sitemaps.
• Regenerate protected filenames manually when needed.

Recommended external precautions

• Do not place original URLs manually in posts, pages, custom fields, or theme templates.
• Do not expose original URLs in public logs or analytics payloads.
• Review CDN cache/index behavior if a CDN is used.
• Review SEO plugin media settings.
• For stronger protection in future versions, consider moving originals outside public uploads and serving them only through gated PHP routes.

Back to top

22. Troubleshooting

Item does not lock anything

• Check that Ecommerce is active in Main Settings.
• Check that the item is Active.
• Check that Entity Type and Entity point to the expected group, gallery, or image.
• Check whether another item with lower sort order is taking priority.
• Clear gallery cache after changing item settings.

Popup sidebar is missing

• For Full resolution, check that placement is “On popup (slidebox)”.
• For Private access, check that the visitor is authorized and “Show resolution sidebar in popup” is enabled.
• Check that the gallery popup itself is enabled.
• Check the active theme/template because popup engines can differ between Colorbox and PrettyPhoto.

Download has no watermark

• Check that gallery watermark is enabled.
• Check that the Ecommerce Item has show_original_without_watermark set to 0.
• Check that the download URL uses sg_ecommerce_image and not direct wp-content/uploads URL.
• Clear browser cache or add a cache-busting query parameter while testing.
• Check that the generated watermarked file exists in uploads.

Free preview size is wrong

• Check img_resolution_free in Additional JSON preview.
• If width or height is 0, remember that the missing side is calculated by aspect ratio.
• Check whether the current gallery template is using thumbnail, popup, or protected URL for that state.

Access login fails

• Check that the order is paid and access status is active.
• Check that access has not expired.
• For Access Key, verify that the customer copied the complete key.
• For Email + Password, verify the exact email used for purchase.
• For WordPress User, verify that the user is logged in to the correct WordPress account.

Original URL is still visible somewhere

• Enable srcset, REST, core sitemap, Yoast, and Rank Math protection options.
• Regenerate protected filenames.
• Search page source for wp-content/uploads URLs.
• Check custom theme templates and shortcode wrappers.
• Check CDN and SEO plugin caches.

Back to top