Big Cartel Theme API (2023)

Looking to customize a Big Cartel store or build a custom theme? You’re in the right place! Whether you’re just getting started or an experienced coder, we’ve got everything you need here to build a great theme and make your vision a reality: the basic anatomy of a theme, how our template language works, complete variable and filter documentation, and some sample code to get you on the right track.

A Big Cartel theme consists of 9 built-in pages and is made up of HTML, CSS, Javascript, and a combination of filters and variables. All changes to a store’s theme will need to be made in the Customize Design section of the admin, but if you’re a more advanced coder we’d love for you to check out Dugway to develop and test your theme locally.

Not a coder? If you’re looking for themes to install in your store, or general theme customization tips, check out our customization article »

Page	Description
`Layout`	The main store template.
`Cart`	Where customers can see the contents of their cart and proceed to the checkout.
`Contact`	A built in contact page.
`Home`	The store’s Home page.
`Maintenance`	The page visitors will see when a store is in Maintenance Mode.
`Product`	The individual product page.
`Products`	The page where visitors can see all products and categories.

The Layout page is the most important of all of these, and you can think of it as a master template that all store pages live inside. Any content that you need displayed throughout the entire store — a header, navigation, logo, etc will go in here. We also require that you include some important variables to make sure your store functions properly: {{ head_content }}, which goes inbetween the <head> HTML tags, and {{ page_content }} inside <body>. Here’s what that looks like inside a simple, stripped down HTML template:

{{ head_content }} loads important system code from our server, while {{ page_content }} will display the content for the current page being viewed - such as product details on the individual Product page.

You’ll also notice there’s a line in the above code to load a CSS file. We’ll take care of hosting your theme’s CSS, which can be edited in Customize Design > Advanced > CSS. You’ll then want to make sure you call this in the <head> HTML tags like the example above.

We don’t offer hosting for any separate javascript files though, so if your theme requires any javascript you’ll need to have load it from an external website or include it directly inside your page content.

If you’re building a new theme or doing a major overhaul to your existing theme, you should definitely check out Dugway. This fancy little tool allows you to build a Big Cartel theme (or run any of our default themes) locally on your computer, test it in any browser, and you can make changes to a theme using your favorite code editor. It also supports tools like CoffeeScript, Sass, and LESS. We’ve got more information on how to install Dugway and start creating a theme over at: github.com/bigcartel/dugway

Have a question about building a Big Cartel theme, how to use certain variables/filters, or stuck with a tricky coding issue? Head over to Stack Overflow – it’s a great question and answer site for programmers. Just be sure to include the bigcartel tag when asking a question to get answers from programmers and members of the Big Cartel team: http://stackoverflow.com/questions/tagged/bigcartel

Our theme template language consists of variables and filters. Variables are the individual pieces of data about different aspects of your store, like product details and cart information. Filters are simple methods to format or manipulate output, like capitalizing words or modifying the size of an image. We’ve provided complete documentation for filters and variables below.

If, Else, and Elsif

These tags show output for different conditions. The opposite of if is unless. You can use and and or to combine conditions.

Case Statement

These tags let you handle multiple conditions.

For Loops

These tags allow you to loop over collections, like a list of products or items in the cart.

Cycle

These tags let you alternate between a set of values. Commonly used to alternate between colors to zebra stripe rows.

Raw

You can disable tag processing by using the raw tag.

Variable Assignment

These tags let you store data in your own variables to be used in output or other tags. The easiest way is with the assign tag.

Variables are the individual pieces of data about different aspects of your store. You can use these variables in your code to display specific information. To use variables, wrap them in two curly brackets on either side.

Cart

Used to display information about the buyer’s cart.

Variable	Description
`cart.item_count`	Returns the number of items in the cart.
`cart.subtotal`	Returns the combined price for all items in your cart, before shipping, tax, or discounts.
`cart.total`	Returns the combined price, shipping, tax, and discounts for all items in your cart.
`cart.items`	Returns all of the items in your cart.

Cart Item

Used to display information on each item in the cart. Iterate through them with a for loop.

Variable	Description
`item.id`	Returns the id of an item.
`item.name`	Returns the name of an item. This is done by combining the name of the product and name of the option, unless it’s a default option.
`item.price`	Returns the price of an item multiplied by it’s quantity.
`item.unit_price`	Returns the price of for one of an item.
`item.shipping`	Returns the shipping amount of an item, if you’re using Big Cartel’s shipping features.
`item.total`	Returns the total price and shipping amount of an item.
`item.quantity`	Returns the quantity in the cart for an item.
`item.product`	Returns the product of an item.
`item.option`	Returns the option of an item.

