Gumroad Integration Add-on Guide for Larapen

Connect your Larapen site to the Gumroad API. Import your Gumroad products as license products, record every sale through Gumroad’s Ping notifications, email each buyer a license key, and let customers verify their Gumroad keys on your site.

Use Cases

Software Sold on Gumroad

You sell scripts, plugins or themes on Gumroad and run your support site on Larapen.

• Import your Gumroad catalog. Each new product also becomes a license product in the Licenses add-on.
• Enable the Ping webhook. Every new sale is recorded and the buyer receives a license key by email, even for products that do not use Gumroad’s license-key feature.
• Your applications verify those keys through the Licenses add-on’s License API.

Support Reserved for Buyers

You want only Gumroad buyers to open tickets in a product’s helpdesk department.

• In the Licenses add-on, link the license product to the helpdesk department.
• Buyers add their key on My Gumroad Licenses, or get it attached automatically when they sign up with the email they used on Gumroad.
• Agents see the customer’s Gumroad licenses in the ticket sidebar.

Answering “Where Is My Key?”

A buyer writes in with only an email address or a Gumroad receipt.

• Open Gumroad → Verify License Key and search by license key, buyer email, order number or Gumroad sale ID.
• Resend the key from the Gumroad dashboard (Resend ping): the key email is sent again.

Requirements

• Larapen CMS v1.0.0 or later
• PHP 8.3+
• MySQL 8.0+
• The Licenses add-on, installed and active. This add-on depends on it (1.0.13 or later for this release, see Updating).
• A Gumroad account and an access token (see Creating an Access Token)
• Optional: the HelpDesk add-on, for the ticket sidebar and the support link on the front-end page
• Optional: a running queue worker, only if you enable background sync (see Settings)

Installation

Step 1: Upload the Add-on

In the admin panel, go to Admin → Extensions → Add-ons and click the Upload Add-on button. Select the add-on’s ZIP file: the system extracts it automatically and the add-on appears in the installed add-ons list.

Step 2: Activate the Add-on

Make sure the Licenses add-on is active first. Then find Gumroad Integration in the list and click Activate. Its migrations and permissions are set up automatically, and a Gumroad menu appears in the admin sidebar.

Step 3: Connect to Gumroad

Go to Admin → Gumroad → Settings, paste your access token and click Test Connection. On success, the message shows the name of your Gumroad account. See Configuration.

Step 4: Enable the Gumroad Marketplace in Licenses

In Admin → Licenses → Settings, enable the Gumroad marketplace (see Licenses Add-on Settings). If it stays disabled, importing Gumroad products does not create license products.

Step 5: Import Your Products

Go to Admin → Gumroad → Products and click Import from Gumroad (see Importing Products).

Step 6: Enable the Ping Webhook (Recommended)

In Gumroad → Settings → Ping Webhook, enable the ping and copy the Ping URL. On Gumroad, paste it in Settings → Advanced → Ping. See Ping Webhook.

Purchase Code (License Key)

Gumroad Integration is sold as a separate product, so it has its own purchase code (license key), distinct from the purchase code of the main application and from the one of every other add-on. You are asked for it when you activate Gumroad Integration in Admin panel → Add-ons.

Our products are sold on three platforms. The way you receive a purchase code depends on where you bought the product.

1. bedigit.com Store (in-site purchase)

• As soon as the order’s payment status becomes Paid, a license key is generated automatically for every licensed item in the order (one key per purchased unit: buying 3 units gives 3 distinct keys).
• It is emailed to the address used on the order, either in a dedicated license email or inside the order confirmation email. Check your inbox and your spam / junk folder.
• The key stays available in your account under My Account → My Licenses. Keys are masked in the list; open the license detail page to reveal and copy the full key, see the domains it is activated on, and deactivate a domain to free an activation slot.
• The matching invoice is under My Account → My Orders.

2. Gumroad

