Chapter 14. Troubleshooting

Follow the purchase from Paddle to your site:

The customer bought a product or price your site doesn't know, usually one created in Paddle's dashboard and never opened in PaddleSubs. Open the Products page so PaddleSubs picks it up, give the product a category and groups, then click Try again beside the purchase on the Needs Attention page. Replaying the event from Paddle doesn't help, because PaddleSubs skips events it has already processed.

If the price is custom, such as one Paddle made for an invoice or a transaction created in its dashboard with an amount typed in, the Products page doesn't pick it up, since Paddle leaves custom prices out of its lists. Click Set Up Price beside the purchase instead: it adds the price, and its product if needed, and tries the purchase again.

The page shows what your site knows at the moment it opens. Access appears once the webhooks have been processed, usually within a minute if Joomla's scheduler runs from CRON, and at the next visit to your site if it doesn't. Set up CRON as in the section called “Run the Scheduler From Your Server”. Also check that the customer is logged in as the account the purchase went to: the page only shows a logged-in customer's own purchase.

Prices are filled in by Paddle in the visitor's browser, so the same causes as above apply: the client-side token, blocked scripts, or a second Paddle.js. A tag that shows nothing at all names a product or price that doesn't exist, or a product with no price of that kind: {psprice} needs a one-time price, {pspricerecurring} a recurring one.

Turn on Allow buyers to add a discount code in Paddle → Checkout → Checkout configuration; until it is on, Paddle hides the field whatever your site asks for. Also check that Discount codes at checkout is on in PaddleSubs' options. A code is only accepted if its discount is active, has that code and is enabled for checkout in Paddle.

PaddleSubs connects a purchase to the account with the checkout's email address. If the customer bought while logged out, with another address, a new account was created for that address. Ask customers to log in first; the product page then fills in their account's address. To fix a purchase that went to the wrong account, see the section called “How Paddle Customers Become Joomla Users”.

Accounts PaddleSubs creates have a random password. The customer was signed in on the Purchase Complete page right after paying, and the welcome email links to a page to choose a password, once and within a week. After that they use Forgot your password?. Until they choose a password, the session they were signed in to after paying lasts a day and can't open Joomla's profile pages; see the section called “Purchase Complete”. These accounts are active whatever New User Account Activation says. If the account is blocked, someone blocked it in Users → Manage.

PaddleSubs has an API key for the environment in use but no webhook secret key, so your site refuses every webhook Paddle sends and purchases give no access. In Paddle, open Events → Notifications, click … beside your destination, then Edit destination, and copy the secret key. Paste it into the options as described in Procedure 2.5, “Enter the secret key in PaddleSubs”. The keys are kept for each environment: after switching Environment, enter that environment's secret key too. Webhooks refused meanwhile are retried by Paddle for a few days; replay older ones from the destination's log.

403 Forbidden means the request didn't come from an IP address in Webhook addresses (Sandbox webhook addresses in the sandbox) on the Webhooks tab of the options. If your site is behind a proxy or a service such as Cloudflare, PaddleSubs sees the proxy's address rather than Paddle's: enter the proxy's addresses in Trusted proxies. If Paddle has announced new addresses, add them, or empty the field to use the ones PaddleSubs knows.

500 means the webhook couldn't be checked against the destination's secret key, or something went wrong saving it. The log says which: Webhook secret not configured (enter it, see Procedure 2.5, “Enter the secret key in PaddleSubs”) or Webhook not verified (the key doesn't match the destination's: copy it again, and check that Environment matches the Paddle account that sent it).

Paddle delivers a refused webhook again later, so once the cause is fixed the webhooks it refused still arrive; replay them from the destination's log if you don't want to wait.

A plugin or scheduled task PaddleSubs needs is disabled or missing. The message lists each one, with what doesn't happen until it is fixed and a link to fix it:

The tasks checked are PaddleSubs - Process webhooks, PaddleSubs - Access subscription lifecycle and PaddleSubs - Expiry reminders. The message goes away on the next page once everything is in place. It doesn't tell whether the tasks actually run on time; for that, see the section called “Run the Scheduler From Your Server”.