Variable	Description
`category.id`	Returns the id of a category.
`category.name`	Returns the name of a category.
`category.permalink`	Returns the permalink of a category.
`category.url`	Returns the URL of a category.
`category.products`	Returns all of the products of a category.
`categories.all`	Returns all of the categories in your store.
`categories.active`	Returns all of the categories that are currently in use by one or more products.
`categories.permalink`	Returns a specific category based on it’s permalink.

Contact

Used on a store’s built-in Contact page to build your contact form, and display a message after the form is submitted.

Variable	Description
`contact.name`	Returns the name entered in the contact form.
`contact.email`	Returns the email address entered in the contact form.
`contact.subject`	Returns the subject entered in the contact form.
`contact.message`	Returns the message entered in the contact form.
`contact.captcha`	Returns a unique captcha to fight spam for the contact form. Note: deprecated in favor of contact.recaptcha
`contact.recaptcha`	Inserts javascript code for Google reCAPTCHA, CSS to hide the badge, and a required message indicating the contact form is protected by Google reCAPTCHA.
`contact.sent`	Returns true or false based on whether the the contact form was successfully sent.

Country

Used to retrieve information about countries from the Big Cartel shipping settings.

Variable	Description
`country.name`	Returns the name of a country.
`country.code`	Returns the code of a country.

Image

Used for retrieving information on theme or product images.

Variable	Description
`image.url`	Returns the URL of an image.
`image.width`	Returns the width of an image.
`image.height`	Returns the height of an image.

Page

Used for retrieving information on custom pages.

Variable	Description
`page.id`	Returns the id of a page.
`page.name`	Returns the name of a page.
`page.content`	Returns the content of a page.
`page.category`	Returns the type of page. “custom” or “theme”.
`page.permalink`	Returns the permalink of a page.
`page.url`	Returns the URL of a page.
`page.full_url`	Returns the absolute URL of a page.
`page.full_path`	Returns the path as well as any query parameters of the page.
`pages.all`	Returns all of the custom pages in your store.
`pages.permalink`	Returns a specific page based on it’s permalink.

Product

Used to retrieve all details on a given product.

(Video) BIG CARTEL HACKS

Variable	Description
`product.id`	Returns the id of a product.
`product.name`	Returns the name of a product.
`product.permalink`	Returns the permalink of a product.
`product.url`	Returns the URL of a product.
`product.edit_url`	Returns the URL to edit a product in the admin.
`product.position`	Returns the position of a product in your product list.
`product.description`	Returns the description of a product.
`product.status`	Returns the status of a product. “active”, “sold-out”, or “coming-soon”.
`product.created_at`	Returns the date the product was first created.
`product.categories`	Returns all of the categories of a product.
`product.css_class`	Returns the css_class of a product. “product”, “product sold”, “product soon”, or “product sale”.
`product.default_price`	Returns the default price of a product.
`product.variable_pricing`	Returns true if any option has a price that differs from the default price, false otherwise.
`product.min_price`	Returns the minimum price of a product and it’s options.
`product.max_price`	Returns the maximum price of a product and it’s options.
`product.on_sale`	Returns true or false based on whether the product is marked as on sale.
`product.has_default_option`	Returns true if the product has no custom options configured. False otherwise.
`product.has_option_groups`	Returns true if the product has option groups.
`product.option`	Returns the default option of a product.
`product.options`	Returns all of the options of a product whether they are sold out or not.
`product.options_in_stock`	Returns all of the options of a product that are in stock. If you’re not using Big Cartel’s inventory tracking, then this is the same as calling product.options.
`product.shipping`	Returns all of the shipping areas of a product.
`product.image`	Returns the default image of a product.
`product.images`	Returns all of the images of a product.
`product.image_count`	Returns the number of images a product has.
`product.previous_product`	Return the previous product in your list.
`product.next_product`	Return the next product in your list.
`products.all`	Returns all of the products in your store.
`products.current`	Returns all of the products for the current Products page.
`products.on_sale`	Returns all of the products in your store that are marked “on sale”.
`products.permalink`	Returns a specific product based on it’s permalink.

Product Option

Used for retrieving options that have been added to a given product.

