Resource

https://api.warehousefs.com/public/v1/tracked-returns/{merchantCode}/{merchantIdentifier}

The tracked returns resource allows the merchant to provide advance notification about returns that are being mailed to Shipvine.

POST

Request

URL Template

The {merchantCode} field in the URL template should be replaced with the merchant code for the merchant that owns the return.

The {merchantIdentifier} field in the URL should contain the merchant's identifier for the request. In many cases, the merchant's e-commerce systems' order number is a good value to put here. See note (2) in the example request XML for more information about the merchant identifier.

Note that the {merchantIdentifier} field in the URL cannot contain forward slashes, either escaped or unescaped due to a safety feature of the .NET Framework. It's unfortunate that we have to do this, but if your order numbers have slashes in them, we support a workaround where you can substitute the string {FORWARD_SLASH} in the URL template. For example, https://api.warehousefs.com/public/v1/tracked-returns/CONTOSO/123456{FORWARD_SLASH}01.

Example Request URL

https://api.warehousefs.com/public/v1/tracked-returns/CONTOSO/129834478

Query Parameters

No query parameters may be included in the request.

Entity Body

The entity body is an XML document that represents the tracked return.

Example Request Entity Body

<?xml version="1.0" encoding="utf-8"?>
<TrackedReturn> <!-- (1) -->
	<FulfillmentRequest> <!-- (2) -->
		<MerchantIdentifier>129834478</MerchantIdentifier>
		<ShipvineIdentifier>2-14-027-69323-899-2</ShipvineIdentifier>
	</FulfillmentRequest>
	<TrackingNo>1ZRV18090334709490</TrackingNo> <!-- (3) -->
	<Lines> 
		<Line> <!-- (4) -->
			<Item>
				<MerchantIdentifier>9999-1811-165</MerchantIdentifier> <!-- (5) -->
				<Modifications> <!-- (6) -->
					<Modification>Shorten sleeves by 1.0"</Modification>
				</Modifications>
			</Item>
			<Defective>False</Defective> <!-- (7) -->
		</Line>
		<Line>
			<Item>
				<MerchantIdentifier>786-548-165</MerchantIdentifier>
			</Item>
			<Defective>True</Defective>
		</Line>
	</Lines>
	<Note>The shirt I received smells bad</Note> <!-- (8) -->
	<Label> <!-- (9) -->
		<CarrierMethod> <!-- (10) -->
			<Code>PriorityMail</Code>
			<Carrier>USPS</Carrier>
		</CarrierMethod> 
		<EstimatedWeight> <!-- (11) -->
			<Magnitude>0.8</Magnitude>
			<Unit>Pounds</Unit>
		</EstimatedWeight>
		<Origin> <!-- (12) -->
			<Country>US</Country> <!-- (13) -->
			<PersonalName>
				<First>John</First>
				<Last>Doe</Last>
			</PersonalName>
			<StreetLines>
				<StreetLine>123 Main St</StreetLine>
			</StreetLines>
			<CityOrTown>Anytown</CityOrTown>
			<StateOrProvince>VA</StateOrProvince>
			<PostalCode>23005</PostalCode>
			<Phone>+18044333127</Phone> <!-- (14) -->
		</Origin>
	</Label>
</TrackedReturn>

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 overkill going forward, so leave it out here.
2. The <FulfillmentRequest /> element (and each of its child <MerchantIdentifier> and <ShipvineIdentifier> elements are optional. If specified, then the tracked return will be associated with the given fulfillment request if it exists. If this element is not present, or if the specified fulfillment request cannot be found, then the tracked return will be associated with the most recent fulfillment request with a merchant identifier that matches the {merchantIdentifier} in the URL template, if any. Practically speaking, if you are passing in your system's order number as the {merchantIdentifier} in the URL template, then you don't need to worry about the <FulfillmentRequest /> element.
3. The <TrackingNo> element is optional. If specified, then Shipvine will be able to mark your tracked return as Received by scanning the tracking number barcode when the parcel is dropped off at the loading dock. If you are requesting a Shipvine-generated return label, then leave this element out as we'll do the association for you.
4. At least one <Line> should be present in the return. Each <Line> represents a single unit in the return (i.e., a quantity of 1). If a customer is returning multiple instances of the same item, then you'll need to repeat the <Line> element that many times. This is because we'll be tracking each individual item independently as we process the return.
5. The item's <MerchantIdentifier> is required and is used to determine what item is being returned.
6. If the item being returned has been subject to modifications, adding the modification parameters here will help prevent Shipvine from returning modified product back into inventory incorrectly. If the item has not been modified, then omit the <Modifications> element completely from the request.
7. Indicate whether or not the customer has indicated that he believes the item to be defective with a True or False value. If unsure, or if you don't ask the customer this question, then send False.
8. If you provide a field for a customer to enter notes about the return, then you can pass that text along in the <Note> element. Otherwise, leave the element out.
9. You can optionally have a Shipvine Logistics generate a prepaid return label that you can relay to your customer. If you don't want a label, leave the element out.
10. The carrier method or service for the label.
    • When Carrier is set to USPS, the only acceptable Codes are FirstClassMail or PriorityMail
    • When Carrier is set to FedEx, the only acceptable Code is Ground
    • No other values are currently accepted.
11. The estimated weight of the customer return. We're not sure why the carriers ask for it since it's generally not known, but they ask for it. Note that if requesting FirstClassMail as your carrier method, the weight must be 13 oz. or fewer. If you request a FirstClassMail return label and the customer ends up returning something that weighs more than 13 oz., it will be charged as if it were PriorityMail along with the postmaster giving us the stinkeye.
12. The address that the return is coming from. If you have associated the tracked return to a fulfillment request as described in item #2, then you can omit the Origin element and we'll use the original shipping address.
13. Only US origin addresses are currently supported.
14. The carriers require a phone number. If you don't know the customer's phone number, pass in your customer service phone number.

Response

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

No Label Requested

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

Label Requested

If successful, the API will return 200 OK and an entity body that contains a Base64-encoded PDF version of the label suitable for printing on regular 8.5" x 11" paper. You can decode the PDF payload and stream it to the customer's browser so that they can print it out themselves.

Example Entity Body

<?xml version="1.0"?>
<ReturnLabel>
	<IdentificationNo>9316269932000007209156</IdentificationNo> <!-- (1) -->
	<Payload>JVBERi0xLjUNCiW1tbW1DQoxIDAgb2JqDQo8PC9UeXBlL0NhdGFs...</Payload> <!-- (2) -->
</ReturnLabel>

1. The tracking number for the generated label.
2. The Base64-encoded PDF payload, suitable for printing on an 8.5" x 11" printer.