This document provides an overview of the important elements to consider when embedding the Carrot store into a Wordpress website.
It will cover:
Key Technical Concepts
Installing the Embed
Multi-Location Stores and Recommended Site Structure
Analytics + Reporting
Maintenance + Support
Key Technical Concepts
The Carrot store is a Single Page Application, unlike Wordpress, which creates multi-page websites. On your website the Carrot store will exist physically only on one Wordpress page, but can serve different content to the user depending on how they interact with it. Because this is different from how Wordpress serves content, failing to follow all the configuration steps may break your installation.
Installing the Embed
This guide assumes that you would like to run your Carrot store embedded into an existing Wordpress website. If you would like to operate your store as a totally separate subdomain this is also possible. Contact us for details.
If you are adding Carrot to a website built with a system other than Wordpress please contact our team so we can assist you.
1. Create the store page in your website builder
If one doesn’t exist already, create a page where the store will be embedded. By default we assume the slug for this page will be /store (eg. mywebsite.com/store), but any other slug can be used.
💡 If using Wordpress The page cannot be set as the Wordpress homepage! If you have no other pages on the site you should make a placeholder homepage and then set up a redirect to send all traffic to the store page.
2. Add Carrot store Code Block
Wordpress
On this page, add an HTML code block, ensuring you cancel out any padding, margins, etc. The Carrot Store is designed to occupy the full width of the page.
💡 Don't additional content to the page where the Carrot store is embedded. It can cause unexpected UX impacts to the store, increase loading times, and result in layout bugs in the Carrot or on your website.
Paste the following into the code block
<div id="carrot-store">
<div id="carrot-store-root"></div>
</div> <script> CARROT_API_URL = "<https://api.nevada.getcarrot.io/api/v1>";
CARROT_SPACE_ID = **PUT_YOUR_SPACE_ID**;
</script>
<script src="<https://nevada-store-core.getcarrot.io/carrot.js>"></script>
Replace these properties with your store-specific settings
SPACE_ID> get your company space ID from the Carrot team
Disable Caching for the Store Embed Page
To ensure you are able to maintain proper operation during updates to the store, its necessary to disable caching for the store page. If you do not, then your site may try to serve an old version of the Carrot store after an update, causing the store to fail to load.
Ensure the Carrot.js file is never cached
When updates are made to the store this file will update, and if you’re site is trying to serve an old version of the file it will cause your embed to break.
We have taken all steps possible on our side to configure this file to eliminate caching, but it is possible for these configurations to be overriden if you have implemented aggressive caching on your site.
3. Configure Embedded Single Page App URLs
This is an essential final step for ensuring the correct function of your store. Problems here may mean users may see a 404 error page, or get redirected to the homepage when linked to pages inside your store (like a product page).
Instructions will vary depending on the platform used for your site.
Wordpress
Finish steps 1 and 2, ensuring that you can see your Carrot embedded on the intended page
Make note of the Wordpress page ID for the embedded store. It’s an integer number you can see in your browser URL when you’re editing the page in WP Admin.
Install Wordpress plugins:
Rewrite Rules Inspector https://wordpress.org/plugins/rewrite-rules-inspector/
Redirection https://redirection.me/
Code Snippets https://wordpress.org/plugins/code-snippets/
[Optional] If you want the homepage to redirect to your store page, open the Redirection plugin (WP Admin “Tools” -> “Redirection”) and add a redirect from
/with the option “ignore slash” to/store/(or whatever slug you picked for the page in step 4)Open the Code Snippets plugin (WP Admin “Code Snippets” and create a new PHP snippet with the following code:
function store_rewrite() { add_rewrite_rule( '^**PAGE_SLUG**/.+', 'index.php?page_id=**PAGE_ID**', 'top' ); } add_action( 'init', 'store_rewrite', 10 );Replace these properties
PAGE_IDwith your page ID from step 3PAGE_SLUGwith your slug from step 4.
Example:
function store_rewrite() { add_rewrite_rule( '^store/.+', 'index.php?page_id=1127', 'top' ); } add_action( 'init', 'store_rewrite', 10 );Don’t forget to switch PHP Inserter to “ON” at the top right and save your changes.
Go to the Rewrite Rules Inspector plugin (WP Admin “Tools” -> “Rewrite Rules”) and click “Flush Rules”
Flush as many caches as you can find in your Wordpress
Contact us to ensure that the slug for your embedded store page matches what we have configured in our settings (eg.
/store) This is required for the redirection settings to function correctly.
Multi-Location Operations
If your store has more than one location, we have some additional guidelines to ensure a clear experience for your customers. Below are two diagrams. One shows a typical single-location setup, the second shows the required setup for multi-location to function correctly on Carrot.
In both examples there is only one Carrot Store page, but you can always link to a specific location if there is more than one. Unlike other providers, Carrot has built-in features to handle navigation between your different locations.
Even if you have more than one location, you will only ever have a single page on your website with the Carrot store embedded in it.
Important Information:
Create a “Locations” page to use as the target for any calls to action like “Shop Now” not targeted to a specific location
For any links that should take customers to a specific location, simply target the main store page, but add an additional parameter
?locId=to tell Carrot which location should open(Examples: “/store?locId=1”, “/store/category/flower?locId=4”). This parameter can be added to any store path.
We will provide the location ID numbers of each store during the onboarding process.
Once a customer has signed in to the store once, Carrot will remember which store they last had open, to reduce the possibility of shopping at the wrong location.
Kiosk Mode
To add a kiosk display to your site follow the instructions here.