Help
Log in

Troubleshooting your Checkout Blocks content

The content of your Checkout Blocks might not display as expected due to various reasons, resulting in elements disappearing or not functioning properly. Common issues include display rules not being met, permission misconfigurations, or discrepancies between the settings in the block itself and how the block has been added to the checkout and accounts editor.

This guide helps you troubleshoot and resolve common Checkout Blocks issues yourself. If you're still having issues after reviewing the steps in this guide, then contact Shopify Support for assistance.

On this page

Troubleshooting blocks

Blocks are the customization elements that display content in your checkout, such as custom fields, dynamic content, and banners. If a block isn't working as expected, then use the following sections to identify and resolve the issue.

Block isn't displaying in checkout

Troubleshoot block not added to editor

Creating a block in the Checkout Blocks app doesn't automatically add it to your checkout. You need to add the block to your checkout configuration using the checkout and accounts editor.

Steps:

  1. From your Shopify admin, go to Settings > Checkout.
  • In the Configurations section, click Customize next to the configuration that you want to modify.
  • Navigate to the checkout page where you want the block to display.
  • Click ⊕ Add block and select the appropriate block type.
  • Configure the Block ID to match the ID of the block you created in Checkout Blocks.
  • Click Save.
    • Troubleshoot block not set to Active

    A block must be set to Active for it to display within the checkout. Draft blocks don't display to customers.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Blocks.
  • Click the block that you want to activate.
  • In the Status section, select Active.
  • Click Save.
    • Troubleshoot block not published to market or page

    If your block is configured with market-specific publishing settings, then it displays only in the markets you've selected. If the block is published only to specific checkout pages, then it won't display on other pages.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Blocks.
  • Click the block you want to review.
  • In the Publishing section, confirm that the block is published to all applicable markets.
  • In the Checkout pages section, confirm that the block is set to display on all applicable checkout pages.
  • Click Save.
    • Troubleshoot display rules not being met

    Display rules define the conditions that must be met for a block to display in checkout. If these conditions aren't met during a customer's checkout session, then the block isn't displayed.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Blocks.
  • Click the block that isn't displaying.
  • Review the display rules configured for the block.
  • Verify whether your test checkout meets all of the required conditions, such as cart total thresholds, product types, or customer login status.
  • If you've set Only show when: All rules pass, then ensure that every rule is being met. If you've set Only show when: Any rule passes, then ensure that at least one rule is being met.
    • Troubleshoot Block ID mismatch

    Each block type in the checkout and accounts editor has a Block ID setting. The Block ID in the editor must match the Block ID of the block you created in the Checkout Blocks app. If the IDs don't match, then the block isn't displayed.

    For example, if your block has a Block ID of 4 in the Checkout Blocks app, then the block in the checkout and accounts editor must also have its Block ID set to 4.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Blocks.
  • Click the block that isn't displaying and note its Block ID.
  • Go to Settings > Checkout.
  • In the Configurations section, click Customize next to the configuration you want to check.
  • Click the block in the editor that should display your content.
  • In the Block settings, confirm that the Block ID matches the ID from step 3.
  • If the IDs don't match, then update the Block ID to match.
  • Click Save.
    • Troubleshoot Preview block ID field contains a value

    The Preview block id (For testing purposes) field in the checkout and accounts editor is intended only for testing. If this field contains a value after saving your checkout, then it can override your block's display rules and cause unexpected behavior.

    Steps:

    1. From your Shopify admin, go to Settings > Checkout.
  • In the Configurations section, click Customize next to the configuration you want to check.
  • Click the block that isn't displaying correctly.
  • In the Preview block id (For testing purposes) field, delete any value so the field is empty.
  • Click Save.
    • Troubleshoot higher-priority block displaying instead

    If you have multiple blocks of the same type with overlapping display rules, then only the highest-priority block displays. Learn more about block priority.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Blocks.
  • Click ⇅ Edit priority.
  • Select the block type that isn't displaying.
  • Review the priority order. Blocks with a lower number have higher priority.
  • Adjust the Priority numbers to change which block displays first.
  • Click Save.
    • Troubleshoot active block limit reached

    Checkout Blocks supports up to 30 active blocks per block type. If you have more than 30 active blocks of a single type, such as 35 active custom field blocks, then only the first 30 blocks can display in checkout.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Blocks.
  • Filter by the block type you're troubleshooting.
  • Count the number of active blocks.
  • If you have more than 30 active blocks, then deactivate or delete any blocks you no longer need.

    • Block is displaying multiple times in checkout

    Troubleshoot block added to shared section

    Depending on where you add a block within the checkout and accounts editor, it might display across every step of checkout. The Order summary section and the area attached to the Continue or return button are consistent across all pages of checkout.

    To display a block on a specific step only, add the block to the main content area of that step.

    Steps:

    1. From your Shopify admin, go to Settings > Checkout.
  • In the Configurations section, click Customize next to the configuration you want to modify.
  • Click the block that's displaying multiple times.
  • Note which section the block is in. If it's in the Order summary or attached to the Continue or return button, then the block displays on every checkout page.
  • To display the block on a specific page only, remove the block from the current section and add it to the main content area of the desired checkout page.
  • Click Save.
    • Troubleshoot multiple block instances added

    Some block types, such as Line item edit blocks, typically only need to be added to the checkout one time. The block relies on display rules to display different content for different scenarios. If block content is duplicated, then you might have accidentally added the block more times than needed.

    Steps:

    1. From your Shopify admin, go to Settings > Checkout.
  • In the Configurations section, click Customize next to the configuration you want to check.
  • Navigate through each page of your checkout and review the blocks that have been added.
  • If you find duplicate blocks of the same type and Block ID, then remove the extras by clicking the block and selecting Remove block.
  • Click Save.

    • Troubleshooting errors when creating or saving blocks

    If you receive an error when trying to create or save a block, then review the following sections.

    Troubleshoot "There were some issues with your form submission" error

    This error typically indicates that your staff account is missing the required permissions to create blocks in Checkout Blocks.

    Required permissions:

    • Store permissions > Content: Staff must have permissions to View and Create and edit metaobject definitions, as well as View and Create and edit entries.
    • Store permissions > Store settings: Staff must have Manage settings permission.
    • App permissions: Staff must have at least permissions for Checkout Blocks.

    Steps:

    1. From your Shopify admin, go to Settings > Users and permissions.
    2. Click the staff account that's experiencing the error.
    3. Under Store permissions, expand the Content section.
    4. Confirm that Metaobject definitions has View and Create and edit permissions selected.
    5. Confirm that Entries has View and Create and edit permissions selected.
    6. Under Store settings, confirm that Manage settings is selected.
    7. Under App permissions, confirm that Checkout Blocks is selected.
    8. Click Save.

    If you don't have permission to modify staff permissions, then contact the store owner or a staff member with user management permissions.

    Troubleshooting custom discounts

    Custom discounts created in Checkout Blocks might not apply as expected due to several factors.

    Troubleshoot active automatic discount limit reached

    Shopify allows a maximum of 25 active automatic discounts at a time, including app-based discounts from all installed apps. This limit applies across your entire store, not just Checkout Blocks.

    If you try to activate a 26th automatic discount, then it isn't applied in checkout.

    Steps:

    1. From your Shopify admin, go to Discounts.
    2. Filter to display only Automatic discounts.
    3. Count how many automatic discounts are currently active.
    4. If you have 25 or more active automatic discounts, then deactivate or delete discounts you no longer need before activating new ones.

    Learn more about limitations when combining discounts.

    Troubleshoot discount not active

    A custom discount must be set to Active for it to apply within checkout. The discount also must not have expired based on its configured start and end dates.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Discounts.
  • Click the discount that isn't applying.
  • In the Status section, confirm the discount is set to Active.
  • In the Active dates section, confirm that the current date falls within the configured start and end dates.
  • Click Save.
    • Troubleshoot discount rules not being met

    Custom discounts in Checkout Blocks can have detailed conditional rules that determine when the discount applies. If these conditions aren't met during a customer's checkout session, then the discount won't apply.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Discounts.
  • Click the discount that isn't applying.
  • Review the rules and conditions configured for the discount.
  • Verify whether your test checkout meets all of the required conditions, such as minimum order value, specific products or collections, or customer eligibility requirements.
  • Adjust the discount rules as needed.
  • Click Save.

    • Troubleshooting delivery and payment method customizations

    If delivery or payment methods aren't being hidden, renamed, or reordered as expected, then review the following sections.

    Troubleshoot customization not active

    A delivery or payment method customization must be set to Active for it to apply within checkout.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Functions.
  • Click the customization that isn't working.
  • In the Status section, confirm the customization is set to Active.
  • Click Save.
    • Troubleshoot active functions limit reached

    Shopify Functions has limits on the number of active functions you can have per type. You can activate a maximum of 25 payment customization functions on each store. If you exceed this limit, then you might receive the error: Failed to enable customization. Please try again or contact support.

    These limits help ensure checkout maintains high performance. You need to merge or remove customizations to stay under the limit.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Functions.
  • Count how many active delivery method customizations you have (if troubleshooting delivery) or how many active payment method customizations you have (if troubleshooting payment).
  • If you've reached the limit for that type, then deactivate or delete customizations you no longer need.
  • Try activating your new customization again.
    • Troubleshoot customization rules not being met

    Delivery and payment method customizations rely on rules that determine when the customization applies. If these conditions aren't met during a customer's checkout session, then the customization won't take effect.

    Steps:

    1. From your Shopify admin, go to Apps > Checkout Blocks.
  • Click Functions.
  • Click the customization that isn't working.
  • Review the rules configured for the customization.
  • Verify whether your test checkout meets all of the required conditions.
  • Adjust the rules as needed.
  • Click Save.

    • Validating your changes with a test checkout

    Before relying on your Checkout Blocks customizations in a live environment, you should validate that they work as expected using a test checkout.

    Steps:

    1. From your online store, add products to your cart that match the conditions for the blocks, discounts, or customizations you want to test.
    2. Proceed to checkout but don't complete the purchase.
    3. Review each step of checkout and verify the following:
      • Blocks display in the correct locations with the correct content.
      • Custom discounts apply when eligibility requirements are met.
      • Delivery and payment method customizations function as expected.
    4. If you're testing display rules based on cart total, then try different cart values to confirm blocks appear and disappear at the correct thresholds.
    5. If you're testing customer-based display rules, then test both logged-in and guest checkout scenarios.

    Frequently asked questions

    How many blocks can I have active at the same time?

    You can have up to 30 active blocks per block type. For example, you can have 30 active custom fields, 30 active dynamic content blocks, and 30 active line item edit blocks simultaneously. You can create more than 30 blocks of a type, but only the first 30 active blocks can display in checkout.

    Why do I need specific staff permissions to use Checkout Blocks?

    Checkout Blocks creates metaobject definitions to store block configurations. Staff members need permissions to create and edit metaobject definitions and entries in order to save blocks in the app. Additionally, staff need Manage settings under Store settings and explicit App permissions for Checkout Blocks.

    Can I use Checkout Blocks if I'm not on Shopify Plus?

    Merchants on the Basic plan or higher can use dynamic content and static content blocks on their Thank you and Order status pages only. All other Checkout Blocks features, including custom fields, custom discounts, and delivery/payment method customizations, require the Shopify Plus plan.

    How do I know which Block ID to use?

    When you create a block in the Checkout Blocks app, it's assigned a Block ID (the default is 0). When you add that block type to your checkout in the editor, you need to set the same Block ID so the editor knows which specific block to display. If you want to display different blocks of the same type in different locations, then assign each block a unique Block ID and match those IDs in the editor. Learn more about Block IDs.

    Can I combine Checkout Blocks discounts with other discounts?

    Custom discounts created in Checkout Blocks are automatic discounts powered by Shopify Functions. They follow the same discount combination rules as other automatic discounts. You can have a maximum of 25 active automatic discounts across your store, including those created in Checkout Blocks and other apps.

    Before you contact Shopify Support about Checkout Blocks

    If you've tried the troubleshooting steps above and your Checkout Blocks issue persists, then you can contact Shopify Support for assistance. Before contacting Shopify Support, gather the following Checkout Blocks-specific information to help resolve your issue faster:

    • Block details: The name, type (such as custom field, dynamic content, or line item edit), and Block ID of the block that isn't working
    • Configuration screenshots: Screenshots of the block's settings in the Checkout Blocks app, including any display rules, publishing settings, and status
    • Editor screenshots: Screenshots of how the block is configured in the checkout and accounts editor, including the Block ID and Preview block ID fields
    • Error messages: Screenshots or exact text of any error messages you're receiving when creating, saving, or previewing blocks
    • Test checkout URL: A link to a test checkout or abandoned checkout where the issue can be reproduced, along with the cart contents used to trigger display rules
    • Expected versus actual behavior: A clear description of what you expected to happen versus what's actually happening in checkout
    • Troubleshooting steps completed: Which sections from this guide you've already reviewed and what you've tried
    • Staff permissions: Confirmation that your account has the required permissions for Content (metaobject definitions and entries), Store settings (Manage settings), and App permissions (Checkout Blocks)

    Having this Checkout Blocks-specific information ready helps Shopify Support to diagnose and resolve your issue more efficiently.