item

Description

An item is a product added to a cart or contained in a transaction. Items that are part of a transaction can not be modified. Cart items, however, can be modified.

Sandbox Example

You can interact with this resource and run actions against the sandbox API via our HAL Brower.

Actions

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

Properties

Property Description Type Constraints
item_category_uri The full API URI of the item category associated with this item. URL Obtained from the self link relation of an item_category.
name The name of this item. String Required. 255 characters or less.
price The price of this item. This represents the base price of the item before any item option modifiers. Decimal Required
quantity The number of items in the cart or transaction. When adding products to the cart, if all properties are identical, the quantity will be incremented accordingly. Integer Optional. Defaults to 1.
quantity_min Minimum quantity that should be allowed per product, per cart. If the quantity is less than this, the quantity will be updated automatically to this number. Integer Optional
quantity_max Maximum quantity that should be allowed per product, per cart. If the quantity is more than this, the quantity will be updated automatically to this amount. Integer Optional
weight This item's per-item weight, used for shipping rate requests. Decimal Optional
code Item code. Can be used however you would like (internal use, product SKU, etc.). String Optional. 200 characters or less.
parent_code Parent item code. Used if this should be a child product in a bundle. String Optional. 200 characters or less.
discount_name The name of the line item discount if it is included on this item. String Optional. 50 characters or less.
discount_type The type of the line item discount if this item has a discount. String Required if discount_name is set. Either quantity_amount, quantity_percentage, price_amount, or price_percentage.
discount_details The details of the line item discount if this item has a discount. See the cart documentation for details on how this value should be formatted. String Required if discount_name is set. 200 characters or less.
subscription_frequency This determines how often this subscription will be processed. The format is a number followed by a date type such as d (day), w (week), m (month), or y (year). You can also use .5m for twice a month. To modify this value for an existing subscription, you must modify the subscription directly. String Optional. Read only if connected to an existing subscription.
subscription_start_date The original date this subscription began or will begin if set in the future. To modify this value for an existing subscription, you must modify the subscription directly. Date Optional. YYYY-MM-DD format. Read only if connected to an existing subscription.
subscription_next_transaction_date The date for when this subscription will run again. To modify this value for an existing subscription, you must modify the subscription directly. Date Must be in the future. YYYY-MM-DD format. Read only if connected to an existing subscription.
subscription_end_date If set, the date this subscription will end. The subscription will not run on this day. Date Must be in the future. YYYY-MM-DD format. Read only if connected to an existing subscription.
is_future_line_item If this item is part of a future subscription (or a subscription originally set up to start in the future), this will be set to true. Boolean Read only
shipto Used for multiship to assign this item to a specific shipment. This value will be the address name of the shipment. String Optional. 100 characters or less.
url The full item url for the customer to view this item online. URL Optional. 200 characters or less.
image The full image url for the customer to view an image of this item online. URL Optional. 200 characters or less.
length The length of this item. This is currently a place holder for future use. Integer Optional
width The width of this item. This is currently a place holder for future use. Integer Optional
height The width of this item. This is currently a place holder for future use. Integer Optional
expires As a unix timestamp, this is the point in the future when this item will no longer be valid and will be removed from the cart. Timestamp Optional. If supplied, must be in the future.
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/items/5616394",
            "title": "This Item"
        },
        "fx:store": {
            "href": "https://api-sandbox.foxycart.com/stores/66",
            "title": "This Store"
        },
        "fx:transaction": {
            "href": "https://api-sandbox.foxycart.com/transactions/3844264",
            "title": "This Transaction"
        },
        "fx:item_category": {
            "href": "https://api-sandbox.foxycart.com/item_categories/60",
            "title": "This Item Category"
        },
        "fx:item_options": {
            "href": "https://api-sandbox.foxycart.com/items/5616394/item_options",
            "title": "Item Options for This Item"
        },
        "fx:shipment": {
            "href": "https://api-sandbox.foxycart.com/shipments/3978",
            "title": "Shipment for this Item"
        }
    },
    "item_category_uri": "https://api-sandbox.foxycart.com/item_categories/60",
    "name": "basic",
    "price": 10,
    "quantity": 1,
    "quantity_min": 0,
    "quantity_max": 0,
    "weight": 5,
    "code": "",
    "parent_code": "",
    "discount_name": "",
    "discount_type": "",
    "discount_details": "",
    "subscription_frequency": "",
    "subscription_start_date": null,
    "subscription_next_transaction_date": null,
    "subscription_end_date": null,
    "is_future_line_item": false,
    "shipto": "Me",
    "url": "",
    "image": "",
    "length": 0,
    "width": 0,
    "height": 0,
    "expires": 0,
    "date_created": null,
    "date_modified": "2015-04-15T08:45:49-0700"
}
<?xml version="1.0" encoding="UTF-8"?>
<resource href="https://api-sandbox.foxycart.com/items/5616394" rel="https://api.foxycart.com/rels/item">
  <link rel="self" href="https://api-sandbox.foxycart.com/items/5616394" title="This Item"/>
  <link rel="https://api.foxycart.com/rels/store" href="https://api-sandbox.foxycart.com/stores/66" title="This Store"/>
  <link rel="https://api.foxycart.com/rels/transaction" href="https://api-sandbox.foxycart.com/transactions/3844264" title="This Transaction"/>
  <link rel="https://api.foxycart.com/rels/item_category" href="https://api-sandbox.foxycart.com/item_categories/60" title="This Item Category"/>
  <link rel="https://api.foxycart.com/rels/item_options" href="https://api-sandbox.foxycart.com/items/5616394/item_options" title="Item Options for This Item"/>
  <link rel="https://api.foxycart.com/rels/shipment" href="https://api-sandbox.foxycart.com/shipments/3978" title="Shipment for this Item"/>
  <item_category_uri>https://api-sandbox.foxycart.com/item_categories/60</item_category_uri>
  <name>basic</name>
  <price>10</price>
  <quantity>1</quantity>
  <quantity_min>0</quantity_min>
  <quantity_max>0</quantity_max>
  <weight>5</weight>
  <code></code>
  <parent_code></parent_code>
  <discount_name></discount_name>
  <discount_type></discount_type>
  <discount_details></discount_details>
  <subscription_frequency></subscription_frequency>
  <subscription_start_date></subscription_start_date>
  <subscription_next_transaction_date></subscription_next_transaction_date>
  <subscription_end_date></subscription_end_date>
  <is_future_line_item>false</is_future_line_item>
  <shipto>Me</shipto>
  <url></url>
  <image></image>
  <length>0</length>
  <width>0</width>
  <height>0</height>
  <expires>0</expires>
  <date_created></date_created>
  <date_modified>2015-04-15T08:45:49-0700</date_modified>
