item_category : Foxy hAPI

item_categories

Description

This link relationship returns a collection of resources. You can easily paginate through this collection using the hypermedia links provided and the link relationships of first, prev, next, and last. Scroll down to view a representation of a single resource embedded within this collection.

Interact with this resource

To interact with this resource and see it in the context of the API, you can utilise Postman or your Terminal/Console to perform requests. If you have a Foxy store, you can also use the API browser in the admin to interact with resources connected to your store.

Actions

GET: View a list of item_categories
POST: Create a new item_category
HEAD: Get just the header response
OPTIONS: Get a response explaining which HTTP methods are supported

Example Representation

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "...",
      "title": "This Collection"
    },
    "first": {
      "href": "...?offset=0",
      "title": "First Page of this Collection"
    },
    "prev": {
      "href": "...?offset=0",
      "title": "Previous Page of this Collection"
    },
    "next": {
      "href": "...?offset=0",
      "title": "Next Page of this Collection"
    },
    "last": {
      "href": "...?offset=0",
      "title": "Last Page of this Collection"
    }
  },
  "_embedded": {
    "fx:item_categories": [...]
  },
  "total_items": "5",
  "returned_items": 5,
  "limit": 20,
  "offset": 0
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="...">
  <link rel="self" href="..." title="This Collection"/>
  <link rel="first" href="...?offset=0" title="First Page of this Collection"/>
  <link rel="prev" href="...?offset=0" title="Previous Page of this Collection"/>
  <link rel="next" href="...?offset=0" title="Next Page of this Collection"/>
  <link rel="last" href="...?offset=0" title="Last Page of this Collection"/>
  <resource href="..." rel="https://api.foxycart.com/rels/item_category">
  ...
  </resource>
  <total_items>5</total_items>
  <returned_items>5</returned_items>
  <limit>20</limit>
  <offset>0</offset>
</resource>

{
    "properties": {
        "total_items": "5",
        "returned_items": 5,
        "limit": 20,
        "offset": 0
    },
    "entities": [...],
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "..."
        },
        {
            "rel": [
                "first"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "prev"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "next"
            ],
            "href": "...?offset=0"
        },
        {
            "rel": [
                "last"
            ],
            "href": "...?offset=0"
        }
    ],
    "actions": [
    ]
}

Embedded Resource: item_category

Description

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 can not be deleted and will be the default for all items added to the cart if no category is specified.

Interact with this resource

Actions

GET: View a item_category
PATCH: Update a item_category (send only the properties you want to modify)
PUT: Replace a item_category (send the entire representation)
DELETE: Delete a item_category
HEAD: Get just the header response
OPTIONS: Get a response explaining which HTTP methods are supported

Properties

