Over the last few years, I’ve worked on lots of specifications for new Magento stores – for merchants migrating their existing Magento 1 store over to Magento 2, and for merchants moving from a different platform altogether. In order to provide context for an agency before you into discovery (depending on the size of the project), I believe it’s important to provide enough detail that you can obtain an indicative cost, which then allows you to differentiate between the different partners.

When you’re approaching a project of this nature, it’s important that you provide as much detail around your requirements as possible, in order to receive an accurate quotation on the project, in terms of timing and financials, and to ensure that you’re not losing functionality, which is particularly important if you’ll be working with smaller agencies. A larger Magento partner would likely insist on a comprehensive discovery before going into a build project, where they’d assess all of the functionality and integrations required, as well as the business impact – but smaller partners or freelancers are less likely to do this exercise.

This guide is designed to provide insight into the areas and data points that should be covered in a specification, as well as information around the native functionality available in Magento 1.x / 2.x Community and Enterprise editions. Some of the points are more to provide context for the integrator (e.g. hosting preferences or server setup), as they may impact the development time in some way.

I’ve broken the areas down into separate categories and I’d generally suggest creating a spreadsheet with each of the following as separate tabs and as much information for each line item as possible (e.g. how it needs to work on both the front-end and the back-end and any other dependencies).

I tend to use the MOSCOW methodology to highlight the importance of the feature and whether it’ll be built into the initial launch or considered further down the line. MOSCOW is made up of the following:

Must Have Feature
Should Have Feature
Could Have Feature
Won’t Have Feature

I’d then have a separate column to outline whether the feature requires custom development or whether it’s native within the desired version of Magento. Regardless of whether it’s native or custom, I’d generally recommend writing a detailed outline of how the feature needs to work, so the agency can better understand if any further changes need to be made (e.g. subscription payments, but with a split deposit).


Information about scaling requirements is provided for context, as it could impact the approach taken with certain processes or functions, or it could trigger suggestions around hosting setup. I generally suggest providing details around monthly traffic and order numbers, to give the integrator an idea of the load that’s likely to be hitting the store. In addition to the average numbers, I’d also suggest providing detail around key peaks for both areas.

Platform Setup & Hosting

It’s important to provide information around how you plan to host the new store and the environments you require. This is also where I’d detail your preferred version of Magento, for example, Magento 2 Community Edition or Magento 2 Cloud Edition.

Here are the points I’d usually suggest adding:

  • Preferred Magento version at this stage (e.g. Magento Enterprise edition or Magento Enterprise Cloud edition)
  • Hosting provider (e.g. Sonassi or Elastera)
  • Server setup and specifications
  • Required environments (e.g. staging, UAT and live)

If you’re unsure on this section, most agencies will happily provide guidance and will have preferred partners for things like hosting. I generally recommend Elastera and Sonassi, based on what I’ve seen with clients. Sonassi is suited to mid-level and enterprise-level Magento merchants, whereas Elastera (AWS-based) is purely enterprise-level. The other consideration would be whether you want to look at Magento’s cloud edition, if you’re going with enterprise anyway.

General Design / Front-End Work

This section would be more of an overview around how you want the store to look and feel and would include any top-level design or front-end aspects of your current store that you want to carry over to the new build. If you already have designs, these could be included to make this process easier and more effective. If you’re planning on using the agency for design as well, this would be covered as part of the design discovery.

Here are the things I’d generally include, bearing in mind that this section is fairly top-level:

Who will be responsible for the design?

Will it be completed by an in-house team, a third party design agency or do you want the partner to complete the design work.

Deviation from current store design

I’d recommend providing some information around how much you plan to change the design of the new store, or whether it’ll be more of a lift-n-shift of the existing store.

Header & footer

A top-level overview of how you want the universal header to look and the key components that need to be included. Also how you want the footer to look and the key components that need to be included. For example, you may require an email signup widget, and the footer to be editable via static blocks in Magento, and you may wish to define how the footer should be stacked on mobile devices.

Primary navigation

Any top-level requirements around the main navigation should be outlined. For example, will there be a full-width mega navigation system, is there a need for images / promotions in columns, and does the navigation need to be manageable via static blocks or the category tree in Magento?

The core pages that need to be built

These are the main templates that will be used on the store, for example the homepage, product list page, collection page, product detail page, cart page, checkout pages, account pages, blog pages (if managed via Magento / part of the project), specific CMS pages and so on.

