Envato Market Integration

Connect your Larapen site to the Envato Marketplace API. Verify customer purchase codes, manage buyers, and gate access to helpcenter, forum, and knowledge base by purchase ownership.

Use Cases

CodeCanyon Plugin Author

You sell a premium WordPress plugin or Laravel package on CodeCanyon. You run a support site on Larapen with a helpcenter.

• Import your CodeCanyon items into Larapen.
• Link each item to a helpcenter department (e.g. “Plugin Support”).
• Enable “Require Purchase for HelpCenter”: only verified buyers can submit tickets.
• Customers connect their Envato account via OAuth and their purchases are auto-synced.

ThemeForest Author with Community Forum

You sell multiple themes and want a community forum gated by product.

• Create a forum category for each theme.
• Link each Envato item to its forum category.
• Enable “Require Purchase for Forum”: buyers can only post in forums for items they own.

Knowledge Base with Premium Content

You have a knowledge base with product-specific documentation that should only be accessible to buyers.

• Link Envato items to KB collections.
• Enable “Restrict KB by Purchase”: non-buyers see a “Purchase Required” page.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+
• MySQL 8.0+
• An Envato personal API token (see Creating an Envato Token)
• At least one of: HelpCenter or Forum add-on (for access gating features)

Installation

Step 1: Place the Add-on

Copy or symlink the envato folder into your Larapen "extensions/addons" directory:

Step 2: Activate the Add-on

Go to Admin → Add-ons → Installed Add-ons and activate Envato Market Integration.

Step 3: Run Migrations

This creates 3 tables: envato_items, envato_user_purchases, and envato_item_links. It also adds OAuth token columns (provider_token, provider_refresh_token, provider_token_expires_at) to the users table.

Step 4: Set Permissions

The add-on registers 10 permissions (see Permissions). Assign them to admin roles via Admin → Users → Roles & Permissions.

Step 5: Configure

Navigate to Admin → Envato → Settings and enter your Envato API token and author username. Use the Test Connection button to verify. See Configuration.

Step 6: Configure OAuth (Optional)

To allow customers to connect their Envato accounts via OAuth:

1. Register an app at build.envato.com.
2. Set the callback URL to https://yoursite.com/auth/envato/callback.
3. In Admin → Settings → Social Auth, enable the Envato driver and enter the Client ID and Client Secret.

Configuration

All settings are managed in Admin → Envato → Settings (stored in the settings table, group envato).

Setting	Description	Default
envato_api_token	Personal Envato API token for author-level API calls (verify sales, import items).	(empty)
envato_author_username	Your Envato Marketplace username.	(empty)
envato_require_email_match	When enabled, the buyer’s Envato email must match their site account email for purchase verification to succeed.	false
envato_helpcenter_require_purchase	Gate helpcenter ticket creation behind a verified Envato purchase.	false
envato_forum_require_purchase	Gate forum thread creation behind a verified Envato purchase.	false
envato_kb_restrict_by_purchase	Restrict knowledge base collection access to buyers of linked items.	false

Environment Variables

OAuth Configuration (Social Auth)

Envato OAuth is configured through the core Social Auth settings, not the add-on directly:

• social_auth_envato_enabled: Enable/disable the Envato OAuth driver
• social_auth_envato_client_id: OAuth Client ID from build.envato.com
• social_auth_envato_client_secret: OAuth Client Secret

Creating an Envato Token

1. Go to build.envato.com/create-token.
2. Give it a descriptive name (e.g. “Larapen Support Site”).
3. Enable these permissions:
   • View and search Envato sites
   • View the user’s Envato Account username
   • View the user’s email address
   • View the user’s account profile details
   • View the user’s items’ sales history
4. Copy the generated token and paste it in Admin → Envato → Settings.

Admin: Settings

The settings page (Envato → Settings) is organized into four sections:

API Configuration

• Personal Token: Masked password field with show/hide toggle.
• Author Username: Your Envato Marketplace username.
• Test Connection button: AJAX call that tests the token in real time (works with unsaved values typed into the form). Returns the resolved username on success.

Add-on Dependencies

Displays badges showing whether the HelpCenter and Forum add-ons are currently active. A warning is shown if neither is active (since access gating requires at least one).

Integration Settings

Toggle switches shown conditionally based on which add-ons are active:

• Require Purchase for HelpCenter: shown if HelpCenter is active
• Restrict KB by Purchase: shown if HelpCenter is active (KB is part of HelpCenter)
• Require Purchase for Forum: shown if Forum is active

Verification Options