• A Gumroad purchase produces two separate emails: the Gumroad receipt (sent by Gumroad, giving access to the files) and a license key email (sent by bedigit.com) that contains your purchase code.
• The license key email is generated as soon as Gumroad notifies us of the sale, so it normally arrives within seconds of the payment. Here too, check your inbox and your spam / junk folder.
• When the Gumroad product uses Gumroad’s own license-key feature, the same key also appears in your Gumroad receipt and under Library → your purchase on gumroad.com.
• Use the same email address on bedigit.com as on Gumroad: your keys are then linked to your account automatically and listed under My Account → My Licenses, even if you register after the purchase. You can also add a Gumroad key manually from My Account → My Gumroad Licenses.

3. Envato Market (CodeCanyon)

• Envato purchase codes are issued and delivered by Envato Market, never emailed by us, so there is nothing to look for in your spam folder: you retrieve the code from your Envato account.
• Log in to your Envato / CodeCanyon account, open the Downloads page, find the item, and choose License certificate & purchase code from the Download dropdown. The code is written in that certificate.
• An Envato purchase code looks like 12345678-90ab-cdef-1234-567890abcdef (8-4-4-4-12 characters). It never changes, and renewing item support does not issue a new one.
• Official Envato article: Where Is My Purchase Code?

Configuration

All settings are managed in Admin → Gumroad → Settings (stored in the settings table, group gumroad). Saved values override the defaults of the add-on’s config/gumroad.php.

The ping log retention used by the Purge action (ping_log_retention_days, 90 days) is a config-only value in config/gumroad.php.

Creating an Access Token

1. Sign in to Gumroad and open Settings → Advanced.
2. In the Applications section, create an application (any name, e.g. “Larapen Support Site”, and your site URL as redirect URI).
3. Open the application and click Generate access token.
4. Copy the token and paste it into Admin → Gumroad → Settings → API Configuration, then click Test Connection.

Licenses Add-on Settings

The Gumroad marketplace is configured in Admin → Licenses → Settings. These settings belong to the Licenses add-on:

Admin: Dashboard

Gumroad → Dashboard (/admin/gumroad) shows:

• A warning with a link to Settings when no access token is set.
• Counters: products (total / active), customers, licenses (total / verified / refunded), revenue from sales that were not refunded, and the number of product → license product links.
• The most recent licenses (product, buyer email, date) and the top products.
• Shortcuts to Verify License Key and Settings.

Admin: Settings

The settings page (Gumroad → Settings) has these tabs:

API Configuration

• Access Token: hidden field with a show/hide button.
• Seller Name: for information only.
• Test Connection button: checks the token right away, including a token typed but not yet saved, and shows your Gumroad account name when it works.

Dependencies

Shows whether the Licenses add-on is active, with a warning when it is not.

Verification Options

• Require Email Match: the buyer email of a Gumroad sale must match the account email (enabled by default).

Ping Webhook

• Enable Ping switch.
• Ping URL: read-only field with a copy button. It shows the full URL of the gumroad.api.ping route, e.g. https://yoursite.com/api/gumroad/ping.
• A security note and a link to the ping log.
• License keys created from pings: create a key when Gumroad provides none, email the key to the buyer, blind-copy (the admin addresses are listed next to the field), ignore test sales, key format, license type and number of activations.

Licenses Sync

This tab is shown only when the Licenses add-on is active.

• Allow several license products per product: disabled by default, so a Gumroad product is linked to only one license product and the modal replaces it when you pick another.
• Run sync in the background: sends the Licenses → Gumroad sync to the queue. Enable it only if a queue worker is running (e.g. php artisan queue:work under supervisor). Without a worker, leave it disabled: the sync then runs during the request.

Admin: Products

Gumroad → Products lists your local copy of the Gumroad catalog.

Products List

• Search by name, Gumroad product ID, custom permalink or short permalink.
• Filters: published / unpublished, linked / not linked to a license product, with / without recorded licenses.
• Sort: name (default), sales, licenses, price (high to low / low to high), last synced.
• Columns include the thumbnail, name with the linked license products shown below it, price, sales count, license count and the Links count.
• Row actions: view, Linked license products (see below), delete. You can also select several rows and delete them.

Importing Products

Click Import from Gumroad. The import runs in a single AJAX request (POST /admin/gumroad/products/import):