Variable	Description
`option.id`	Returns the id of an option.
`option.name`	Returns the name of an option.
`option.price`	Returns the price of the product option, if set, or the price of the parent product.
`option.has_custom_price`	Returns true if this product option has a price set that’s different than the parent product, false otherwise.
`option.position`	Returns the position of an option in a product’s option list.
`option.sold`	Returns the number of times an option has been sold.
`option.sold_out`	Returns true or false based on whether the option is sold out. If you’re not using Big Cartel’s inventory tracking, then this is always true.
`option.quantity`	Returns the quantity left in stock for an option.
`option.inventory`	Returns the remaining inventory percentage of an option.
`option.default`	Returns true or false based on whether the option is the product’s default option.

Product Shipping Area

Used for retrieving information on shipping areas from the Big Cartel shipping settings.

Variable	Description
`area.name`	Returns the name of a shipping area. Must be used with the shipping_name filter.
`area.amount_alone`	Returns the shipped alone amount of a shipping area.
`area.amount_with_others`	Returns the with others amount of a shipping area.
`area.country`	Returns the country of a shipping area. Only applicable if you have country based shipping.

Store

Used for retrieving store information that’s set on the Settings page of your admin.

Variable	Description
`store.name`	Returns the name of your store.
`store.description`	Returns the description of your store.
`store.url`	Returns the URL of your store. This will use your custom domain if you have it setup.
`store.website`	Returns the URL of your store’s primary website.
`store.currency.name`	Returns the name of the currency used for your store.
`store.currency.code`	Returns the code of the currency used for your store.
`store.currency.sign`	Returns the sign of the currency used for your store.
`store.country`	Returns the country of your store.

Filters are simple methods to format or manipulate output. The first parameter is your starting value, and it runs from left to right through one or more filters separated by bars.

Parameters

Name	Type	Default	Description
`number_to_multiply`	integer	nil	Number to multiply.

divided_by

Divides a number by another number.

Parameters

Name	Type	Default	Description
`number_to_divide_by`	integer	nil	Number to divide by.

modulo

Calculates a remainder with division.

Parameters

Name	Type	Default	Description
`number_to_divide_by`	integer	nil	Number to divide by.

num_lt

Returns true or false if a number is less than the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

num_lte

Returns true or false if a number is less than or equal to the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

num_gt

Returns true or false if a number is greater than the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

(Video) Do NOT Use Aliexpress for Dropshipping (NEW 2023 Method)

num_gte

Returns true or false if a number is greater than or equal to the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

num_eq

Returns true or false if a number is equal the other.

Parameters

Name	Type	Default	Description
`number_to_compare`	integer	nil	Number to compare to.

money

Formats a number into money format.

Parameters

Name	Type	Default	Description
`format`	string	nil	Can be “sign”, “code”, or “sign_and_code”

(Video) Jae-P - Ni de aqui ni de alla (EXPLICIT)

Parameters

Name	Type	Default	Description
`string_to_find`	string	nil	The string to search for.
`replacement_string`	string	nil	The string to replace it with.

remove

Removes all occurrences of a given string.

Parameters

Name	Type	Default	Description
`string_to_remove`	string	nil	The string to remove.

remove_first

Same as remove, but only removes the first occurrence.

Parameters

Name	Type	Default	Description
`string_to_remove`	string	nil	The string to remove.

prepend

Adds a string to the beginning of another string.

Parameters

Name	Type	Default	Description
`string_to_prepend`	string	nil	The string to prepend.

append

Adds a string to the end of another string.

Parameters

Name	Type	Default	Description
`string_to_append`	string	nil	The string to append.

date

Formats a date.

Parameters

Name	Type	Default	Description
`format`	string	nil	The date format to use.

link_to

Creates a link to any page, product, or category.

Parameters

Name	Type	Default	Description
`text`	string	item’s name	The link’s text.
`title`	string	“View {{ item.name}}”	The link’s title attr.
`id`	string	nil	The link’s title attr.
`class`	string	nil	The link’s class attr.
`rel`	string	nil	The link’s rel attr.

(Video) The Best Way to Set up The Facebook Conversions API Yet! (Fast, Easy, Zero Coding)

product_image_url

Returns the URL of the specified product image and size. Pro-tip: instead of using the pre-made sizes, use the constrain filter for a custom image size.

Parameters

Name	Type	Default	Description
`size`	string	nil	Can be “thumb” (75x75), “medium” (175x175), “large” (300x300), or blank (1000x1000).

theme_js_url

Returns the URL of a JavaScript file used by a specific theme. Use this over calling the URLs directly.

Parameters

None.

theme_css_url

Returns the URL of your custom CSS StyleSheet.

Parameters

None.

theme_image_url

Returns the URL of an image file used by a specific theme. Use this instead of direct URLs.

Parameters

None.

constrain

