Troubleshooting

Find the cause and the fix for common TierMint and TierMint Pro problems, such as an unavailable checkout, failing webhooks and missing updates.

Checkout and payments

Checkout says it is not available

The checkout shows "Checkout is not available right now. Please try again later." when no payment gateway is ready. For Stripe, the current Stripe mode needs both a publishable key and a secret key. This happens when the mode is Test but only the live keys are filled in, or the other way round. Enter the keys for the current mode under TierMint → Settings → Payments, or switch the mode. See Connect your Stripe account.

A buyer paid, but the order is still pending

TierMint completes an order only when Stripe's webhook confirms the payment, so the webhook did not arrive or failed its signature check. Check that the endpoint URL ends in /wp-json/tiermint/v1/webhooks/stripe, that it sends payment_intent.succeeded, and that the signing secret in TierMint belongs to that endpoint and to the current Stripe mode. The endpoint's event log in your Stripe Dashboard shows each delivery and your site's reply. A site on your own computer cannot receive webhooks from Stripe, so forward them with the Stripe CLI, and use the whsec_ signing secret that the CLI prints. See Set up the webhook and Test payments.

Stripe webhooks fail with an invalid signature

TierMint replies with status 400 and "Webhook signature verification failed." Usually the signing secret belongs to another endpoint, or to the other mode: a live event fails the check while the mode is Test. Paste the signing secret of the endpoint for the current mode. Also check the server clock, because TierMint refuses a signature whose timestamp is more than five minutes from the server time. See Stripe payments.

Saved secrets are empty after a move to a new host

TierMint encrypts the Stripe secret keys and signing secrets with a key built from SECURE_AUTH_KEY in wp-config.php. When that constant changes, for example after a move to a new host, TierMint can no longer read them. The Stripe secret key and signing secret fields then show as empty, and checkout stops until you enter the secrets again. With TierMint Pro, the PayPal client secret is encrypted the same way, so enter it again too, and the License panel shows License key unreadable: enter your license key again. The signing secrets of your outbound webhook endpoints become unreadable as well, so delete each endpoint and create it again. Pro also creates a new license signing key, so a plugin that pinned the old public key gets unknown_key for new answers until it pins the new one. Without SECURE_AUTH_KEY, TierMint cannot save a secret at all. See When SECURE_AUTH_KEY changes, What each status means and Signed license answers.

PayPal does not show at checkout

The current PayPal Mode has no client ID or no client secret. Check both on the PayPal tab under TierMint → Settings → Payments, and check that Mode matches the credentials: sandbox credentials work only in sandbox mode. If saving the secret fails with "The PayPal secret could not be encrypted. Confirm SECURE_AUTH_KEY is set on this site.", the constant is missing from wp-config.php. See Connect PayPal.

A PayPal order stays pending or misses a refund

PayPal reports payments and refunds to TierMint through a webhook. A one-time order completes when the buyer returns from PayPal. If they closed the window first, nothing is captured, so the order stays pending. Only a capture that PayPal reports as pending waits for the webhook. The first payment of a PayPal subscription always waits for it. Refunds made in PayPal reach TierMint for one-time orders only. Check that the webhook URL is https://yourstore.example/wp-json/tiermint/v1/webhooks/paypal with your own domain, that it has the refund events, and that the webhook ID in TierMint matches the one PayPal shows. See Add the PayPal webhook.

Checkout asks for a country or an address you did not turn on

TierMint Pro settings can require these fields. With tax calculation set up, the country list and the tax ID field always show and the country is required. With the invoice option Show the buyer's billing address on invoices on, which is the default, the checkout requires an address. Turn that option off under TierMint → Settings → Invoices to let Collect a billing address decide again. See Billing country and Billing address.

A discount code is rejected

The message under the Discount code box gives the reason. "That is not a valid discount code." covers a code that does not exist, is switched off, has not started yet or belongs to an automatic discount. Check the discount's status and dates under TierMint → Discounts. Starts at and Expires at are UTC times, not your local time. See Messages buyers see when a code is rejected.