1. Gumroad returns products 10 per page, newest first. The server requests every page until the last one, so products of any age are imported. It stops at 100 pages (1,000 products) or if Gumroad returns the same page twice.
2. Existing products (matched by Gumroad product ID) are updated. New products are created.
3. For each new product, when the Licenses add-on is active and its Gumroad marketplace is enabled, a license product is created (or the license product already listed under the same Gumroad identifiers is reused) and the Gumroad product is listed under it.
4. Short permalinks are then read from your public Gumroad storefront (see Gumroad Identifiers). If this step fails, the import still succeeds and a warning is written to the log.
5. The result shows how many products were imported, updated and processed in total.

Gumroad Identifiers

A Gumroad product has three identifiers:

All three can be searched on the products list, appear on the product page and in the links modal, and are copied into the license product’s Gumroad listing. This lets the License API identify the product from any of them.

The gumroad:permalinks command

# List every imported product: ID, short permalink, custom permalink, name
php artisan gumroad:permalinks

# Find the products matching one or more identifiers (ID, short or custom permalink)
php artisan gumroad:permalinks abcde my-plugin-pro

# Read the short permalinks from the storefront first
php artisan gumroad:permalinks --sync
php artisan gumroad:permalinks --sync --storefront=https://seller.gumroad.com

# JSON output
php artisan gumroad:permalinks --json

The command fails with a non-zero exit code if an identifier matches no imported product. It helps you fill in the Gumroad ID in an add-on or theme manifest (marketplace_item_ids.gumroad).

Product Detail & Sales

The product page (Gumroad → Products → {product}) shows:

• Product info: identifiers, price, currency, sales count, published state, last sync, and the linked license products.
• Sync: fetches the product again from GET /v2/products/{id} and updates its fields.
• Import Sales (permission gumroad.customers.manage): requests the product’s sales page by page (GET /v2/sales?product_id=…&page_key=…, one page per AJAX call) until the last page. Only sales that have a license_key are imported. Sales already on file are skipped. Buyers are matched to site accounts by email. Sales that were not refunded or disputed are also added to the Licenses add-on.
• Add License Key: add a known key manually. The key is checked with Gumroad for this product only, and the buyer email is not compared with any account. The buyer is still matched to a site account by email when one exists.
• Licenses table: every recorded license for the product, with buyer, linked account, key, amount and refund/dispute state.

Linking Gumroad Products to License Products

Click the Linked license products action on a products row (or on the product page) to open a modal:

• It shows the Gumroad product ID, short permalink and custom permalink.
• It uses the shared License Products picker (marketplace filter, keyword search, slug / SKU / version on each row).
• A Create license product button creates the missing license product from the Gumroad product and selects it (available when you have the licenses.products.create or licenses.products.edit permission).
• When you save, the selected license products replace the current links. Without Allow several license products per product, only one can be selected.

When a sale is recorded, its key is assigned to the license product that the Gumroad product is listed under. If the Gumroad product has no listing, the add-on tries these in order: a license product whose slug or slug alias matches the product name, then the first active license product. If neither exists, it creates a license product and immediately lists the Gumroad product under it. To avoid keys landing on the wrong product, link each Gumroad product explicitly.

Admin: Customers

Gumroad → Customers groups recorded licenses by buyer email. Gumroad has no buyer username, so the email identifies the customer.

• Columns: buyer email, linked site account, number of licenses and products, total spent (refunded sales excluded), refunded count, last purchase.
• Search by buyer email or by the name/email of the linked account.
• Filters: buyers of a given product (their totals still include all their purchases), linked / not linked to an account, with / without a refund.
• Sort: latest (default), oldest, licenses, amount spent, email.

Customer Detail

The customer page URL is /admin/gumroad/customers/show?email=…. The email is passed in the query string because some web application firewalls block URL paths that end in .com. The page shows:

• The buyer email and the linked site account (with a link to the user).
• Stats: licenses, products, total spent, verified count, refunded count.
• Every license of the buyer, newest sale first, with a link to each product.

