Resource

https://api.warehousefs.com/public/v1/item-groups/{merchantCode}/{merchantIdentifier}

The item groups 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 group belongs to.

The {merchantIdentifier} field in the URL should contain the merchant's identifier for the item group. Typically, this is a truncated version of the child item's identifiers. Continuing the surfer t-shirt example, if the items have identifiers of "SURFER-RED-M", "SURFER-BLUE-XL", etc., then a good merchant identifier for the item group would be "SURFER".

Example Request URL

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

Query Parameters

No query parameters may be included in the request.

Entity Body

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

Example Request Entity Body

<?xml version="1.0"?> <-- (1) -->
<ItemGroup>
  <Name>Surfer T-Shirt</Name> <-- (2) -->
  <HarmonizedCode>6105100000</HarmonizedCode> <-- (3) -->
  <CountryOfOrigin>TH</CountryOfOrigin> <-- (4) -->
</ItemGroup>

1. Older Shipvine Logistics API resources require a particular XML namespace declaration here, but this resource does not use a namespace.
2. A human-readable name that will be applied to all items contained within the item group.
3. A 10-digit harmonized code must be supplied so that Shipvine can properly prepare commodity documentation for international shipments. There is a harmonized code for almost every good you can imagine. You can look up harmonized codes at the Schedule B Search Engine; we want the 10-digit code without the periods. If in doubt, contact Shipvine Support for help in determining the harmonized code for your product.
4. The ISO two-letter code for the country in which the items within the item group were manufactured. If your company is based in the US, but your products are made a factory in China, then you'd put CN here.

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 group belongs to.

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

Example Request URL

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

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 group.

If any error occurs, the HTTP status code will not be 200 OK; for example, if the item group 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"?>
<ItemGroup>
  <Merchant>
    <Code>RIPS</Code>
  </Merchant>
  <MerchantIdentifier>SURFER</MerchantIdentifier>
  <Name>Surfer T-Shirt</Name>
  <HarmonizedCode>
    <Abbreviation>MEN'S OR BOYS' SHIRTS OF COTTON, KNITTED OR CROCHE</Abbreviation>
    <Heading>6105100000</Heading>
    <Description>MEN'S OR BOYS' SHIRTS OF COTTON, KNITTED OR CROCHETED</Description>
  </HarmonizedCode>
  <CountryOfOrigin>
    <AlphabeticCode>TH</AlphabeticCode>
    <EnglishName>Thailand</EnglishName>
  </CountryOfOrigin>
</ItemGroup>