</resource>
{
    "class": [
        "item"
    ],
    "properties": {
        "item_category_uri": "https://api-sandbox.foxycart.com/item_categories/60",
        "name": "basic",
        "price": 10,
        "quantity": 1,
        "quantity_min": 0,
        "quantity_max": 0,
        "weight": 5,
        "code": "",
        "parent_code": "",
        "discount_name": "",
        "discount_type": "",
        "discount_details": "",
        "subscription_frequency": "",
        "subscription_start_date": null,
        "subscription_next_transaction_date": null,
        "subscription_end_date": null,
        "is_future_line_item": false,
        "shipto": "Me",
        "url": "",
        "image": "",
        "length": 0,
        "width": 0,
        "height": 0,
        "expires": 0,
        "date_created": null,
        "date_modified": "2015-04-15T08:45:49-0700"
    },
    "links": [
        {
            "rel": [
                "self"
            ],
            "href": "https://api-sandbox.foxycart.com/items/5616394"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/store"
            ],
            "href": "https://api-sandbox.foxycart.com/stores/66"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/transaction"
            ],
            "href": "https://api-sandbox.foxycart.com/transactions/3844264"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/item_category"
            ],
            "href": "https://api-sandbox.foxycart.com/item_categories/60"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/item_options"
            ],
            "href": "https://api-sandbox.foxycart.com/items/5616394/item_options"
        },
        {
            "rel": [
                "https://api.foxycart.com/rels/shipment"
            ],
            "href": "https://api-sandbox.foxycart.com/shipments/3978"
        }
    ]
}

Zoomable Resources

The following related resources can be embedded within this resource by including a ?zoom=<child_resource> parameter. You can also filter by child resources by ?child_resource:property=<property_value>

item_options
item_category