A subscription cart is refused at checkout

A subscription must be bought on its own, at quantity one and with no discount code. A cart that breaks a rule shows a message such as "A subscription must be purchased on its own. Please check out the subscription separately." The buyer checks out the subscription and any other product separately. See What happens at checkout.

A refund shows an error

"The payment gateway did not confirm this refund, so the money may or may not have moved." means TierMint does not know the outcome. Confirm refund stays disabled to stop a double refund, and TierMint records the refund when Stripe's webhook reports it, so check the order again in a few minutes. "Nothing was charged or refunded: the payment gateway is not configured." means the current Stripe mode has no secret key. A refund of a live order also fails while Stripe mode is Test, with the "did not confirm" message, and no webhook follows because nothing moved. Switch the mode to Live and refund again. See When a refund shows an error.

Storefront

Buy now adds nothing to the cart

Look for a message on the page, or for tiermint_cart_error in the address. The value invalid shows "That item could not be added to the cart." and failed shows "Something went wrong updating your cart. Please try again." With no message at all, the form's security token had probably expired, for example on a page served from a cache. Reload the page and try again. See How the cart forms work.

A block or shortcode shows nothing on the live page

Most often the product cannot be bought: it is not published, it has no active tier, or the chosen tier is archived or belongs to another product. TierMint Pro archives its recurring tiers while it is deactivated, so they show nothing either. See If you deactivate Pro. A Pricing Table shows nothing until you enter product ids in Products, and the Purchase Confirmation block stays empty until a buyer returns from payment. In the editor, these blocks show a sample instead: see Sample previews. See also Shortcodes.

There is no Proceed to checkout button

The cart is empty, or no checkout page is set. Pick a page in Checkout page under TierMint → Settings → General, or set checkout_page on the cart summary. See Set the checkout page.

The receipt does not show after payment

The receipt needs a Purchase Confirmation block on the page the buyer returns to, and ?tiermint_order= in the address. If you built your own checkout page, add the Purchase Confirmation block or [tiermint_purchase_confirmation] above the checkout. An order that belongs to a WordPress account shows only to that account, so the buyer may need to sign in first. See The purchase receipt.

Storefront pages or the links to them are missing

When a page setting points at a draft or a trashed page, TierMint hides its links to that page. The cart summary is an exception: it still links a draft or trashed checkout page. Publish the page, or pick another one under TierMint → Settings → General. To get a fresh copy of a page TierMint created, trash or delete the old page, then deactivate and activate TierMint. Clearing the setting alone selects the same page again. If you open registration after setup, TierMint does not create the Register page: add the Registration Form block to a page and pick it in Registration page (see The registration page). See How TierMint fills the page settings.

A child page of the product page shows not found

TierMint reads every path directly under the product details page as a product address. With the product page at /product/, a page at /product/faq/ is looked up as a product, and a slug with no published product returns "not found". Give that page another parent. See Child pages under the product page.

The product page has an empty heading or breadcrumb

The default Product page heading option hides the theme's page title on the product page. Breadcrumbs and page lists there then get an empty title, and a few older themes print an empty heading. If your theme prints the page title, pick Use the theme page title for the product name under TierMint → Settings → General. See Choose how the product page shows its heading.

Your CSS changes have no effect

A color set under TierMint → Settings → Appearance prints in a :root:root block, which wins over a plain :root rule. Clear the color there, or give your rule more weight, such as :root:root:root. For a rule on a component class, add the .tiermint-component scope that TierMint uses. See How your CSS wins over TierMint's.

Cart forms do nothing after a template override

A cart form with a missing or wrong nonce does nothing and shows no error. Check that your template copy keeps the hidden tiermint_cart_action, product_id and price_id fields, the quantity field and the nonce printed by wp_nonce_field(). See Override a component template.

TierMint widgets or products are missing in Elementor

