Resource #1

https://api.warehousefs.com/public/v1/inbound-shipments/{merchantCode}

This version of the inbound shipments resource allows the merchant to query for a listing of inbound shipments that may have been recently completed.

GET

Request

URL Template

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

Example Request URL

   https://api.warehousefs.com/public/v1/inbound-shipments/CONTOSO?state=Complete&changed-since=2014-10-15T16:45:00Z

Query Parameters

The method supports the following query parameters:

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 inbound shipment.

If any error occurs, the HTTP status code will not be 200 OK .

The entity body is an XML document that represents a listing of the inbound shipments. You can use the MerchantIdentifier field in the response to look up more details about the inbound shipment by issuing a GET request to Resource #2.

Example Response Entity Body

<?xml version="1.0" encoding="utf-8"?>
<InboundShipments>
  <InboundShipment>
    <MerchantIdentifier>S12345</MerchantIdentifier>
    <State>Complete</State>
  </InboundShipment>
  <InboundShipment>
    <MerchantIdentifier>S54321</MerchantIdentifier>
    <State>NotComplete</State>
  </InboundShipment>
</InboundShipments>

Resource #2

https://api.warehousefs.com/public/v1/inbound-shipments/{merchantCode}/{merchantIdentifier}

The inbound shipments resource allows the merchant to provide an advance shipment notification for new inventory being sent to Shipvine. Shipvine will reconcile the shipments it receives against the appropriate inbound shipment, and the merchant may inspect the manifest for discrepancies between what Shipvine was expected to receive and what Shipvine says it received.

PUT

Request

URL Template

The {merchantCode} field in the URL template should be replaced with the merchant code for the merchant that the items in the inbound shipment belong to.

The {merchantIdentifier} field in the URL should contain the merchant's identifier for the inbound shipment. This value should be clearly indicated on the parcels that are shipped to Shipvine. For example, the merchant's purchase order number is a good value to put here. It must be unique among all other inbound shipments associated with the merchant account.

Example Request URL

   https://api.warehousefs.com/public/v1/inbound-shipments/CONTOSO/PO%20234-58

Query Parameters

No query parameters may be included in the request.

Entity Body

The entity body is an XML document that represents the inbound shipment. If the inbound shipment already exists, it is replaced with the version specified in the XML document. If Shipvine has started receiving the inbound shipment, then it may not be updated and an error will be returned.

Example Request Entity Body

<?xml version="1.0"?>
<InboundShipment> <!-- (1) -->
  <ExpectedAt>2014-02-28</ExpectedAt> <!-- (2) -->
  <Lines>
    <Line>
      <Item>
        <MerchantIdentifier>1891-212-15</MerchantIdentifier> <!-- (3) -->
      </Item>
      <QuantityExpected>7</QuantityExpected> <!-- (4) -->
    </Line>
    <Line>
      <Item>
        <MerchantIdentifier>1001-1-A3</MerchantIdentifier>
      </Item>
      <QuantityExpected>3</QuantityExpected>
    </Line>
  </Lines>
</InboundShipment>

1. Older Shipvine Logistics APIs require an XML namespace declaration here so that the document will validate against an XML schema, but we're moving away from that going forward, so leave it out here.
2. A guesstimated date for when the shipment will arrive at the Shipvine warehouse, in YYYY-MM-DD format. This helps Shipvine allocate resources appropriately ahead of the shipment.
3. Each <Line /> element describes an item that should be expected in the shipment, and the item's <MerchantIdentifier> is used to determine which item is expected. The item must already exist in the Shipvine Logistics catalog; otherwise, an error will be returned.
4. The quantity that is expected to arrive at the Shipvine warehouse, expressed as a positive integer. Values less than or equal to zero will return an error.

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 inbound shipment belongs to.

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

Example Request URL

   https://api.warehousefs.com/public/v1/inbound-shipments/CONTOSO/PO%20234-58

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 inbound shipment.

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

