Product definition

This attribute is mandatory; it is your product's unique ID. If you are using a CMS like Wordpress or Umbraco, we suggest using the unique ID from your database. There are no constraints on Snipcart's side; you can use integers, GUID, strings, etc.

This attribute will also be used to locate the element when crawling your webpage, to make sure the amount the customer is about to pay is correct and hasn’t been altered.

This is another mandatory attribute; it simply is your product name. The product name will be displayed in the shopping cart and during the checkout process.

Another mandatory attribute: the item price. You must provide a decimal number. Do not format the number you provide in this attribute. Use a simple decimal with a dot (.) as a separator. Simply define the price regardless of the currency you're using. If you are using our multi-currency feature, please follow [this guide](/configuration/multi-currency) to define your prices correctly.

        
Valid price: 10000.50

        
Invalid price: 10 000,50$
    

This attribute is very important. It must be the URL where we will find your Buy button. To make sure the price has not been altered during the checkout process, we will crawl this URL and look for the Buy button. It must be on the source of the page and not added dynamically with JavaScript. **Important notice**: For users with a single-page website, the data-item-url field should be filled with only your basic domain name, such as www.example.com, or with a simple slash bar **/**.

Make sure that you configured your domains correctly in the dashboard (protocols and domains). Otherwise, you might encounter validation issues. Please refer to this section to understand how our validation process works.

Use this attribute if you want to provide a short description of your product that your customers will see in the cart and during checkout.

Use this if you want to provide your customers with a small thumbnail of your product in the cart. This must be an absolute URL. As this attribute is optional, if you do not provide it, no image will be displayed.

Please note that the format is 50x50 in our default template.

Use this option to specify the categories this product belongs to. You can specify multiple categories splitted by a comma. Example: data-item-categories="cat1, cat2, cat3"

This attribute is required only if you are using shipping rates from one of our supported shipping providers. Every provider requires the "package" weight to estimate the cost.

Please note that we are using grams as weight units.

Use this attribute to specify item *width*. The item dimensions will be used when using integrated shipping providers and will be sent to the Shipping Webhooks API if defined.

Please note that we are using centimeters as dimension unit and **this attribute is required to use Australia Post**.

Use this attribute to specify item *length*. The item dimensions will be used when using integrated shipping providers and will be sent to the Shipping Webhooks API if defined.

Please note that we are using centimeters as dimension unit and **this attribute is required to use Australia Post**.

Use this attribute to specify item *height*. The item dimensions will be used when using integrated shipping providers and will be sent to the Shipping Webhooks API if defined.

Please note that we are using centimeters as dimension unit and **this attribute is required to use Australia Post**.

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.

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.

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.

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.

When you set this attribute to false, the product will be flagged as an item that you do not ship. All shipping options will be removed from the cart if you only have non-shippable items in it. As soon as you add an item that is shippable, the shipping tab will show up.

Set this option to `false` when you want to exclude this particular item from the taxes calculation. The default value is `true`.

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 `|`. 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.

Set this flag to `true` if the taxes you defined are included in your product prices.

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"}'`.

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.

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`.

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.

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.

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`.

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.

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.