Check that Elementor is active and that Elementor widgets is on under TierMint → Settings → Integrations. A widget's product select lists up to 100 published products. For a larger catalog, use the block editor's product picker or the shortcode. See Turn the Elementor integration on or off and Set up a widget.

Accounts, sign-in and staff access

You cannot reach the WordPress login screen

With Use the sign-in page instead of wp-login on, open wp-login.php?tiermint_wp_login=1. It always shows the real WordPress login screen. If your sign-in page is deleted, unpublished or trashed, the redirect stops and wp-login.php works as normal again. See You cannot lock yourself out.

The password reset page is broken

While your reset page is published, the password emails TierMint sends link to it. WordPress's own password emails link to it too while Use the sign-in page instead of wp-login is on. To reach the WordPress reset form instead, copy the key and login values from the emailed link and open wp-login.php with them, plus action=rp and tiermint_wp_login=1. You can also set a password with wp user update in WP-CLI. Unset or unpublish the reset page, and WordPress builds its own links again. See Which password emails link to your reset page.

The sign-in form has no Create an account link

WordPress registration is closed and the Login Form block has no Registration URL, or the block has Show registration link turned off. Turn on Anyone can register under WordPress's Settings → General, or set Registration URL on the block. See When the Create an account link shows.

A purchase is missing from a customer's account

The order was most likely placed as a guest with another email address. TierMint links a guest's customer record to a WordPress account only when the user registers or signs in with the same email. Compare the order's email with the account email. A signed-in user with no linked customer record sees the account page with empty tabs. See How TierMint matches a buyer to a record.

A staff member cannot see a TierMint screen

Each screen needs its capability. Settings needs manage_tiermint_settings, Reports needs view_tiermint_reports, and the day-to-day store screens need manage_tiermint. A direct link to a screen the user cannot open shows "Access denied". See Who can use each screen.

Licenses and activations

A license is refused on activation

The activate route answers with an error code that names the reason:

Code	Cause	Fix
tiermint_activation_limit_reached	Every slot on the license is in use.	Deactivate a site the customer no longer uses, then activate again.
tiermint_license_expired	The license has passed its expiry date.	The customer buys a new license and uses its key. With a TierMint Pro subscription, the next paid renewal extends the same license.
tiermint_license_disabled	You disabled the license, or a full refund did.	Enable it under TierMint → Licenses if it should work.
tiermint_key_mismatch	The key belongs to another product than the product_slug sent.	Use the key for this product, or send the product's catalog slug.
tiermint_invalid_key	No license has this key.	Check the key the customer entered.

The customer can deactivate a site on their account page, and you can do it from the license screen. See Errors and Deactivate a site for a customer.

A customer cannot activate a new site from their account

The Activate a new site form shows only when the license is active, has not expired and has a free slot. Look at the card's status badge and its Active sites count. At "3 / 3", the customer deactivates a site first. The form also hides when the Licenses block has Show site activations turned off. Activating needs JavaScript in the browser. See Activate a site.

The Licenses tab is empty after a purchase

TierMint creates license keys only for products with Licensed product turned on. Also check that the account page's dashboard does not have Show licenses turned off. See Customer dashboard.

A download link stopped working

Links on the account page work for six hours after the page loads, and links in an email for 72 hours after it was sent. A refund or a disabled license also stops a link. Reload the account page for fresh links. See The Downloads tab.

License requests fail with status 429

The licensing routes allow 60 requests an hour per license key and 300 an hour per IP address. A client that validates on every page load reaches them, so cache each answer for about 12 hours. TierMint reads only REMOTE_ADDR. Behind a proxy or CDN, unless the web server sets it to the visitor's address, every request shares one window. Developers can change the limits with the tiermint_rest_rate_limits filter. See Rate limits.

Updates and releases

A customer does not see a new release