Because this section is more about providing an overview of how the site will look, MOSCOW ratings and the native / custom information aren’t needed.

Content Management & CMS

This section is focused on how the different types of content you’re creating will be edited and managed, and the functionality you and your team require. Magento recently acquired Bluefoot, a CMS extension created by Gene Commerce, which is currently being re-factored into the core of Magento and is supposed to be released as part of the Magento 2.2 release, in September 2017. Magento also announced that some components of Bluefoot will be available in the Community Edition, which is great for smaller merchants.

These are the requirements that I feel need to be detailed in this section:

Menu management

How will the different menus, such as top navigation, secondary navigation on product list pages, footer menus and so on, be managed within your store? This is where you may want to list custom requirements around things like images or videos in navigation, specific mobile menus, and any other special requirements for a mega navigation menu. You’d want to detail the requirement and also how it should be managed in the Magento back-end. Out of the box, your primary menu navigation would be based on the category tree, but lots of agencies create custom extensions or provide the ability to manage links via static blocks for added flexibility.

Widgets / blocks required

This would be where you’d detail the widgets that are needed on different pages, such as product recommendation blocks, forms, latest blog posts, videos, banners, and any accordions. This needs to be mapped out in detail, as Bluefoot is able to handle most of these requirements, but it or Magento may not support your preferred method of management (for example, setting SKUs in product recommendation blocks at page-level). Bluefoot provides a lot more freedom in this area and provides drag and drop functionality for widgets, amongst other things.


This is usually quite an important area, as there are lots of options around how a blog can be managed, such as via an external WordPress instance, WordPress via something like BlogPro or Fishpig (WordPress > Magento integration), a blog module within Magento (such as the MageFan blog extension), or via Bluefoot. It’s important to provide guidance on how the blog needs to work and everything you need in terms of features, such as an admin panel within Magento, blog posts to be pulled through onto other pages, or the ability to add product blocks).

Content pages

This would be where you’d detail any special content pages you might need, such as your about page, sizing guides, buying guides, T&C pages and so on, and the work needed from the agency. With Bluefoot, you should be in a much better position to create these types of page templates yourself, but if there are any special requirements here, they should be listed.

Content on different page templates

Here, you’d detail the blocks that need to be available for different page templates, such as a  50/50 content block with an image on product list pages, or specific brand information on certain products etc. This would give the agency an idea of whether certain blocks need to be added or whether custom input boxes need to be added in the back-end of Magento. You’d also detail things like lightboxes needed on product detail pages here.

Scheduled publishing

Scheduled publishing is something that lots of merchants want and it’s something that is native in Magento 2 Enterprise. You should detail whether this is needed and how it needs to work, as if you end up going with Magento Community Edition, the agency would need to find a tthird-partyextension or create the functionality. You’ll need to detail what will be scheduled here too.

Staging & preview

Similar to scheduled publishing, this is an enterprise-only feature, so the agency would need to find an alternative solution if this is something you require, but you’re going with Magento Community Edition.

Product catalog setup

Product types

Magento supports 7 product types out of the box, which are:

  • Simple products
  • Configurable products
  • Bundled products
  • Grouped products
  • Downloadable products
  • Virtual products
  • Gift card (enterprise edition only)

Here, you should provide detail around your requirements for each and the number of each that you’ll have. Configurable products are a key area and it’s important to outline all of your requirements for this, which could be things like front-end nuances, stock control, the core options available, how the options should appear in PLPs and so on. If you have any non-native requirements around how these work, such as a differing approach to the parent / child relationship or how they’re displayed on the product list page, this should be outlined here. I’d usually list out the types of variants / options that will be used for configurable products too, just to give the agency more of an understanding around whether it’s standard or non-standard, and whether there’ll be any front-end work required on the product detail page.

With things like bundled products, it’s important to outline how they should look and how often they’ll be used.

Here, you’d probably want to outline things like how the products would be set up too, covering things like whether you’re going to be creating them via an ERP or PIM, and the data points that need to be passed into Magento. These would be detailed further in the integrations section, but it’s good to provide a bit of info around that in this section too.

Things like product options (configurable options that can be assigned to individual products – different to a configurable product) should also be detailed, along with how this will be stock managed.

You’d probably also want to briefly touch on any non-standard requirements around Magento attributes and attribute sets too.