Admin: Ping Logs

Gumroad → Ping Logs records every ping received, including rejected ones, and every re-run started by an admin.

• Stat cards: total, created, duplicates, failed (failed + rejected), last ping received.
• Filter by status, and search by sale ID, buyer email, license key, product name or Gumroad product ID.
• Each row shows the source (ping or manual re-run), the sale, product and buyer, and the license key (linked to the Licenses key when there is one) with a badge saying whether Gumroad issued it or the site created it. It also shows whether the key email was sent and to which address, and the message. The details show the raw request and the sale data returned by the API.
• Reprocess (only for logs with a sale ID): runs the sale again. The sale is fetched again from the Gumroad API, as for a live ping.
• Delete a log, or Purge logs older than 7, 30, 60, 90, 180 or 365 days.

Admin: Verify License Key

Gumroad → Verify License Key looks up a purchase from any of these:

• a license key: a key issued by Gumroad, or a key created by the site in any Licenses add-on format,
• the buyer email,
• the order number from the Gumroad receipt, or the Gumroad sale ID.

Local records are searched first. If several sales match (e.g. a repeat buyer’s email), up to 25 are listed and you choose one. For a single local match, the sale is checked again with the Gumroad API (GET /v2/sales/{id}), and any changes (e.g. a new refund) are saved to the record. If nothing is found locally and the value is a license key, it is checked with Gumroad. You can pick a product to search only that product. Tick Skip format check to send a value with an unrecognized format to Gumroad as a key.

The same lookup opens in a modal from the ticket sidebar (see HelpDesk Sidebar).

Ping Webhook

Gumroad can notify your site of every sale (“Ping”). The endpoint is:

{
  "success": true,
  "status": "created",
  "created": true
}

License Key Email

For products without Gumroad’s license-key feature, the Gumroad receipt contains no key, so this email is the buyer’s only copy.

• Sent on every processed ping, including replays. To send a lost key again, use Resend ping on the sale in the Gumroad dashboard. A second email for the same key is not sent within 60 seconds, which prevents duplicates when a ping arrives twice.
• Not sent for refunded or disputed sales, or for sales without a buyer email.
• When the buyer has an account, the email is sent to that account, so their language and notification preferences apply. Otherwise it is sent directly to the buyer email.
• This is the Gumroad License Key notification type (gumroad_license_key_issued, email only). It can be turned off in the notification settings. The ping log records only emails that were actually sent.
• The Blind-copy setting sends a copy to one address, or to every admin account if no address is set.

My Gumroad Licenses

Signed-in users have a My Gumroad Licenses page in their account menu, at /{locale}/gumroad/licenses. It is available in all six themes (default, creative, elegant, minimalist, olive, studio).

Versions without {locale} are also registered (gumroad.licenses, gumroad.licenses.store, …).

Page Layout

• Add License Key form: the key from the Gumroad receipt or from the license key email.
• Verified Licenses: searchable by product name, buyer email or key, 5 per page. Each entry shows the product, the key with a copy button, the sale and verification dates, a Refunded badge when relevant, and a Remove button.
• Register button (when the Licenses add-on is active and the key is not yet there): creates the license key in the Licenses add-on so it unlocks the support and other features it gives access to. If the key already exists, the user is added as its owner.
• Sidebar: help tips (where to find the key, use the same email as on Gumroad, several keys allowed) and, when the HelpDesk add-on is active, a Need support? card.

How Customers Verify a Gumroad Key

When a user submits a key (on the page, or with POST /api/gumroad/validate-license), the key is converted to upper case and checked as follows:

1. Format: the key must look like a Gumroad key (XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX) or a key in one of the Licenses add-on formats (these keys come from pings).
2. Already recorded? (case-insensitive)
   • Already on this account: “already yours”.
   • Belongs to another account: already_used.
   • Recorded without an account (typically a ping sale): the user gets it if the buyer email matches (when required) and the sale was not refunded or disputed.
