> ## Documentation Index
> Fetch the complete documentation index at: https://app.docs.circuly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and fix common issues with circuly Subscriptions

## Product not showing subscription options

If a product on your storefront doesn't show subscription plan options, check the following:

<AccordionGroup>
  <Accordion title="Is a subscription plan assigned to the product?" defaultOpen>
    Go to the circuly Subscriptions app and open your subscription plan. Check that the product is listed under the assigned products. If not, add it.

    You can also use the [Product Details Action](/docs/mintlify/admin-extensions#product-details-action) directly from the product page in Shopify Admin to quickly assign plans.
  </Accordion>

  <Accordion title="Is the subscription plan active?">
    Ensure the selling plan group containing this product is active and not in draft state.
  </Accordion>

  <Accordion title="Is the Unified purchase selector block added to your theme?">
    The subscription widget must be added to your product page template through the Shopify Theme Editor. See [Theme Extension Setup](/docs/mintlify/theme-extension#adding-the-block-to-your-theme) for instructions.
  </Accordion>

  <Accordion title="Are you viewing the correct product page template?">
    If you use multiple product page templates in your theme, make sure the Unified purchase selector block is added to the template assigned to this specific product.
  </Accordion>
</AccordionGroup>

## Subscription widget not appearing on storefront

If the Unified purchase selector block doesn't show up at all on your product pages:

<AccordionGroup>
  <Accordion title="Check the Theme Editor">
    Go to **Online Store > Themes > Customize** and navigate to a product page. Confirm the **Unified purchase selector** block is added and positioned correctly. See [Theme Extension Setup](/docs/mintlify/theme-extension).
  </Accordion>

  <Accordion title="Check the product has selling plans">
    The widget only appears on products that have at least one selling plan assigned. Products without plans will not show the block.
  </Accordion>

  <Accordion title="Preview your theme">
    Use the **Preview** button in the Theme Editor to see the block in action on a product that has selling plans assigned.
  </Accordion>
</AccordionGroup>

## Cross-sells not showing

If the cross-sell rows don’t display, or some rows are unexpectedly hidden:

<AccordionGroup>
  <Accordion title="Check the cross-sell config in the app">
    Cross-sells are configured in the app under **Cross-sell**. Open the main product’s cross-sell page and confirm rows are added and saved. See [Cross-sell setup](/docs/mintlify/cross-sell#configuring-cross-sells-in-the-app).
  </Accordion>

  <Accordion title="Check product availability">
    Cross-sell products must be **available** (in stock and published). Unavailable products are silently hidden on the storefront.
  </Accordion>

  <Accordion title="Check the main product’s plan selection">
    The block strictly mirrors the main product’s currently selected plan. If the customer picks plan group **A**, only cross-sells in plan group **A** are visible. Cross-sells outside that group are hidden until the customer switches groups — unless they’re marked **One time**, in which case they’re always visible. See [How frequency mirroring works](/docs/mintlify/cross-sell#how-frequency-mirroring-works).
  </Accordion>

  <Accordion title="Confirm the theme block is added">
    The **Cross-sell Products** block must be placed on the product page in the Theme Editor. Without it, no rows will render even if the app config is correct.
  </Accordion>
</AccordionGroup>

## Billing failures and retries

When a subscription billing attempt fails (e.g., declined payment), the system handles retries automatically:

* Failed charges are retried according to the dunning schedule
* Customers are notified to update their payment method
* After all retry attempts are exhausted, the subscription status may change based on your configuration

<Tip>
  Customers can update their payment method directly from the [Customer Portal](/docs/mintlify/customer-portal) without needing to contact support.
</Tip>

## Customer portal not loading

If customers don't see their subscriptions in their account page:

<AccordionGroup>
  <Accordion title="Customer accounts must be enabled">
    Go to **Settings > Customer accounts** in your Shopify admin and ensure customer accounts are turned on.
  </Accordion>

  <Accordion title="Check the extension is active">
    Go to **Settings > Customer accounts > Extensions** and verify the circuly Subscriptions extension is enabled.
  </Accordion>

  <Accordion title="Customer must have subscriptions">
    The portal only shows for customers who have at least one subscription contract. If a customer has never subscribed, they won't see the section.
  </Accordion>

  <Accordion title="New customer accounts recommended">
    The customer portal extension works best with Shopify's new customer accounts experience. If you're using classic accounts, consider upgrading.
  </Accordion>
</AccordionGroup>

## Extension not appearing in Shopify Admin

If the admin extensions (product actions, bulk actions) aren't showing:

<AccordionGroup>
  <Accordion title="Refresh the page">
    Shopify Admin extensions sometimes take a moment to load. Try refreshing the page.
  </Accordion>

  <Accordion title="Check the app is installed">
    Verify the circuly Subscriptions app is still installed and active on your store.
  </Accordion>

  <Accordion title="Check the correct page">
    * **Product Details Action** appears under **More actions** on individual product pages
    * **Product Index Selection Action** appears when selecting products on the Products list page
  </Accordion>
</AccordionGroup>

## Troubleshoot wizard

The circuly Subscriptions app includes a built-in **Troubleshoot wizard** that walks you through a 4-step diagnostic process:

1. **Eligibility Status** — Checks whether the product has a subscription plan assigned and is eligible
2. **Payment Gateway** — Confirms your payment gateway supports subscription billing
3. **Store Plan** — Verifies your Shopify plan supports subscriptions and your store is properly configured
4. **Resolution** — Provides specific recommendations based on the issues found. If the issue persists, a **Submit a Ticket** button lets you open a pre-filled support ticket with all diagnostic results included — so the support team gets full context immediately.

The wizard is accessible from the info banner shown when creating or editing a subscription plan on an ineligible store.

## Billing & safety

<AccordionGroup>
  <Accordion title="Why am I not seeing commission charges for some orders?">
    circuly only charges commission for subscriptions created through circuly. If you use other subscription apps alongside circuly, orders from those apps are automatically excluded — you'll never be charged commission for subscriptions you manage outside of circuly.

    This detection happens automatically using an internal ownership marker that circuly places on every subscription plan it creates. No configuration is needed on your part.
  </Accordion>
</AccordionGroup>

## Still need help?

If you can't resolve your issue with the steps above, contact our support team:

<Card title="Contact Support" icon="envelope" href="mailto:miguel@circuly.io">
  Email us at [miguel@circuly.io](mailto:miguel@circuly.io) and include your store URL, a description of the issue, and any relevant screenshots.
</Card>