items
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 items
- POST
- Create a new item
- 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:items": [...]
},
"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"> ... </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
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.
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 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"
},
"fx:attributes": {
"href": "https://api-sandbox.foxycart.com/items/5616394/attributes",
"title": "Attributes for This Item"
},
"fx:discount_details": {
"href": "https://api-sandbox.foxycart.com/items/5616394/discount_details",
"title": "The Discounts for this Item"
},
"fx:coupon_details": {
"href": "https://api-sandbox.foxycart.com/items/5616394/coupon_details",
"title": "The Coupons for this Item"
},
"fx:provisioned_gift_card_code": {
"href": "https://api.foxycart.com/gift_card_codes/51",
"title": "The Gift Card Code 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"/> <link rel="https://api.foxycart.com/rels/attributes" href="https://api-sandbox.foxycart.com/items/5616394/attributes" title="Attributes for This Item"/> <link rel="https://api.foxycart.com/rels/discount_details" href="https://api-sandbox.foxycart.com/items/5616394/discount_details" title="The Discounts for this Item"/> <link rel="https://api.foxycart.com/rels/coupon_details" href="https://api-sandbox.foxycart.com/items/5616394/coupon_details" title="The Coupons 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"
},
{
"rel": [
"https://api.foxycart.com/rels/attributes"
],
"href": "https://api-sandbox.foxycart.com/items/5616394/attributes"
},
{
"rel": [
"https://api.foxycart.com/rels/discount_details"
],
"href": "https://api-sandbox.foxycart.com/items/5616394/discount_details"
},
{
"rel": [
"https://api.foxycart.com/rels/coupon_details"
],
"href": "https://api-sandbox.foxycart.com/items/5616394/coupon_details"
}
]
}
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>
coupon_details
discount_details
item_options
item_category
gift_card_codes