item_category
Collection: item_categories
An item category offers a way to give items additional behaviors that cannot be accomplished by item options alone, including item delivery types. When a store is first created, you will have a default item category with the code DEFAULT. This code cannot be deleted and will be the default for all items added to the cart if no category is specified.
Required Scopes
store_full_access item_categories_read item_categories_write Actions
Properties (26)
admin_email_template_uri String · Required The full API URI of the email template used by this category for sending an administrative email if send_admin_email is true.
Required if send_admin_email is true. Obtained from the self link relation of an email template.
customer_email_template_uri String · Required The full API URI of the email template used by this category for sending an additional customer email if send_customer_email is true.
Required if send_customer_email is true. Obtained from the self link relation of an email template.
gift_recipient_email_template_uri String (nullable) · Optional The full API URI of the email template used by this category for sending an additional customer email for gift items that are in the cart.
code String · Required · max 50 The category code used when applying this item category to the cart.
If DEFAULT then it cannot be modified.
name String · Required · max 50 The name of this category.
If code is DEFAULT then it cannot be modified.
item_delivery_type String · Required The delivery type of the items in this category.
Default: notshipped
shippeddownloadedflat_ratepickupnotshipped max_downloads_per_customer Number · Required Determines how many times the same customer can attempt to download a purchased downloadable item before they are given an error.
Required if item_delivery_type is downloaded.
Default: 3
max_downloads_time_period Number · Required Determines how long in hours after the initial purchase a customer can attempt to download a purchased downloadable item before they are given an error. Some helpful values include: 1 day = 24 hours, 1 Week = 168 hours, 1 Month = 672 hours, 6 Months = 4032 hours.
Required if item_delivery_type is downloaded.
Default: 24
customs_value Number · Optional The customs value that should be used for shipping services for items in this category.
Greater than or equal to 0.
default_weight Number · Required The default weight of an item in this category if no individual item weight is given.
Required if item_delivery_type is shipped.
Default: 1 pound
default_weight_unit String · Required The weight unit of measurement that will be sent to shipping services for items in this category.
Default: LBS
LBSKGS default_length_unit String · Required The length unit of measurement that will be sent to shipping services for items in this category.
Default: IN
INCM shipping_flat_rate Number · Required The amount to charge for flat rate shipping when the item_delivery_type is flat_rate.
Greater than or equal to 0.
shipping_flat_rate_type String · Required How to apply the flat rate shipping amount, either to the whole order or to each shipment in the order.
Required if item_delivery_type is flat_rate.
per_orderper_item handling_fee_type String · Required Specify a handling fee type if you want items in this category to have a handling fee added to their price.
Default: none
noneflat_per_orderflat_per_itemflat_percentflat_percent_with_minimum handling_fee Number · Required The handling fee amount for this category.
Required if handling_fee_type is not none. Greater than or equal to 0.
handling_fee_minimum Number · Required The minimum fee when calculating the flat fee per shipment OR % of order total with items in this category. Whichever is greater.
Required if handling_fee_type is flat_percent_with_minimum. Greater than or equal to 0.
handling_fee_percentage Number · Required The handling fee percentage used when the handling_fee_type includes a percentage.
Required if handling_fee_type is flat_percent_with_minimum or flat_percent. Greater than or equal to 0.
discount_type String If specified, the type of discount applied to this item category.
""quantity_amountquantity_percentageprice_amountprice_percentage discount_name String · Required · max 50 The name of this category discount.
Required if a discount_type is specified.
discount_details String · Required · max 200 This is the string that determines the tiers and amounts that make up your discount. For example, 2-.50|10-3|50-5 means between 2 and 9 is discounted by .5 per product, 10 and 49 by 3 per product and 50 and over by 5 per product. If you're doing a quantity discount, it will compare against the quantity of products in the order. If you're doing a price based discount, it will compare against the price of the products in the order.
Required if a discount_type is specified.
send_customer_email Boolean Set to true to send an email to the customer any time an item in this category is purchased. If you set this to true, you'll also need to specify a customer_email_template_uri.
send_admin_email Boolean Set to true to send an email to an administrator any time an item in this category is purchased. If you set this to true, you'll also need to specify an admin_email_template_uri.
admin_email String · Required Email address of the administrator you'd like to send an email to every time an item in this category is purchased.
Required if send_admin_email is set to true.
date_created String (nullable) · Read-only The date this resource was created.
date_modified String (nullable) · Read-only The date this resource was last modified.
Link Relations (8)
self This Item Category Only present when item_delivery_type is downloaded.
Only present when an admin email template is configured.
Only present when a customer email template is configured.
fx:gift_recipient_email_template GET Gift Recipient Email Template for this Item Category. Only present when a gift recipient email template is configured.
fx:item_category on coupon_item_category·fx:item_category on discount_detail·fx:item_category on downloadable·fx:item_category on gift_card_item_category·fx:item_category on item·fx:item_category on tax_item_category Example Representation
{
"_links": {
"curies": [
{
"name": "fx",
"href": "https://api.foxycart.com/rels/{rel}",
"templated": true
}
],
"self": {
"href": "https://api.foxycart.com/item_categories/123",
"title": "This Item Category"
},
"fx:store": {
"href": "https://api.foxycart.com/stores/456",
"title": "This Store"
},
"fx:email_templates": {
"href": "https://api.foxycart.com/stores/456/email_templates",
"title": "Email Templates for this store"
},
"fx:tax_item_categories": {
"href": "https://api.foxycart.com/item_categories/123/tax_item_categories",
"title": "Tax Item Category relationships"
}
},
"admin_email_template_uri": "",
"customer_email_template_uri": "",
"gift_recipient_email_template_uri": "https://api.foxycart.com/email_templates/12",
"code": "DEFAULT",
"name": "Default for all products",
"item_delivery_type": "notshipped",
"max_downloads_per_customer": 3,
"max_downloads_time_period": 24,
"customs_value": 0,
"default_weight": 1,
"default_weight_unit": "LBS",
"default_length_unit": "IN",
"shipping_flat_rate": 0,
"shipping_flat_rate_type": "per_order",
"handling_fee": 0,
"handling_fee_minimum": 0,
"handling_fee_type": "none",
"handling_fee_percentage": 0,
"discount_name": null,
"discount_type": null,
"discount_details": null,
"send_customer_email": false,
"send_admin_email": false,
"admin_email": null,
"date_created": "2012-10-31T14:12:39-0700",
"date_modified": "2012-10-31T14:12:39-0700"
}