• Require Email Match: when enabled, the buyer’s Envato email must match their site account email.

Admin: Items

The Items page (Envato → Items) manages your local catalog of Envato Marketplace items.

Items List

A sortable, paginated table (20 per page) showing:

• Thumbnail: item icon from Envato
• Name & Envato ID
• Marketplace site (e.g. codecanyon, themeforest)
• Price (formatted from cents)
• Sales count
• Link count: how many entities (departments, categories, collections) this item is linked to
• Last synced date

Per-item actions: View, Manage Links, Delete. Bulk delete with checkbox selection.

Importing Items

Click Import from Envato to start a JavaScript-driven sequential import:

1. The UI sends POST admin/envato/items/import?page=1.
2. The server fetches one page (up to 10 items) from the Envato author/sales endpoint.
3. For each new item (not already in DB), it calls getCatalogItem() to get full details.
4. A progress bar updates in real time showing: new items imported, items skipped (duplicates), pages processed.
5. If hasMore = true, the JS automatically requests the next page.

Item Detail & Sync

The item detail page (Envato → Items → {item}) shows:

• Item info card: thumbnail, name, Envato ID, marketplace, author, price, sales count, rating, “View on Envato” link
• Sync Now button: re-fetches the item from the Envato catalog API and updates all fields
• Add Purchase Code form: admin can manually add a known purchase code for this item
• Purchases table: all verified purchases for this item, showing buyer username, linked site user, email, purchase code (full, visible to admin), license type, amount, sold date
• Linked entities sidebar: departments, categories, collections linked to this item

Admin: Item Links

Item Links (Envato → Item Links) define which helpcenter departments, forum categories, and KB collections require ownership of specific Envato items.

Links List

A table of all active items with their current linked entities shown as badges. Click “Edit” to manage links for a specific item.

Editing Links

The edit page shows one card per available entity type (only types with active add-ons are shown):

• HelpCenter Departments: checkboxes for each active department (if HelpCenter is active)
• Forum Categories: checkboxes for each active forum category (if Forum is active)
• KB Collections: checkboxes for each active KB collection (if HelpCenter is active)

Saving replaces all existing links for the item with the selected ones.

Admin: Customers

The Customers page (Envato → Customers) provides an aggregated view of all buyers.

Customers List

Purchases are grouped by buyer_username, showing:

• Envato username
• Email
• Linked site account (if any)
• Purchases count & Items count
• Total spent
• Support status (active/expired badge)
• Last purchase date

Searchable by buyer username, buyer email, or linked user name/email.

Customer Detail

Click a customer row to see their full purchase history:

• Sidebar: username, email, linked site account with “Revoke Link” button, stats grid (purchases, items, total spent, verified count), support status alert
• Purchases table: item thumbnail, item name, purchase code, license type, amount, sold date, support expiry badge

Revoking a Link

The Revoke Link action:

1. Removes all envato_user_purchases records for the buyer
2. Clears the user’s Envato OAuth data (provider, provider_id, provider_token, etc.)
3. The user loses access to all purchase-gated features immediately

Linked Accounts

The Linked Accounts page (Envato → Linked Accounts) shows all site users who have connected their Envato account via OAuth.

• Site user: avatar, name, email
• Envato username badge
• Purchases count
• Linked at date

Per-row actions:

• Sync Purchases (AJAX): calls the Envato buyer/purchases endpoint using the user’s stored OAuth token and imports any new purchases. Updates the count badge inline.
• View Purchases: navigates to the customer detail page
• Revoke Link: disconnects the Envato account and removes all purchases

OAuth Flow

The Envato OAuth integration uses Laravel Socialite and is handled by the core SocialAuthController.

For New Users (Login/Register)

1. User clicks “Login with Envato” on the login page.
2. Redirected to Envato’s OAuth authorization page.
3. After approval, Envato redirects back to /auth/envato/callback.
4. The system finds or creates a user account (matching by Envato username, then email).
5. OAuth tokens (provider_token, provider_refresh_token, provider_token_expires_at) are stored on the users table.
6. All the user’s Envato purchases are automatically synced via syncUserPurchases().
7. User is logged in and redirected.

For Existing Users (Linking Account)

1. Authenticated user clicks “Connect Envato Account” on the My Purchases page.
2. Redirected to Envato OAuth.
3. After approval, the callback links the Envato account to the existing user.
4. Revalidation: Any existing purchases that belong to a different Envato buyer are removed.
5. Sync: All new purchases from the buyer’s account are imported.
6. User is redirected back to the My Purchases page with a summary message.

Token Refresh