3. Product-scoped check with Gumroad: Gumroad checks a key only together with a product ID (POST /v2/licenses/verify, always with increment_uses_count=false). The add-on tries the key against each active imported product until one matches. If no product is imported, the result is product_mismatch.
4. Refunded or disputed sales are refused (refunded).
5. Buyer identity: if gumroad_require_email_match is on, the sale’s email must match the account email (case-insensitive), otherwise email_mismatch.
6. The license is recorded (verification_method = api) and the key is created in the Licenses add-on.

Validation Statuses

Subscriptions

For a subscription product, the license key expires on the earliest of the subscription’s end, cancellation and failure dates (expires_at). A one-time purchase never expires.

Buyers Without an Account

A ping or a sales import can record a sale before the buyer has an account on your site. Those licenses are stored without an owner. They are assigned to the account that has the buyer email (case-insensitive), together with the matching Licenses keys, when:

• a user account is created with that email, or
• an account’s email is verified (this also covers a user who changes their email to the one they used on Gumroad).

Licenses Add-on Integration

Gumroad → Licenses

• Every sale added through the front-end, the admin form, a sales import or a ping is also created as a Licenses key (marketplace gumroad, marketplace reference = the key, or the sale ID for keys created by the site). Details such as product, email, order number, sale ID, amount and currency are stored with it. Keys that already exist are left unchanged.
• Product imports create license products and their Gumroad listings (when the Gumroad marketplace is enabled).
• In the Licenses add-on, Licenses → Products → Import from Gumroad creates license products from the Gumroad products already imported here.

Licenses → Gumroad

• If the License API receives a key it does not know and the Gumroad marketplace is enabled, it checks the key with Gumroad against this add-on’s active products. If there are none, it uses licenses_gumroad_product_ids. Valid keys are created locally. Valid results are cached for 1 hour, because Gumroad sales can be refunded.
• Each time the Licenses add-on verifies a Gumroad key, the SyncGumroadLicenseFromLicense listener copies the result here (verification_method = licenses). Your Customers and Products pages therefore also include keys that were verified only through the License API.

Access Control

Helpdesk departments, KB collections and forum categories are linked to license products in the Licenses add-on (licenses_entity_links). A Gumroad key unlocks them once it is a Licenses key of a linked product. That is why each Gumroad product should be linked to the correct license product.

What the License API accepts as the product

A client app sends the product parameter next to the license key on GET /api/licenses/verify. The Licenses add-on accepts several identifiers of the same product, and all three Gumroad identifiers are among them, through the product’s Gumroad listing, not through the SKU:

The full order the server tries, and the other marketplaces’ identifiers, are documented in the Licenses add-on documentation (How the API Recognizes a Product).

HelpDesk Ticket Sidebar

When the HelpDesk add-on is active and a ticket belongs to a registered user, the admin ticket page shows a Gumroad card in the sidebar with that user’s verified Gumroad licenses:

• Product thumbnail and name (with a link to Gumroad), with Refunded, Disputed and Subscription ended badges when relevant.
• Sale date and license key. Admins see the full key with a copy button. Other agents see only its last 8 characters.
• A Verify button (permission gumroad.products.view) that opens the lookup in a modal.
• A View customer button that opens the customer page.

HelpDesk also counts verified Gumroad sales in the customer’s total spend shown by its badges.

Updating

There are two ways to update this add-on: via the admin panel (recommended) or manually replacing files.

Method 1: Admin Panel Upload (Recommended)

1. Download the latest .zip file of this add-on.
2. Go to Admin panel → Add-ons and click the Upload button.
3. Select or drag the .zip file into the upload area.
4. A confirmation prompt will show the current and new version numbers. Click Replace to proceed.
5. Go to Admin panel → System Update (/admin/update) to apply any pending updates.

Method 2: Manual File Replacement

1. Back up your database.
2. Replace the extensions/addons/gumroad directory with the new version.
3. Open Admin panel → System Update (/admin/update) to apply the pending updates. Files that are no longer used are removed by the update.
4. Visit Gumroad → Settings and click Test Connection.

Uninstallation

Switching an add-on off without losing anything is a deactivation: go to Admin panel → Add-ons, find Gumroad Integration and click Deactivate.