The entity body is an XML document that represents the inbound shipment. If the inbound shipment already exists, it is replaced with the version specified in the XML document. If Shipvine has started receiving the inbound shipment, then it may not be updated and an error will be returned.

Example Response Entity Body

<?xml version="1.0" encoding="utf-8"?>
<InboundShipment>
  <Merchant>
    <Code>CONTOSO</Code>
  </Merchant>
  <MerchantIdentifier>PO 20234-58</MerchantIdentifier>
  <ExpectedAt>2014-02-28</ExpectedAt>
  <Totals>
    <Expected>7</Expected> <!-- (1) -->
    <Resolved>11</Resolved> <!-- (2) -->
    <Unresolved>3</Unresolved> <!-- (3) -->
  </Totals>
  <ExpectedLines> <!-- (4) -->
    <ExpectedLine>
      <Item>
        <MerchantIdentifier>1891-212-15</MerchantIdentifier>
        <VariationsSummary>Size: 15</VariationsSummary>
        <ItemGroup>
          <MerchantIdentifier>1891-212</MerchantIdentifier>
          <Name>Vanguard Button Down Slim Super Check Shirt</Name>
        </ItemGroup>
      </Item>
      <QuantityExpected>7</QuantityExpected> <!-- (5) -->
      <QuantityReceived>6</QuantityReceived> <!-- (6) -->
    </ExpectedLine>
  </ExpectedLines>
  <UnexpectedLines> <!-- (7) -->
    <UnexpectedLine>
      <Item>
        <MerchantIdentifier>1123-34-A3</MerchantIdentifier> <!-- (8) -->
        <VariationsSummary>Size: A3</VariationsSummary>
        <ItemGroup>
          <MerchantIdentifier>1123-34</MerchantIdentifier>
          <Name>Fancy Tie</Name>
        </ItemGroup>
      </Item>
      <QuantityReceived>5</QuantityReceived>
    </UnexpectedLine>
    <UnexpectedLine>
      <Item>
        <Barcode>8675309999</Barcode> <!-- (9) -->
      </Item>
      <QuantityReceived>3</QuantityReceived>
    </UnexpectedLine>
  </UnexpectedLines>
</InboundShipment>

1. The total number of units that the merchant expected Shipvine to receive.
2. The total number of units that Shipvine received and was able to associate with an item entered in the Shipvine Logistics catalog.
3. The total number of units that had barcodes that did not match any items entered in the Shipvine Logistics catalog. Such items were not added to inventory, and a Shipvine employee will contact the merchant for resolving the error.
4. Each <ExpectedLine /> represents an item that the merchant expected Shipvine to receive in the inbound shipment.
5. The number of units that the merchant expected Shipvine to receive.
6. The number of units that Shipvine actually received.
7. Each <UnexpectedLine /> represents an item that the merchant did not expect Shipvine to receive as part of the inbound shipment. This could indicate data entry errors, shipping errors, or misapplied barcodes.
8. If the barcode scanned by Shipvine is unexpected but can be reconciled against an existing item for that merchant in the Shipvine Logistics catalog, then the item is added to inventory anyway. The <Quantity Received /> element represents the number of items that were added to inventory.
9. If the barcode scanned by Shipvine is unexpected and cannot be reconciled against an existing item for that merchant in the Shipvine Logistics catalog, then the barcode is displayed. These items are not added to inventory (because Shipvine does not know what they are), and the <Quantity Received /> element represents the number of items that require resolution. A Shipvine employee will contact the merchant to resolve the errors.

DELETE

Request

URL Template

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

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

Example Request URL

   https://api.warehousefs.com/public/v1/inbound-shipments/CONTOSO/PO%20234-58

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 empty entity body. This indicates that the inbound shipment was found and was deleted from the system.

If any error occurs, the HTTP status code will not be 200 OK ; for example, if Shipvine has already started work on the inbound shipment, then it can't be deleted. An <Errors /> element may be present in the entity body.