First check that the release is Published, not still a draft. The update client keeps each answer for 12 hours, and WordPress checks for updates on its own schedule, so a site picks up the release when its cache runs out. Calling flush_cache() on the client makes it ask your store on the next check. A client with an empty license key gets no update at all. With TierMint Pro, also check the rollout shown on the release row. See Caching and the grace period.

A beta or release candidate build does not reach a site

TierMint Pro offers a beta or release candidate draft to the sites on its channel. Check these in order:

1. The draft's row shows Offered. If it does not, click Offer to beta sites, or Offer to release candidate sites on the release candidate channel. A new version or package on an offered draft stops the offer until you offer it again.
2. The draft's version is newer than the latest published release and than any draft already offered on the same channel. TierMint Pro refuses an offer that is not, with a message that names the versions.
3. The rollout on the row is high enough. A site outside the rollout does not get the build.
4. The site's update client asks for the channel, with its channel option set to beta or rc. See Let your users choose a channel.
5. The client's 12-hour cache has run out. Call flush_cache() on the client to make it ask your store on the next check.
6. TierMint Pro is active on the store. Without it, the store ignores the channel and serves published releases only.

See Offer a beta or release candidate build.

WordPress says automatic update is unavailable

The site's license is expired, disabled or unknown, so your store sends the new version and changelog without a download link. WordPress lists the update with "Automatic update is unavailable for this plugin." and installs nothing. Once the site has a valid key, its next check brings the link. See When the license is not valid.

An update fails to download

At update time the client asks your store for a fresh download link, and that request or the download failed. WordPress shows "Could not refresh the download link for this update. Please try updating again." or "The update package could not be downloaded. Please try updating again." Try the update again. Signed package downloads lists the reasons your store refuses a download.

A release upload is refused

A release needs a version and a package zip. When the product has an update slug, the zip must hold a folder named after the slug with a PHP file that has a Plugin Name: header in its first 8 KB. For the slug orbit-forms, orbit-forms/orbit-forms.php passes. A version that already exists for the product is refused with "That version already exists for this product." See Create a release.

Publishing a release fails because of its version

TierMint refuses to publish a version that is not higher than the live one, and the message names both versions. Click Publish anyway only when you mean to put the older version live. See Publish a version that is not newer.

A package download says it is missing from storage

The stored file has gone, for example because someone deleted it from the uploads folder. The Download button on the Releases tab fails with "The package for this release is missing from storage. Re-upload the build to restore it." Customer updates fail with "The update package could not be downloaded." until you attach the package again. Edit the release and attach it. See Check the attached package.

Emails and webhooks

A buyer did not receive the receipt

TierMint sends the receipt from a background job after the order completes, so it can arrive a little after the payment.

1. Open Tools → Scheduled Actions and search for tiermint_job_send_email. A pending action has not run yet, and a failed one shows its log.
2. A completed action does not prove the email went out, because failures are caught and logged. Look in the tiermint_logs table for an email row, or an error row with the reason. The table carries your database prefix and no admin screen shows it, so use a database tool.
3. Check that Send purchase receipts is on under TierMint → Settings → Emails.
4. If you use an SMTP plugin, check its log too.

See Check whether an email was sent.

A webhook endpoint shows Failing

Every retry to the endpoint failed, so TierMint switched it off, and a warning names its URL on every wp-admin screen. Fix the receiver so it is reachable and returns a 2xx status, then turn Active back on under TierMint → Settings → Webhooks. That clears the badge and the warning. Deliveries that failed are not sent again. See Retries and failing endpoints.

A webhook delivery never arrived

Check Tools → Scheduled Actions for a tiermint_job_send_webhook action, and the logs table for a webhook_out entry with the status your receiver returned. Also check that the endpoint was active and subscribed to the event when it happened. After a SECURE_AUTH_KEY change, the log holds an error row saying there is no usable signing secret. TierMint does not retry that delivery and shows no Failing badge. Delete the endpoint and create it again. TierMint refuses addresses on your local or private network, and ports other than 80, 443 and 8080. See Where deliveries are logged.

Your webhook signature check fails