Other things that could be listed in this section:

  • Core attributes and attribute sets and how they’d be used
  • Requirements around customer groups (elements specific to a certain type or group of customers)
  • Guidance around what will need to be imported and the format of the data

Product detail page

Here I’d try to summarise all of the components on the product detail page, as well as how things need to be managed in the back-end. This would include things like product images, product videos, 360 images, the attributes on the page (e.g. price, description etc.) and then all of the content blocks, up-sells / cross-sells / related products, and how they should be managed, along with things like a product-level Instagram feed etc. A lot of this will come out in a subsequent discovery anyway, but it’s good to provide an idea of the elements and functionality that you’ll have on this page template.

Examples of other things that would be listed here include:

  • Requirements around how content is being broken down and the fields you need
  • Any non-standard functionality like comparisons on PDP, attribute tooltips, personalisation / customisation, backorders etc.
  • Pre-ordering
  • Any integration of third-party product review tools

Product list page

The same principles apply as the product detail page, and the main thing is to list all of the elements of the page template so that the agency can then determine whether there is any custom work required, or whether Magento is capable of achieving the features out of the box. Then, beyond that, it’s just about estimating the front-end side of things, so providing as much detail as possible is key.

An example of a feature that would need to be listed here could be icons for specific selling points of products, which would be managed at product-level and would require a customisation. Listing out how this needs to look and work in the admin would be key for the agency being able to provide a quote.

Examples of other things that would be listed here include:

  • Any specific sort ordering and display options for the page
  • Product filters, to allow visitors to refine the list of products


The homepage is likely to be one of the most frequently updated pages on the entire site, so it’s important to list all of the elements required for this page, and the means by which they will be updated. Elements on the home page might include a slideshow, a product carousel featuring new or best-selling items, multiple banners to showcase specific products or categories, and even a custom product selector widget.

It’s important to define how these elements will be created and managed, both for the initial launch and going forwards once the site is live.

Examples of other things that would be listed here include:

  • Any popups or modal dialogs that are required to appear
  • Any Geo-IP functionality, to identify which country visitors are from
  • Any different requirements for logged in customers versus non-logged in customers, or for other visitor segments, such as first-time visitors.

Account section

The account section of the site is typically one that remains fairly true to the out of the box functionality, with the only customisation needed usually being design elements and layout.

You may, however, want to specify here whether you need the facility to allow repeat orders, or to use gift vouchers or store credits as part of a purchase, and whether customers can manage the newsletter subscriptions from within their account.

Examples of other things that would be listed here include:

  • Any requirement for a customer rewards or loyalty points system
  • Any additional data fields that you would like to collect on account creation
  • Any wishlist requirements

Marketing Requirements

In this section, you would typically list any features you require for marketing, which would generally cover all of the customer acquisition channels, email, product and merchant reviews, feeds and anything around analytics and tag management. You’d generally need to be pretty specific here, specifying how the integration with NOSTO or dotMailer, for example would work – in terms of what data needs to be imported, the data that needs to be sync’d moving forward, the integration requirements etc.

I’d also include information around things like promotions and landing pages here too.

Examples of other things that would be listed here, include:

  • Requirements around tag management (any specific technical requirements – e.g. enhanced eCommerce) and the solution you’ll be using.
  • Any specific requirements around analytics and business intelligence
  • Integration into marketplaces, such as eBay and Amazon (and detail around the solution and how often the sync needs to run etc).
  • Data feed requirements (which feeds, how they need to be managed etc)
  • Personalisation (the solution – e.g. NOSTO – how the blocks need to work, where the data needs to go etc).
  • Common promotions you run (e.g. free delivery, BOGOF, free gift with purchase etc)
  • Loyalty programs (requirements around loyalty points and the program itself, as well as the third party solution if applicable)
  • Email marketing integration (e.g. product data needs to be passed into dotmailer regularly, along with data from customer attributes)
  • Requirements around customer segmentation (personalised customer journeys and requirements for segmentation of data)

SEO requirements

In this section, you would include information about the data that needs to be imported (e.g. product descriptions, category descriptions, meta data, legacy redirects, setup of things like hreflang and canonical URLs etc), along with who will be responsible for this. This is an area that needs to be very carefully defined, as lots of actions in this area are often missed and it’s a key area from a performance / project success perspective.