• Its routes, views, admin menu entries and permissions stop being registered, and its front-end pages stop answering.
• Its database tables and all the data they hold are kept, and its files stay under extensions/addons/gumroad/. Nothing is deleted.
• The purchase code recorded at activation is kept too, so activating the add-on again does not ask for it.
• Deactivation is refused while another active add-on depends on this one: deactivate that add-on first.

Click Activate on the same card to switch it back on. Pending migrations are re-run, assets are republished, and the add-on picks up exactly where it left off.

Removing

Removing is permanent and destroys the add-on's data. The Remove button only appears on a deactivated add-on, so removal is always two steps:

1. Deactivate Gumroad Integration (see Uninstallation).
2. Click Remove on its card and confirm the prompt.

The admin panel then, in one pass:

• runs the add-on's uninstall hook, if it ships one, while its code is still on disk;
• revokes the permissions declared in its addon.json;
• rolls back its migrations (this drops its database tables and every row they hold) and purges its entries from the migrations table, so a later reinstall migrates from scratch;
• deletes its published assets: public/addons/gumroad/, public/vendor/gumroad/ and storage/app/public/addons/gumroad/;
• deletes the add-on directory extensions/addons/gumroad/;
• deletes its row in the addons table (the recorded purchase code goes with it) and clears the application cache.

Removal is refused, with an explanatory message and before anything is destroyed, when the add-on is still active, when another active add-on depends on it, or when the web server (PHP) user cannot delete extensions/addons/gumroad/. In that last case, give that user write permission on the directory and on its parent, then try again.

Deleting the folder over FTP or SSH is not equivalent: the add-on's tables, its entries in the migrations table and its addons row are all left behind, and its card stays in the list. Use Remove in the admin panel instead.

Troubleshooting

Test Connection fails

• Check that the token was generated from a Gumroad application and has not been revoked.
• Your server must be able to reach api.gumroad.com over HTTPS.

Only some products are imported

Since the pagination fix, every page is requested. If products are still missing, check the log for a “repeated cursor” or “page cap” warning (the limit is 1,000 products).

Import creates no license products

• The Licenses add-on must be active and its Gumroad marketplace enabled (licenses_gumroad_marketplace_enabled).
• License products are created only for new Gumroad products. For products imported earlier, use the Create license product button in the links modal, or Licenses → Products → Import from Gumroad.

Short permalinks are empty

They are read from your public storefront, which Gumroad does not provide through its API. Run php artisan gumroad:permalinks --sync. If your products have no storefront URL, add --storefront=https://<seller>.gumroad.com.

“Invalid license key” for a real key

• The product must be imported and active, because Gumroad checks a key only together with its product.
• Keys created by the site (UUID etc.) are unknown to Gumroad. They are verified from the local records, so the sale must have been recorded by a ping or an import.

“Email mismatch”

The account email differs from the email used on Gumroad. Ask the buyer to use the same email, or turn off Require Email Match if the key alone is enough proof for you.

Pings are not arriving, or are rejected

• Check Ping Logs. If nothing is logged, the Ping URL on Gumroad is wrong or a firewall blocks the request.
• rejected with HTTP 403: the ping is disabled in Settings.
• failed with HTTP 404: the sale could not be fetched. Check the access token, which must belong to the same Gumroad account as the sale.
• rejected with a “no license key” message: enable Generate a license key, or enable license keys on the product at Gumroad.

The buyer did not receive the key email

• Check the ping log row: it shows whether the email was sent, and to which address.
• Ask the buyer to check the spam / junk folder, then use Resend ping on the sale in Gumroad.
• Check that Mail the license key is enabled, that the Gumroad License Key notification type is not turned off, and that mail is configured.

A key was assigned to the wrong license product

The Gumroad product was not listed under any license product, so the fallback rules were used (slug, then first active product). Link it with the Linked license products modal. Sales recorded afterwards are assigned correctly.

gumroad_product_links is still in the database after updating

Gumroad 1.0.3 was applied before Licenses 1.0.13. Update the Licenses add-on, then run the Gumroad update again from System Update.