Most often the receiver checks a parsed or re-encoded body. Read the raw body, such as php://input, before anything changes it, and use the signing secret of this endpoint. TierMint shows a secret only once, so if you lost it, delete the endpoint and create a new one. See Verify the signature.

Pro license and updates

Pro features and the License tab are missing

The free plugin is inactive or older than 1.0.0, so Pro loads none of its features. Pro shows the notice "TierMint Pro needs the free TierMint plugin (version 1.0.0 or newer) active. Pro stays inactive until then." Install, activate or update the free plugin, and Pro starts on the next page load. See If the free plugin is missing or too old.

Pro license activation is refused

When every site on the license is in use, click Deactivate in the License panel of a site you no longer use, or upgrade the plan, then paste your key into License key and click Activate again. When the key is not accepted, copy it from your DrPlugin account again. When DrPlugin is busy or cannot be reached, your key is still saved, so try again in a few minutes. A localhost address, an IP address or a host name with no dot cannot be licensed. See If activation is refused.

The License panel says it is running on the last good check

DrPlugin did not answer the last check, and Pro is using its 72-hour grace period. If the message does not clear, ask your host whether outgoing HTTPS requests are blocked. See How updates arrive.

A notice says a new Pro version is waiting, but no update shows

DrPlugin sends the package only to an active license. The notice also shows when the key was not accepted, the site is not activated or the site limit is reached. Renew the license, activate this site or free a slot, as the notice says. The update shows after the next background check. See A notice says a new version is waiting.

A setting says it is provided by an extension that is not loaded

The Pro admin script did not load. Reload the page. If the message stays, look for a script error from another plugin in the browser console. See Install and activate Pro.

Subscriptions and cart recovery

A subscriber does not see Switch plan

Check that the current tier has an active target ticked under Allowed switch targets, that the subscription is in a trial, active or past due, and that no other plan change is scheduled. TierMint lets you tick a target on another billing period, so allow switches only between tiers with the same billing period and interval. A PayPal subscriber still sees Switch plan, but the switch is refused with a message to manage the subscription in PayPal. See What the subscriber sees.

Update payment method shows an error

The button opens Stripe's customer portal, which has to be set up in your Stripe Dashboard first. Without it, Stripe cannot open the portal. For a PayPal subscription, the buttons tell the customer to manage it in their PayPal account. See Let customers manage their subscription.

A customer's software stopped after a failed payment

It should keep working through the grace period: until the license end date plus 14 days, or the value your site sets with tiermint_dunning_grace_days. The customer's account page is stricter: it shows the license as expired from its stored end date and shows no Download update link for it. Check the license end date under TierMint → Licenses. A subscription license's end date is the last paid period plus 3 days. See The grace period.

No cart recovery emails go out

1. Check that Send cart recovery emails is on, and that at least one email is enabled, under TierMint → Settings → Recovery.
2. Check that the first email's wait has passed since the buyer submitted the checkout form.
3. Check that your site's cron runs. The hourly check uses Action Scheduler, which needs WP-Cron or a server cron job.
4. Check that the order is a pending or abandoned purchase with an email address, and is younger than the maximum cart age.

A visitor who never submitted the checkout form left no email address, so TierMint cannot email them. See Abandoned cart recovery.

The Recovery settings do not save

TierMint refuses the save when two enabled emails are out of order, when Maximum cart age (hours) does not clear the last enabled email, or when a chosen discount no longer exists. The maximum cart age must be at least one hour more than the last enabled email's wait. To turn on email 3 at 72 hours, for example, raise it to at least 73. See Set up the reminder emails.

A cart restore link does not work

The link has probably expired, or it was edited. Open the cart under TierMint → Cart recovery, click Show details and send the buyer the freshly generated link. If your page cache serves URLs with query strings from cache, exclude tiermint_restore. See What the restore link does.

Tax and invoices

No tax is added at checkout

