Error Codes

This reference covers error codes you may encounter when using CheckoutOS. Each error includes its meaning and recommended resolution steps.

Cause: Unable to establish connection with your Shopify store.

Solutions:

• Verify your Shopify store URL is correct
• Check that your Shopify store is active (not paused or on hold)
• Reinstall the CheckoutOS app from the Shopify App Store
• Ensure you have admin or owner permissions on the Shopify store

Cause: CheckoutOS doesn't have required permissions.

Solutions:

• Reinstall the app to re-authorize permissions
• Verify you're logged in as a store owner or admin
• Check Shopify Admin → Apps → CheckoutOS for permission status

Cause: Your Shopify plan doesn't support checkout extensions.

Solutions:

• Upgrade to Shopify Plus for full checkout extensibility
• Apply for Checkout Extensibility beta access (non-Plus stores)
• Use post-purchase features only (available on all plans)

Cause: Campaign has missing or invalid settings.

Solutions:

• Review all required campaign fields
• Ensure at least one product is selected for upsell
• Check that discount values are within valid ranges

Cause: A product in your campaign no longer exists or is unavailable.

Solutions:

• Check if the product was deleted from your Shopify catalog
• Verify the product is published and active
• Update the campaign with valid product IDs

Cause: Campaign targeting rules contradict each other.

Solutions:

• Review AND/OR logic in targeting rules
• Ensure minimum and maximum values don't overlap incorrectly
• Check for impossible conditions (e.g., cart > $100 AND cart < $50)

Cause: Unable to apply discount to upsell product.

Solutions:

• Check for conflicting Shopify discount codes
• Verify discount combination settings in Shopify
• Ensure the product isn't excluded from discounts

Cause: Unable to charge customer for upsell product.

Solutions:

• This is typically a Shopify payment gateway issue
• Check Shopify Admin → Settings → Payments for gateway status
• Customer may need to retry with a different payment method

Cause: Upsell product is out of stock.

Solutions:

• Enable inventory tracking fallbacks in campaign settings
• Set up backup products for out-of-stock scenarios
• Configure "Continue selling when out of stock" in Shopify if appropriate

Cause: API request used an invalid or expired key.

Solutions:

• Regenerate API key in Dashboard → Settings → API
• Check for typos or whitespace in the key
• Ensure the key has required permissions

Cause: Too many API requests in a short period.

Solutions:

• Implement request throttling in your application
• Use webhook events instead of polling
• Contact support if you need higher rate limits

Cause: Webhook signature verification failed.

Solutions:

• Verify webhook secret matches Dashboard → Settings → API
• Ensure you're using the raw request body for signature verification
• Check that your server clock is synchronized

Cause: Checkout extension couldn't load in the browser.

Solutions:

• Check browser console for JavaScript errors
• Disable ad blockers or privacy extensions temporarily
• Clear browser cache and try again
• Test in a different browser

Cause: Extension loaded but couldn't render properly.

Solutions:

• Check for custom CSS conflicts
• Verify image URLs are valid and accessible
• Review extension configuration for invalid settings