Products

Adding products on your site with Snipcart is simple. Products are defined by adding attributes to HTML elements on your site.

Developers often use a "buy" <button> element, which they define with attributes like product name, price, description, etc.

However, note that any HTML element can become a Snipcart product.

The first step when defining a product is to add the snipcart-add-item class to your element. This informs Snipcart it should react at that element's click event.

Here's an example:

<button class="snipcart-add-item"
  data-item-id="starry-night"
  data-item-price="79.99"
  data-item-url="/paintings/starry-night"
  data-item-description="High-quality replica of The Starry Night by the Dutch post-impressionist painter Vincent van Gogh."
  data-item-image="/assets/images/starry-night.jpg"
  data-item-name="The Starry Night">
  Add to cart
</button>

So what do we have above? First, we have Snipcart's mandatory product attributes:

Name Description Attribute Type Required
Name The name of the product data-item-name string true
ID The unique ID of the product data-item-id string true
Price The price of the product. Note that you must use a . as decimal separator. data-item-price number true
URL The URL of the product, this must be the URL where the buy button will be located. This will be used by our crawler when we'll validate order integrity. data-item-url string true
Description The short description of the product data-item-description string false
Image The URL of the product image. You should avoid linking a very large image and try to use an optimized one. data-item-image string false

data-item-id and data-item-url are especially important. The value that is specified in the data-item-url property will be used for order validation. Before confirming the order, our server will send an HTTP request to this URL and will scan the HTML output returned by your application. Our crawler will look for an HTML element with the snipcart-add-item CSS class and the ID specified with data-item-id.

You'll find the complete attributes reference right here.

If you have more than one product with the same ID, they must all have the same price, otherwise, the validation will fail. If you have multiple products with different prices, make sure they all have their own unique ID.

Custom fields

Products often come in different shapes, sizes and colors. We call these product options custom fields.

We support two different types of custom fields:

This one is handy when you have a predefined list of options to represent a product variation. Here's our example again:

<button class="snipcart-add-item"
  data-item-id="starry-night"
  data-item-price="79.99"
  data-item-url="/paintings/starry-night"
  data-item-description="High-quality replica of The Starry Night by the Dutch post-impressionist painter Vincent van Gogh."
  data-item-image="/assets/images/starry-night.jpg"
  data-item-name="The Starry Night"
  data-item-custom1-name="Frame color"
  data-item-custom1-options="Black|Brown|Gold">
  Add to cart
</button>

Above, the product now has an option called "Frame color" with variants "Black", "Brown", and "Gold".

Important: each option must be separated by a | in your attribute value.

This will look like this in the cart:

Snipcart product with dropdown custom fields

An interesting thing with this custom field type is having price modifiers per variant. Let's say that the price depends on the "Frame color" of the item; you could do something like this:

<button class="snipcart-add-item"
  data-item-id="starry-night"
  data-item-price="79.99"
  data-item-url="/paintings/starry-night"
  data-item-description="High-quality replica of The Starry Night by the Dutch post-impressionist painter Vincent van Gogh."
  data-item-image="/assets/images/starry-night.jpg"
  data-item-name="The Starry Night"
  data-item-custom1-name="Frame color"
  data-item-custom1-options="Black|Brown[+100.00]|Gold[+300.00]">
  Add to cart
</button>

Snipcart product with custom field price modifiers

Standard text box

This adds a standard text box to the product custom fields. It is the default custom field type. If you add a custom field without specifying its type or options, this is what will be rendered.

Let's see our example again:

<button class="snipcart-add-item"
  data-item-id="starry-night"
  data-item-price="79.99"
  data-item-url="/paintings/starry-night"
  data-item-description="High-quality replica of The Starry Night by the Dutch post-impressionist painter Vincent van Gogh."
  data-item-image="/assets/images/starry-night.jpg"
  data-item-name="The Starry Night"
  data-item-custom1-name="Gift note">
  Add to cart
</button>

Above, the product now has an option called "Gift note" that lets customers write a personalized gift note in the text box area.

Snipcart product with standard custom field

Combined custom fields

It's also possible to have multiple custom fields on a product.

<button class="snipcart-add-item"
  data-item-id="starry-night"
  data-item-price="79.99"
  data-item-url="/paintings/starry-night"
  data-item-description="High-quality replica of The Starry Night by the Dutch post-impressionist painter Vincent van Gogh."
  data-item-image="/assets/images/starry-night.jpg"
  data-item-name="The Starry Night"
  data-item-custom1-name="Frame color"
  data-item-custom1-options="Black|Brown|Gold"
  data-item-custom2-name="Gift note">
  Add to cart
</button>

Snipcart product with multiple custom fields

Whenever you add a new custom field, increment the index specified in the attribute: data-item-custom1-name, data-item-custom2-name, data-item-custom3-name, [...].

Other product attributes

We also support many other useful attributes when your products are more complex. Please note that none of them are required.

Product information

These attributes make it possible to define useful information about the product.

Name Description Attribute Type
Categories The categories that the product belongs to, each category must be splitted by a ,. Example: data-item-categories="cat1, cat2, cat3". data-item-categories string[]
Metadata Using this option, you can define metadata on the item. The value must be a valid JSON object. Example usage: data-item-metadata='{"key": "value"}'. data-item-metadata object

