Troubleshooting

Checkout Returns Invalid Checkout

Check:

cart line price_id
quantity
product status
price active state
currency
gateway id
coupon
tax address
required agreements

Log server-side context without secrets.

Signed License Request Fails

Check:

site_uuid
secret_version
site_secret
timestamp skew
nonce reuse
body hash
canonical path
base64url signature encoding

Native Update Does Not Appear

Check:

Update URI header
store_hostname
product_slug
software_kind
manifest_url
installed version
release version
rollout percentage
license_status
site_secret
update_check_url
package token response

Client License Page Does Not Appear

Check:

require_once __DIR__ . '/vendor/awecommerce-client/bootstrap.php';

add_action('plugins_loaded', function () {
    AweCommerce_Client::register([
        'product_slug' => 'example-plugin',
        'store_hostname' => 'store.example.com',
        'api_base_url' => 'https://store.example.com/wp-json/awecommerce/v1',
        'plugin_file' => __FILE__,
    ]);
});

Also confirm the current user can manage site settings.

Portal Returns 404 For Existing Resource

This usually means the logged-in customer does not own the resource. Check:

current WordPress user
linked AweCommerce customer
resource customer_id
portal auth guard
ownership check

Queue Job Fails Repeatedly

wp awecommerce queue list --status=failed
wp awecommerce queue retry 123
wp awecommerce queue work --max=1

Check the job's last error and related record.

Webhook Does Not Update Order

Check:

gateway webhook secret
event persisted
signature verification
event mapper
gateway transaction id
order lookup
idempotency
webhook replay result

Package Download Fails On Same Host

The bundled client includes same-host loopback handling for package downloads. Check:

store_hostname equals current site host
api_base_url package path
REST package token route
package file readability
upgrader_pre_download result
offload headers

Run Focused Checks

php bin/api-check.php
php bin/checkout-check.php
php bin/portal-check.php
php bin/subscription-check.php
php bin/queue-check.php
php bin/frontend-check.php
php bin/security-regression.php