Property	Description	Type	Constraints
admin_email_template_uri	The full API URI of the email template used by this category for sending an administrative email if send_admin_email is true.	URL	Required if `send_admin_email` is true. Obtained from the self link relation of an email template.
customer_email_template_uri	The full API URI of the email template used by this category for sending an additional customer email if send_customer_email is true.	URL	Required if `send_customer_email` is true. Obtained from the self link relation of an email template.
gift_recipient_email_template_uri	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	URL	Optional
code	The category code used when applying this item category to the cart.	String	Required. 50 characters or less. If `DEFAULT` then it can not be modified.
name	The name of this category.	String	Required. 50 characters or less. If code is `DEFAULT` then it can not be modified.
item_delivery_type	The delivery type of the items in this category.	String	Required. `shipped`, `downloaded`, `flat_rate`, `pickup`, or `notshipped`. Defaults to `notshipped`.
max_downloads_per_customer	Determines how many times the same customer can attempt to download a purchased downloadable item before they are given an error.	Integer	Required if `item_delivery_type` is `downloaded`. Defaults to 3.
max_downloads_time_period	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	Integer	Required if `item_delivery_type` is `downloaded`. Defaults to 24.
customs_value	The customs value that should be used for shipping services for items in this category.	Decimal	Optional
default_weight	The default weight of an item in this category if no individual item weight is given.	Integer	Required if `item_delivery_type` is `shipped`. Defaults to 1 pound.
default_weight_unit	The weight unit of measurement that will be sent to shipping services for items in this category.	String	Required. LBS or KGS. Defaults to LBS.
default_length_unit	The length unit of measurement that will be sent to shipping services for items in this category.	String	Required. IN or CM. Defaults to IN.
shipping_flat_rate	The amount to charge for flat rate shipping when the `item_delivery_type` is `flat_rate`.	Decimal	Required. Greater than or equal to 0.
shipping_flat_rate_type	How to apply the flat rate shipping amount, either to the whole order or to each shipment in the order.	String	Required if `item_delivery_type` is `flat_rate`. `per_order` or `per_shipment`.
handling_fee_type	Specify a handling fee type if you want items in this category to have a handling fee added to their price.	String	Required. `none`, `flat_per_order`, `flat_per_item`, `flat_percent`, or `flat_percent_with_minimum`, defaults to `none`.
handling_fee	The handling fee amount for this category.	Decimal	Required if `handling_fee_type` is not `none`. Greater than or equal to 0.
handling_fee_minimum	The minimum fee when calculating the flat fee per shipment OR % of order total with items in this category. Whichever is greater.	Decimal	Required if `handling_fee_type` is `flat_percent_with_minimum`. Greater than or equal to 0.
handling_fee_percentage	The handling fee percentage used when the `handling_fee_type` includes a percentage.	Decimal	Required if `handling_fee_type` is `flat_percent_with_minimum` or `flat_percent`. Greater than or equal to 0.
discount_type	If specified, the type of discount applied to this item category.	String	Optional. If specified: `quantity_amount`, `quantity_percentage`, `price_amount`, or `price_percentage`.
discount_name	The name of this category discount.	String	Required if a `discount_type` is specified. 50 characters or less.
discount_details	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. Please see the documentation for more information: Coupons and Discounts	String	Required if a `discount_type` is specified. 200 characters or less.
send_customer_email	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`	Boolean	Optional
send_admin_email	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 a `admin_email_template_uri`	Boolean	Optional
admin_email	Email address of the administrator you'd like to send an email to every time an item in this category is purchased.	Email	Required if `send_admin_email` is set to true.
date_created	The date this resource was created.	Date	Read only
date_modified	The date this resource was last modified.	Date	Read only

Example Representation

{
  "_links": {
    "curies": [
      {
        "name": "fx",
        "href": "https://api.foxycart.com/rels/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://api-sandbox.foxycart.com/item_categories/13",
      "title": "DEFAULT"
    },
    "fx:store": {
      "href": "https://api-sandbox.foxycart.com/stores/8",
      "title": "This Store"
    },
    "fx:email_templates": {
      "href": "https://api-sandbox.foxycart.com/stores/8/email_templates",
      "title": "Email Templates for this store"
    },
    "fx:tax_item_categories": {
      "href": "https://api-sandbox.foxycart.com/item_categories/13/tax_item_categories",
      "title": "Tax Item Category relationships"
    },
    "fx:gift_recipient_email_template": {
      "href": "https://api.foxycart.com/email_templates/12",
      "title": "Gift Recipient Email Template for this Item Category"
    },
  },
  "admin_email_template_uri": "",
  "customer_email_template_uri": "",
  "gift_recipient_email_template_uri": "https://api.foxycart.test/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"
}

<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api-sandbox.foxycart.com/item_categories/13" rel="https://api.foxycart.com/rels/item_category">
  <link rel="self" href="https://api-sandbox.foxycart.com/item_categories/13" title="DEFAULT"/>
  <link rel="https://api.foxycart.com/rels/store" href="https://api-sandbox.foxycart.com/stores/8" title="This Store"/>
  <link rel="https://api.foxycart.com/rels/email_templates" href="https://api-sandbox.foxycart.com/stores/8/email_templates" title="Email Templates for this store"/>
  <link rel="https://api.foxycart.com/rels/tax_item_categories" href="https://api-sandbox.foxycart.com/item_categories/13/tax_item_categories" title="Tax Item Category relationships"/>
  <admin_email_template_uri></admin_email_template_uri>
  <customer_email_template_uri></customer_email_template_uri>
  <code>DEFAULT</code>
  <name>Default for all products</name>
  <item_delivery_type>notshipped</item_delivery_type>
  <max_downloads_per_customer>3</max_downloads_per_customer>
  <max_downloads_time_period>24</max_downloads_time_period>
  <customs_value>0</customs_value>
  <default_weight>1</default_weight>
  <default_weight_unit>LBS</default_weight_unit>
  <default_length_unit>IN</default_length_unit>
  <shipping_flat_rate>0</shipping_flat_rate>
  <shipping_flat_rate_type>per_order</shipping_flat_rate_type>
  <handling_fee>0</handling_fee>
  <handling_fee_minimum>0</handling_fee_minimum>
  <handling_fee_type>none</handling_fee_type>
  <handling_fee_percentage>0</handling_fee_percentage>
  <discount_name></discount_name>
  <discount_type></discount_type>
  <discount_details></discount_details>
  <send_customer_email>false</send_customer_email>
  <send_admin_email>false</send_admin_email>
  <admin_email></admin_email>
  <date_created>2012-10-31T14:12:39-0700</date_created>
  <date_modified>2012-10-31T14:12:39-0700</date_modified>
</resource>

{
    "class": [
        "item_category"
    ],
    "properties": {
        "admin_email_template_uri": "",
        "customer_email_template_uri": "",
        "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"
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api-sandbox.foxycart.com/item_categories/13"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/store"
            ],
            "href": "https://api-sandbox.foxycart.com/stores/8"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/email_templates"
            ],
            "href": "https://api-sandbox.foxycart.com/stores/8/email_templates"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/tax_item_categories"
            ],
            "href": "https://api-sandbox.foxycart.com/item_categories/13/tax_item_categories"
        }
    ]
}

Zoomable Resources

This resource has no linked resources which can be "zoomed" in on, filtered and embedded within this resource.