Resource

https://api.warehousefs.com/public/v1/item-groups/{merchantCode}/{groupMerchantIdentifier}/items/{itemMerchantIdentifier}

The items resource allows the merchant to programmatically enter catalog information into the Shipvine Logistics system. In Shipvine's vocabulary, an item is the individual stock-keeping unit (SKU) that is shipped. All of these items belong to one (and only one) item group. An item group can have zero or more items within it and it defines some common information about the items that it contains: name, country of origin, harmonized code, etc.

For example, let's say that you're selling a t-shirt that has an image of a surfer printed on it, but the t-shirt comes in four different sizes and four different fabric colors. You'd define one item group named "Surfer T-Shirt" and then put 16 items within it (for variations such as Red/Small, Red/Medium, Blue/Small, etc.).

PUT

Request

URL Template

The {merchantCode} field in the URL template should be replaced with the merchant code for the merchant that the item belongs to.

The {groupMerchantIdentifier} field in the URL should contain the merchant's identifier for the item group that contains the item.

The {itemMerchantIdentifier} field in the URL should contain the merchant's identifier for the item. This is the most important value because this value is used in many other APIs.

Example Request URL

https://api.warehousefs.com/public/v1/item-groups/CONTOSO/SURFER/items/SURFER-RED-S

Query Parameters

No query parameters may be included in the request.

Entity Body

The entity body is an XML document that represents the item. If the item exists, it is updated with the information specified in the XML document.

Example Request Entity Body

<?xml version="1.0"?> <!-- (1) -->
<Item>
  <Weight> <!-- (2) -->
    <Magnitude>0.25</Magnitude>
    <Unit>Pounds</Unit>
  </Weight>
  <Variations> <!-- (3) -->
    <Variation>
      <Type>Size</Type>
      <Value>Small</Value>
    </Variation>
    <Variation>
      <Type>Color</Type>
      <Value>Red</Value>
    </Variation>
  </Variations>
  <Barcodes> <!-- (4) -->
    <Barcode>1234567890</Barcode>
  </Barcodes>
</Item>

1. Older Shipvine Logistics API resources require a particular XML namespace declaration here, but this resource does not use a namespace.
2. The weight, in Pounds, must be specified as a value greater than zero.
3. Optionally, you can include any number of variations that help distinguish this item from other items that may be present in the item group. These values are displayed on requested documentation and reports.
4. Optionally, you can include the values of barcodes (such as UPCs or EANs) that are on the product packaging. Shipvine uses barcodes during the fulfillment process. The barcode must be unique among all items within your merchant account. If the item already exists and has a positive quantity on hand, then the <Barcodes /> element must be omitted completely; including it in this case will return an error. In other words, barcodes may only be changed when the quantity on hand is zero.

Response

If successful, the API will return 200 OK and an empty entity body.

If any error occurs, the HTTP status code will not be 200 OK. An <Errors /> element may be present in the entity body.

GET

Request

URL Template

The {merchantCode} field in the URL template should be replaced with the merchant code for the merchant that the item belongs to.

The {groupMerchantIdentifier} field in the URL should contain the merchant's identifier for the item group to which the item belongs.

The {itemMerchantIdentifier} field in the URL should contain the merchant's identifier for the item.

Example Request URL

https://api.warehousefs.com/public/v1/item-groups/CONTOSO/SURFER/items/SURFER-RED-S

Query Parameters

No query parameters may be included in the request.

Entity Body

No entity body may be included in the request.

Response

If successful, the API will return 200 OK and an entity body containing an XML document that represents the item.

If any error occurs, the HTTP status code will not be 200 OK; for example, if the item can't be found, then a 404 Not Found error is returned. An <Errors /> element may be present in the entity body.

Example Response Entity Body

<?xml version="1.0" encoding="utf-8"?>
<Item>
  <ItemGroup>
    <MerchantIdentifier>SURFER</MerchantIdentifier>
    <Name>Surfer T-Shirt</Name>
  </ItemGroup>
  <MerchantIdentifier>SURFER-RED-M</MerchantIdentifier>
  <Weight>
    <Magnitude>0.3</Magnitude>
    <Units>Pounds</Units>
  </Weight>
  <Variations>
    <Variation>
      <Type>Size</Type>
      <Value>Medium</Value>
    </Variation>
    <Variation>
      <Type>Color</Type>
      <Value>Red</Value>
    </Variation>
  </Variations>
  <Barcodes>
    <Barcode>1234567890</Barcode>
  </Barcodes>
  <Inventory> <!-- (1) -->
    <QuantityOnHand>0</QuantityOnHand>
    <QuantityReserved>0</QuantityReserved>
  </Inventory>
</Item>

1. If you need to look up current inventory for a particular item, then this API will do the job. But if you need to keep inventory between Shipvine and your system in sync over time, please use the Inventory API for this task; with that API, you can receive only the records for items where inventory has actually changed since your last sync. Please don't loop through your entire catalog against the Items API; use the Inventory API instead.