Modifies the URL of any product or theme image to constrain the size to any width and/or height. When constraining an image using both width and height, the image is scaled down to the largest possible width and height that will fit the dimensions you provided while maintaing its aspect ratio.

Parameters

Name	Type	Default	Description
`width`	string	nil	The desired image width. Use “-“ to skip.
`height`	string	nil	The desired image height. Use “-“ or leave blank to skip.

Our JavaScript API returns variables in JSON format, allowing you to use Ajax requests to update/retrieve store data. Our API is 100% standalone and requires no other libraries.

Just drop the following line of code into your store’s HTML. Keep in mind that this code will only work in your store, and not any external websites.

Product.find

Returns a product based on the given permalink.

Parameters

Name	Type	Default	Description
`permalink`	string	null	The product permalink.
`callback`	function	null	Your callback function.

Product.findAll

Returns an array of all products.

Parameters

Name	Type	Default	Description
`params`	object	{}	Can contain `limit` count, `page` number, and `category` permalink.
`callback`	function	null	Your callback function.

Product.search

Returns an array of all products that match the specified search term. Most of the parameters from findAll will work as well.

Parameters

Name	Type	Default	Description
`term`	string	null	The search term.
`params`	object	{}	Can contain `limit` count, `page` number, and `category` permalink.
`callback`	function	null	Your callback function.

Product.findImage

Returns the URL of an image with the given size. Works just like the product_image_url filter.

Parameters

Name	Type	Default	Description
`url`	string	null	The image URL.
`size`	string	null	Can be “thumb” (75x75), “medium” (175x175), “large” (300x300), or blank (1000x1000).

Cart.refresh

Returns the current cart variable.

Parameters

Name	Type	Default	Description
`callback`	function	null	Your callback function.

Cart.updateFromForm

Submits a specific form ID to add, update, or remove items from the cart.

Parameters

Name	Type	Default	Description
`form_id`	string	null	The id of your form element.
`callback`	function	null	Your callback function.

Cart.addItem

Adds a particular option.id to the cart with the desired quantity (1 by default).

Parameters

Name	Type	Default	Description
`option_id`	string	null	The id of your option element.
`quantity`	integer	1	The number to add to the cart.
`callback`	function	null	Your callback function.

Cart.updateItem

Updates a particular item.id in the cart with the desired quantity.

Parameters

Name	Type	Default	Description
`option_id`	string	null	The id of your option element.
`quantity`	integer	1	The number to update the cart with.
`callback`	function	null	Your callback function.

Cart.removeItem

Removes a given item.id from the cart.

Parameters

Name	Type	Default	Description
`option_id`	string	null	The id of your option element.
`callback`	function	null	Your callback function.

Format.money

Formats a number into the proper format for a store’s currency, similar to the money filters. The sign and code will be wrapped in <span> tags.

Parameters

Name	Type	Default	Description
`number`	integer	null	The number to convert.
`with_delimiter`	boolean	false	Whether to include a delimiter.
`with_sign`	boolean	false	Whether to include a sign.
`with_code`	boolean	false	Whether to include a code.

Format.pluralize

Returns the singular version of a word if there is one, and the plural version otherwise.

Parameters

Name	Type	Default	Description
`count`	integer	nil	The number of items.
`singular`	string	nil	The singular name of the item.
`plural`	string	nil	The plural name of the item.

(Video) Garten of Banban - Official Trailer

Format.queryString

Returns a URL-encoded string containing the hash’s contents as query parameters.

Parameters

Name	Type	Default	Description
`params`	object	nil	The object to convert.

Big Cartel Theme API (2023)

Tags

If, Else, and Elsif

Case Statement

For Loops

Cycle

Raw

Variable Assignment

Cart

Cart Item

Category

Contact

Country

Image

Page

Product

Product Option

Product Shipping Area

Store

size

Parameters

join

Parameters

sort

Parameters

first

Parameters

last

Parameters

minus

Parameters

plus

Parameters

times

Parameters

divided_by

Parameters

modulo

Parameters

num_lt

Parameters

num_lte

Parameters

num_gt

Parameters

num_gte

Parameters

num_eq

Parameters

money

Parameters

money_with_sign

Parameters

money_with_code

Parameters

money_with_sign_and_code

Parameters

font_family

Parameters

default_pagination

Parameters

shipping_name

Parameters

hidden_option_input

Parameters

options_select

Parameters

options_radio

Parameters

product_quantity_input

Parameters

item_quantity_input

Parameters

contact_input

Parameters

downcase

Parameters

upcase

Parameters

capitalize