Examples of other things that would be listed here include:

  • Detailed overview of what needs to be imported from the current store
  • Responsibilities around often ambiguous areas (such as creation of category tree, redirect mapping, legacy redirect mapping etc)
  • Processes around 301 redirects
  • Requirements for header tags
  • Requirements for meta data fall-back logic
  • Requirements around more complex areas, such as hreflang, canonical logic, use of javascipt / AJAX, other directives etc
  • Requirements for structured data
  • Requirements for mobile SEO (maybe AMP)

These are just a few areas to think about, I’d suggest consulting an agency or an experienced consultant to ensure success in this area (someone like Carl, Steve or Dan have extensive experience with Magento SEO).


In this section, you would cover the types and frequency of the various kinds of promotion you would like to be able to offer. These might include percentage or flat rate discounts, BOGOF offers, catalog price discounts, free gift once X criteria is met and so on.

Examples of other things that would be listed here include:

  • The format of promotional codes (and whether they’re single-use, unique codes etc)
  • Any unusual promotional requirements, such as free gifts or discounts that kick in after a set number of orders have been placed
  • Any promotions that are targeted at specific customer groups

Multi-store setup

If you’re planning on having multiple storefronts as part of your new store, you should list out each store along with the nuances in the catalog and the overall customer experience. If you’re going to have international storefronts for example, with the same product catalog but with local language and currency, this is important as the integrator could then suggest using a store in Magento and using the same theme and inventory file. If, however, you wanted to use a different warehouse as part of this, it’d require more customisation and the integrator would need to create a second website and pass in a separate stock file.

The same principle applies for multi-brand stores and stores with a wholesale storefront – you should provide as much detail around how stock is going to be managed, differences in products available, different features required, different front-end experiences etc so the integrator can get a better idea of the complexity early on.

Extensions and integrations

If you’re already using Magento, I would recommend making a list of extensions that are providing functionality that you wish to take with you to the new store, you should ensure that they are listed here. I’d generally just go through the module list (sytem > config > developer > advanced > advanced) and create notes against each extension as to what it does and whether it needs to be moved over. This will need to apply for third party modules too as lots aren’t available for Magento 2 yet.

Additionally, if you have identified gaps in functionality and have already found an extension to bridge that gap, you should specify these in as much detail as possible. Bear in mind that the developers of some older extensions are taking the arrival of Magento 2 to retire those extensions completely and are phasing out support for them. If you currently use an extension which does not have a Magento 2.0 version, you will need to establish whether an alternative extension could supply the same functionality, whether a custom extension is required, or whether you could do without the functionality that is currently provided by the non-supported extension.

If you make use of extensions that integrate to third-party software or applications, you should list these here, as porting these to the new store could prove to be a major component of the build. Examples include integrations to your ERP, WMS or any other core third party system – systems could include Sage Accounting, Salesforce, SAP, Microsoft Dynamics or other applications. There are a number of third party connectors for things like SAP and Microsoft Dynamics that are available for Magento and aren’t yet ready for Magento 2, for example. You should also outline any middleware you plan to use or are using currently.

You should also provide a detailed outline of how the system integration works and what data is passed between the two platforms and when. It’s important that you let the integrator know which platform is going to act as the master and also how complex the integration needs to be (e.g. just using basic order management and inventory management vs managing all aspects of products in the ERP, managing returns and phone orders, multiple stock files etc). If you have a preference around how the integration is handled (e.g. middleware, flat files or via API) this should also be detailed.

Other considerations that need to be factored in here include:

  • Delivery – couriers, shipping options, international delivery, shipping calculations, third party services required etc
  • Tax – tax for different products (e.g. 0-rated or lower-rate products), different tax rates that need to be used etc
  • Internationalisation – any other requirements around internationalisation

There are obviously lots of other considerations, but these are some that I feel should definitely be included.



It’s clear to see that there is a lot to consider when starting to think about a Magento build project. As with any project, the more information you can provide to a supplier, the better they will be able to prepare an accurate and reliable quote for the project, both in terms of timescales and budgets. At this initial stage, it’s more important to define features and functionality at a high level than it is to drill down into too much detail, as that will come at a later stage, as the agency builds up a comprehensive picture of the project. Having said that, the more you can cover in this initial specification, the more likely it is that your project will get off to a strong start, and stay on track as the build progresses.

A good initial specification will also stand you in good stead as you meet with prospective partners, enabling you to fully brief the team and clarify any issues that might be raised.

If you have any questions around any of these areas or need help with an initial Magento discovery, please feel free to get in touch.