How to set template in onepage/checkout/success

How to set template in onepage/checkout/success

August 12, 2026 · Illustrated author avatarBy Stefan Bogdanescu
How to set template in onepage/checkout/success

Setting Up the Onepage/Checkout/Success Page Template: A Step-by-Step Guide

If you’re facing challenges setting up the onepage/checkout/success page template in Magento, you’re not alone. This step often trips up even seasoned developers. Let’s walk through a comprehensive solution that should resolve your issue.

Understanding the Layout Structure

In Magento, the layout is defined hierarchically across several XML files. The base file for the checkout process is located at base/default/layout/checkout.xml. However, to make theme-specific changes like modifying the template, you need to create an override in your custom theme’s layout folder (frontend/default/custom/layout).

Modifying the Template

First, let’s understand what you tried and why it didn’t work.

Your Attempts:

  1. You attempted to modify the root reference in your custom local.xml. However, Magento checks multiple layout XML files for a specific block or page type. The checkout_onepage_success is defined in the base file (base/default/layout/checkout.xml) and not in local.xml.

  2. Creating a custom checkout.xml with the same structure as the base one doesn’t override the existing behavior because the Magento system looks for the base file first.

  3. Even when you directly copy the content from the base layout XML to your custom theme, it doesn’t work due to the way Magento handles layout files.

The Correct Approach

Step 1: Understand the Base Layout Structure

The base/default/layout/checkout.xml file is structured as follows:

<layout version="0.1.0">
    <checkout_onepage_success translate="label">
        <reference name="root">
            <action method="setTemplate">
                <template>page/2columns-right.phtml</template>
            </action>
        </reference>
    </checkout_onepage_success>
</layout>

Step 2: Create the Custom Layout XML

Create a new file named checkout.xml in your custom theme folder (frontend/default/custom/layout). This file should look like this:

<layout version="0.1.0">
    <checkout_onepage_success translate="label">
        <reference name="root">
            <action method="setTemplate">
                <template>page/1column.phtml</template>
            </action>
        </reference>
    </checkout_onepage_success>
</layout>

Step 3: Flush Magento Cache

After updating the layout XML, you must flush Magento’s cache to ensure the changes take effect. You can do this via the command line using:

php bin/magento cache:flush

Why Your Attempts Failed and Best Practices

Your attempts failed due to Magento’s layout precedence rules. When a block is requested that matches multiple layout files, Magento prefers the base theme over custom themes.

To ensure your layout changes take effect in Magento 1.7:

  • Always use the correct layout XML file for the specific page type you want to modify.
  • Flush the cache after updating layout XML files.
  • Use the setTemplate action within the <reference name="root"> structure for template overriding.

Conclusion

Setting up the onepage checkout success page template requires a deep understanding of Magento’s layout structure and precedence rules. Always remember:

  • Create your custom layouts in the correct theme folder (frontend/default/custom/layout/).
  • Use the setTemplate action to change the template.
  • Flush the cache after updating layout files.

For more advanced customizations, consider reading our in-depth guide on Magento Layout XML Best Practices.

Checkout Themes Configuration Errors

Our network