The site doesn't get PaddleSubs updates or support until it is activated; everything else works. Enter the Download Key and click Activate this site, as in the section called “Updates and Your License”, which also lists why an activation can be refused. If an update fails to download although the site is activated, check that the Installer - PaddleSubs plugin is enabled.

They are waiting in the queue for the PaddleSubs - Process webhooks task. Check that the Task - PaddleSubs Webhooks Processor plugin is enabled, that the task exists and is enabled, and when it last ran. If it fails, its reason is in the PaddleSubs log. The task leaves the queue alone while PaddleSubs is offline (Offline Enabled on, or no API key for the current environment), and says so in the log.

Groups are only taken away if they are in Remove From User Groups (or a level's Remove groups). Add the group there, then run Resync user groups with Also remove groups no purchase grants on. A group is also kept while another of the customer's active Access Subscriptions grants it, which is intended.

The group may have been added to the product or level after they bought, or the access was imported. Run PaddleSubs - Resync user groups(task). If the Access Subscription is listed but not published, the lifecycle task hasn't started it yet: check that it runs.

The PaddleSubs - Access subscription lifecycle task does both. Check that it exists, runs often, and succeeds. It needs Paddle for purchases made through Paddle: if Paddle can't be reached, it fails for them, and only imported access is ended.

The lifecycle task publishes only Pending Access Subscriptions. If you published it while its window hadn't started, it became pending and was published when its window opened: unpublish it again. To end access at a certain time, change Ends instead; see the section called “Extend, Shorten or End Someone's Access”.

Tags that show as typed mean the Content - PaddleSubs Restricted plugin is disabled. If the content shows to the wrong people, check the product slugs in the tag, and remember that ! means “doesn't have”. Page caching can also show one visitor's page to another: keep pages with restricted content out of Joomla's page cache and any other cache.

Check that Joomla can send email at all, with Send Test Mail in System → Global Configuration → Server, and that Send Mail is on. Failed sends are logged in the PaddleSubs log. Expiry reminders are only sent for one-time purchases, and only by the PaddleSubs - Expiry reminders task.

Links in emails are built from the Site Address option, or from $live_site in configuration.php when that is set. Check both: the option is filled in from the address an administrator first opened a PaddleSubs page with, which may be a development or internal address.

While neither is set, an email sent from CRON uses Joomla's placeholder, joomla.invalid, and one sent during a visit is not sent at all: the task's log says the site's address is not known yet, and the email is tried again at a later run. Open any PaddleSubs page in the administrator to fill in the option.

The API answers with a reason. the section called “Refusal Codes” lists each, with what the customer can do. Most often the customer has used all their seats (all_seats_bound) and should release a site on their licenses page, or the site is bound to another customer's license (identifier_bound_elsewhere).

The token's user doesn't have the permission the request needs, or isn't allowed to use API tokens. See the section called “Tokens, Service Users and Permissions”.

PaddleSubs' own permissions (Grant access, View sales, Charge customers, Manage customers, Manage licenses, Assign user groups, Import from another system) are held only by Super Users until you grant them to a group. Set the one the page needs in Options, Permissions tab; see the section called “Control Who Can Do What”. For a product, also check its category's Permissions tab.

Turn off Offline Enabled, and enter the API key for the current environment, in the options.

The server ran out of time or memory. Nothing is lost: find the import under Previous imports and click Continue. A dump too large to upload can be copied to the server instead; see the section called “Step 1: Choose Where the Data Comes From”.

Usually the tax category isn't approved in your Paddle account. Choose Standard digital goods, or have Paddle approve the category first.

PaddleSubs shows earnings (after Paddle's fee, tax and refunds) in your payout currency, only for transactions that created access on your site, and dated when Paddle billed them. Paddle's own dashboard can show gross sales, other dates, or every transaction. Figures are also kept for up to six hours; Sync from Paddle refreshes them.