Product dimensions

If you need to offer different shipping prices depending on the order content, these attributes will be helpful.

Name Description Attribute Type
Weight The weight in grams of the product. Can be useful when you want to offer different shipping price depending on the weight of the order. This is also mandatory if you use any integrated shipping provider we support. data-item-weight number
Length The length in centimeters of the product. The product dimensions will be used if you enabled an integrated shipping provider. data-item-length number
Height The height in centimeters of the product. The product dimensions will be used if you enabled an integrated shipping provider. data-item-height number
Width The width in centimeters of the product. The product dimensions will be used if you enabled an integrated shipping provider. data-item-width number

Product quantity

These attributes make it possible to change how the quantity can be updated.

Name Description Attribute Type
Max quantity Use this attribute if you want to set a maximum allowed quantity of your product. For example, if you set it to 5, your customers will not be able to add more than 5 occurrences of your product in their cart. This comes in handy if you have limited stocks of a product or if you wish to limit the quantity per customer. A good practice would be to set it to the quantity you have available in your inventory. data-item-max-quantity number
Min quantity Use this attribute if you want to set the minimum allowed quantity for your product. For instance, let's say you set this attribute to 3 for your product A. When your customer adds product A to his cart for the first time, the quantity will be automatically set to 3, not 1. Once in the cart, the product's quantity will increase and decrease by one as usual when using the - & + signs. However, if you decrease its quantity lower than the minimal allowed quantity set, the product will be removed from the cart. Here, for instance, if you were to decrease product A's quantity in-cart under 3, product A would disappear from the cart. data-item-min-quantity number
Stackable When you set this attribute to false, adding the same product to the cart will result in two distinct items in the cart, instead of simply increasing the quantity. For instance, when your customers click twice on the same Buy button, they will have two entries of the product in their cart, instead of having a quantity of 2 for the same product. This is useful when you have a product with specific custom fields requiring different information for each occurrence. For instance, if you’re allowing your customer to engrave a message on your product, this will allow them to specify a different message for every item. When not defined, this property is considered to be true by default. data-item-stackable boolean
Quantity step By default the quantity of an item increments by 1. Use this attribute if you want to override it. For instance, if you set it to 2, the quantity will increment from 2 to 4 to 6. data-item-quantity-step number

Product taxes

Taxes can be complicated, some products can be taxable, others not, and some might have taxes already included in the price. We have a couple of attributes to deal with such scenarios.

Name Description Attribute Type
Taxable Set this option to false when you want to exclude this particular item from the taxes calculation. The default value is true. data-item-taxable boolean
Taxes Using this option, you can define which taxes will be applied on this particular item. It might be useful when you have some products that are exempted from a specific tax. The usage is data-item-taxes="TPS|TVQ". Each taxes are separated by a pipe |. The value must be the same name that is defined in the dashboard. You can also use the unique ID that is generated by your tax rule, available in the URL when editing a tax in the dashboard. Note that the unique IDs will not be the same in Live and Test modes. data-item-taxes string[]
Has taxes included Set this flag to true if the taxes you defined are included in your product prices. data-item-has-taxes-included boolean

Digital goods

You can link a digital good uploaded in our dashboard to the product.

Name Description Attribute Type
File GUID Use this attribute if your product is related to a digital good uploaded via our dashboard. You will find the file GUID in the dashboard once the digital good is created. data-item-file-guid uniqueidentifier

Subscriptions and recurring payments

We also support subscriptions and recurring payments. We have attributes required to specify that a product is a subscription.

Name Description Attribute Type
Payment interval Use this attribute if the item is a subscription plan, you can set the frequency of the payments using it. Possible values are: Day, Week, Month or Year. data-item-payment-interval enum
Payment interval count When defining a subscription plan, you can use this attribute to set the interval count, for instance, if data-item-payment-interval="Month" and data-item-payment-interval-count="2", a payment will be taken every 2 months. data-item-payment-interval-count number
Payment trial Use this attribute if you want to offer a trial period to the customers purchasing the subscription plan. The value specified is the number of days the trial will last. data-item-payment-trial number
Recurring shipping If you are selling a subscription plan and have shipping costs but you don't want to charge these fees on every invoice, only on the first, then set it to false. By default, this value is true. data-item-recurring-shipping boolean
Cancellation action When defining a subscription plan, you can specify the behaviour upon cancellation. By default, the subscription gets cancelled immediately, and no refunds are sent out. Adding the PartialRefundLastPayment attribute will give a refund for the unused period of the subscription. CancelAtCurrentCycleEnd will terminate the subscription at the end of the current billing cycle. When not defined, this property is considered to be None by default. data-item-cancellation-action enum
Pausing action When defining a subscription plan, you can determine the behaviour when pausing a subscription. By default, pausing a subscription will prevent any further payments and the user can resume at any given time without affecting the billing cycle. By adding the KeepActiveUntilEndOfBillingCycle attribute, the subscription will stay active and get paused at the end of its current billing cycle. PauseAndRealignBillingCycleOnResume will pause the billing cycle immediately, and realign the billing cycle on resume depending on how much unused time there was left at pause. When not defined, this property is considered to be None by default. data-item-pausing-action enum