Tax stays off until Enable tax calculation is on and Merchant country is set under TierMint → Settings → Tax. A buyer in a country with no rate in the table and no override pays no tax. If the tax engine fails, the sale goes through without tax, and TierMint writes the failure to its tiermint_logs table. See Turn on tax calculation.

Buyers are asked to confirm their country

The country they picked differs from the country of their connection, and checkout stops with "The country you selected does not match where your connection appears to be. Please confirm the country you live in to continue." A buyer on a VPN, or traveling, often triggers this. If it happens to many buyers, your IP country source may be wrong. Correct it with the tiermint_tax_geoip_country filter, or set the mismatch policy to Trust the billing address. See Two pieces of location evidence.

A business buyer is charged VAT

Before payment, the checkout still shows the VAT. It comes off when the buyer pays and VIES confirms the number. If the VAT is still on a completed order, open its tax record at admin.php?page=tiermint#/tax/orders/<order id> to see the VIES answer. A flagged order also links to it from the Flagged orders tab under TierMint → VAT reporting. A newly registered number can take days to appear in VIES, the number's country must match the country the buyer picked, and a GB or XI number is always charged VAT. See Check business VAT numbers (VIES).

The tax line does not update at checkout

The order summary updates through a background request as the buyer fills in the form. If your page cache serves the checkout page from cache, exclude it. See EU VAT and tax.

VAT reporting asks for your establishment country

The screen shows "Set your business establishment country in the tax settings before viewing or exporting an OSS return." Set Merchant country under TierMint → Settings → Tax. Tax calculation itself does not have to be on. See Before you start.

The quarterly return is empty

Check that you picked the right quarter, in UTC. Only completed orders are on a return, and subscription renewals never are. A sale with no recorded place of supply is listed under Orders that need attention instead. See VAT reporting and OSS returns.

Receipts go out without an invoice

When no order gets an invoice and the log is empty, Send purchase receipts is off. TierMint creates the invoice while it builds the receipt, so turn the receipt back on under TierMint → Settings → Emails. When a single receipt went out without its invoice, the reason is in the tiermint_logs table. To issue the invoice for one order, click Download invoice on its order screen. See How invoicing works.

The log says the invoice store refuses to write

TierMint could not create or confirm the guard files in wp-content/uploads/tiermint/invoices/. Most often a file permission or an open_basedir limit blocks the folder. The PDF engine also needs a folder it can write to under uploads. Fix the permissions. See Where invoices are stored.

A customer's Invoices tab is empty

Check that the customer has completed orders, and that they are logged in to the account linked to the customer record that bought. A fully refunded order loses its row. The tab shows the 20 most recent invoices, taken from the customer's 50 most recent orders. See PDF invoices.

Other Pro screens

Analytics shows that it is being prepared

On a new install, the Overview, Revenue, Subscriptions and LTV tabs show "Analytics are being prepared" until the daily job has run once, and Activations shows "No activation data yet". It usually finishes within a day. To build the snapshots now, run wp tiermint analytics rebuild. See When the dashboard is still being prepared.

A migration source cannot be read

The source's card on TierMint → Migrate gives the reason. Easy Digital Downloads needs its 3.x tables on the same site. License Manager for WooCommerce must stay active during the migration, because TierMint asks it to decrypt each key. SureCart needs a secret API token that reaches SureCart. See Migrate from another store.

An Elementor kit import is refused

The import shows "This kit needs Elementor active with the TierMint Elementor integration turned on before it can be imported for Elementor." Activate Elementor and turn on Elementor widgets under TierMint → Settings → Integrations. A Blocks import needs neither. See Import a kit for Elementor.

PayPal affiliate payouts fail or stay in processing

PayPal Payouts needs its own approval on your PayPal business account, and until PayPal grants it, a run shows the error PayPal returns. Subscribe the payout item and payout batch events on your PayPal webhook, or payouts stay in processing until the hourly check settles them. An affiliate with no payout email is skipped, so pay them with a manual payout. See Pay affiliates through PayPal.