The EnvatoApiClient::getBuyerPurchases() method automatically checks token expiry. If the token is expired (or expires within 5 minutes), it calls refreshUserToken() which uses the stored refresh token to get a new access token from the Envato API. The new token is saved to the database transparently.

My Purchases

The front-end purchases page is available at /{locale}/envato/purchases (requires authentication).

URL & Routes

Method	URL	Route Name	Description
GET	/{locale}/envato/purchases	envato.purchases.localized	My Purchases page
POST	/{locale}/envato/purchases/add	envato.purchases.store.localized	Add a purchase code
DELETE	/{locale}/envato/purchases/disconnect	envato.purchases.disconnect.localized	Disconnect Envato account
DELETE	/{locale}/envato/purchases/{id}	envato.purchases.destroy.localized	Remove a specific purchase

Non-localized variants (without {locale}) are also registered.

Page Layout

Three-column responsive layout (col-lg-8 + col-lg-4):

Main Content

• Not connected: A styled “Connect Your Envato Account” card with an Envato-green connect button. Shows a warning if OAuth is disabled in settings.
• Connected: A “Connected as {username}” badge with a Disconnect button.
• Add Purchase Code form: text input for the purchase code (UUID format) + submit button. Only shown when the user’s Envato account is connected.
• Verified Purchases list: each purchase shows: item thumbnail, name, masked purchase code, license type, support expiry date, verification date, and a Remove button.

Sidebar

• Envato Account status card (connected/not-connected badge, connect/disconnect action)
• Need Support? card with helpcenter link (shown only if HelpCenter add-on is active)
• Help tips list

Disconnecting

When a user disconnects their Envato account:

1. All their envato_user_purchases records are deleted.
2. The provider, provider_id, provider_token, provider_refresh_token, provider_token_expires_at, and provider_avatar columns on the users table are set to null.
3. They lose access to all purchase-gated features immediately.

Purchase Validation Flow

When a user submits a purchase code (via the My Purchases page), the system follows this validation flow:

1. Check local database: is this purchase code already in envato_user_purchases? If so, check ownership:
   • If the code belongs to the current user: return “already added”.
   • If the code belongs to another user: return already_used error.
2. Verify via Envato API: call author/sale?code={code} using the author’s personal token.
3. Find or create item: match the response’s item.id to a local envato_items record. If not found, auto-create the item from the API response.
4. Buyer identity check: verify the user is the actual buyer using this priority:
   1. Envato OAuth match: provider = 'envato' AND provider_id = buyer_username (most reliable)
   2. Name match: user’s name matches buyer username
   3. Email prefix match: email prefix matches buyer username
5. Create purchase record: insert into envato_user_purchases with verification data.
6. Auto-register license: if the Licenses add-on is active, automatically create a LicenseKey record (see Licenses Integration).

Validation Statuses

Status	Description
valid	Purchase code verified and added successfully.
invalid	Purchase code not found on Envato or does not belong to the configured author.
already_used	Purchase code is already registered by another user on this site.
email_mismatch	Email match is required but the buyer’s email doesn’t match the user’s email.
item_mismatch	The purchase code is valid but belongs to a different item than expected.
api_error	An error occurred communicating with the Envato API (network error, invalid token, etc.).

Access Control: Purchase Gating

The EnvatoPurchaseValidator is the central utility for access control decisions. It is registered as an IoC binding (envato.access.checker) so other add-ons can resolve it without a hard dependency on the Envato add-on.

How Gating Works

1. An admin links Envato items to entities (helpcenter departments, forum categories, KB collections) via the Item Links page.
2. An admin enables the relevant “Require Purchase” toggle in Settings.
3. When a user tries to access a gated entity, the helpcenter/forum/KB add-on calls EnvatoPurchaseValidator::userHasPurchaseFor($userId, $linkableType, $linkableId).
4. The validator checks:
   • Are any Envato items linked to this entity? If not → unrestricted (returns true).
   • Does the user have a verified purchase for any of the linked items? If yes → access granted.
   • Otherwise → access denied. The user sees a “Purchase Required” page.

HelpCenter Integration

When envato_helpcenter_require_purchase is enabled:

• The helpcenter ticket creation form includes a purchase selector dropdown (envato::front.partials._purchase-field-helpcenter).
• Per-department gating: userHasPurchaseFor($userId, 'helpcenter_department', $departmentId).
• Users without a valid purchase for the selected department are shown the “Purchase Required” page.

Forum Integration

When envato_forum_require_purchase is enabled:

• The forum thread creation form includes a purchase selector dropdown (envato::front.partials._purchase-field-forum).
• Per-category gating: userHasPurchaseFor($userId, 'forum_category', $categoryId).
• Users without a valid purchase for the selected category are shown the “Purchase Required” page.

Knowledge Base Integration

When envato_kb_restrict_by_purchase is enabled:

• Per-collection gating: userHasPurchaseFor($userId, 'kb_collection', $collectionId).
• Non-buyers see the “Purchase Required” page with the list of required items (passed as $linkedItems to the theme view).
• The getAccessibleEntityIds() method returns only the collection IDs the user can access, useful for filtering KB listing pages.

Licenses Add-on Integration

When both the Envato and Licenses add-ons are active, and the Envato Provider is enabled in Licenses → Settings, the integration is bidirectional.

Envato → Licenses (Automatic Key Creation)

When a verified Envato purchase is created, a license key is automatically registered:

1. Checks if the Licenses add-on is active and the Envato Provider is enabled.
2. Checks if a license key with this purchase code already exists (skips if so).
3. Resolves a LicenseProduct by: SKU matching the Envato item_id → metadata.item_id match → slug match → creates a new one.
4. Maps the Envato license type: “Extended License” → extended, all others → standard.
5. Creates a license key with provider = 'envato', the purchase code as the key, and expires_at = null (Envato licenses are perpetual).

Envato Items → Licenses Products Sync

When the Envato Provider is enabled in the Licenses settings:

• Import: Importing Envato items on Admin → Envato → Items automatically creates corresponding products in the licenses products table. The Envato item_id is stored as the product sku.
• Delete: Deleting Envato items also removes the corresponding licenses product (matched by sku).

Licenses → Envato (Provider Verification)

When a purchase code is verified via the Licenses API (GET /api/licenses/verify) and is not found locally, the Envato Provider automatically verifies it against the Envato API. If valid, the key and a matching product are auto-created for future lookups.

If the Envato add-on is active, its API client is used for verification. Otherwise, the Licenses add-on makes direct HTTP calls to the Envato API.

Updating

Step 1: Replace Files

Replace the add-on directory with the new version.

Step 2: Run Migrations

Step 3: Clear Caches

Step 4: Verify

Visit Envato → Settings and click Test Connection to confirm the API token still works.

Troubleshooting

Test Connection fails: “Could not connect to Envato API”

Check that:

• The API token is correct and has not been revoked.
• The token has the required permissions (especially “View sales history”).
• Your server can reach api.envato.com (no firewall blocking outbound HTTPS).

Import finds no items

The import uses the author/sales endpoint, which only returns items you have sold. If you have a new item with zero sales, it won’t appear in the import. You can manually add items to the database or wait for the first sale.

Purchase code verification fails: “Invalid purchase code”

• Ensure the purchase code is a valid UUID (36 characters, including dashes).
• Verify the code belongs to one of your items (the author/sale endpoint only returns sales by the configured author).
• Check that envato_author_username is set correctly in settings.

User can’t connect Envato account

• Ensure the Envato OAuth driver is enabled in Admin → Settings → Social Auth.
• Verify the Client ID and Client Secret are set.
• The callback URL at Envato must match https://yoursite.com/auth/envato/callback exactly.

Purchases not syncing after OAuth connect

• The OAuth token may have expired. Try disconnecting and reconnecting.
• Check that the provider_token and provider_refresh_token columns exist on the users table (run php artisan migrate if the migration hasn’t run).
• Check server logs for Envato API errors during the sync process.

Purchase gating not working: users can access without a purchase

• Ensure the relevant toggle is enabled (envato_helpcenter_require_purchase, envato_forum_require_purchase, or envato_kb_restrict_by_purchase).
• Ensure at least one Envato item is linked to the entity. Entities with no linked items are always unrestricted.
• Check that the helpcenter/forum add-on is calling EnvatoPurchaseValidator::userHasPurchaseFor() in its access checks.

Buyer identity mismatch: purchase rejected despite valid code

The system tries to match the buyer to the authenticated user via three methods (in order):

1. Envato OAuth match (provider_id = buyer username): most reliable
2. Name match
3. Email prefix match

If none match, the purchase is rejected. Solution: have the user connect their Envato account via OAuth first, then add the purchase code. The OAuth match is definitive.

Auto-license creation not working

• Ensure the Licenses add-on is installed and active.
• Check that Addons\Licenses\Services\LicenseKeyService class exists.
• Check server logs for warnings during the auto-registration process.
• If a license key with the same purchase code already exists, auto-creation is skipped (by design).