Merchant Data API879

SetShipmentTrackingInfo

Specifies the shipment tracking information associated with one package of an order. If multiple packages are required for the order, this call must be made separately for each package.

Note: For orders on the eBay India site, SetShipmentTrackingInfo cannot be used if the buyer uses PaisaPay as the payment method. Note: SetShipmentTrackingInfo cannot be issued on its own like an ordinary API call, using an endpoint. This Large Merchant Services call must be entered one or more times as the payload in a data file that will be uploaded to an eBay server using the File Transfer API, then processed using the Bulk Data Exchange API. This call will fail if you attempt to invoke it directly.

In the Trading API, the CompleteSale call provides similar functionality that you can invoke directly. For more information, see the CompletSale call reference.



Back to top

SetShipmentTrackingInfo Input

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

<?xml version="1.0" encoding="utf-8"?>
<SetShipmentTrackingInfoRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <IsPaid> boolean </IsPaid>
  <IsShipped> boolean </IsShipped>
  <OrderID> string </OrderID>
  <OrderLineItemID> string </OrderLineItemID>
  <Shipment> ShipmentType
    <ShipmentLineItem> ShipmentLineItemType
      <LineItem> LineItemType
        <CountryOfOrigin> string </CountryOfOrigin>
        <Description> string </Description>
        <ItemID> ItemIDType (string) </ItemID>
        <Quantity> int </Quantity>
        <TransactionID> string </TransactionID>
      </LineItem>
      <!-- ... more LineItem nodes allowed here ... -->
    </ShipmentLineItem>
    <ShipmentTrackingNumber> string </ShipmentTrackingNumber>
    <ShippedTime> dateTime </ShippedTime>
    <ShippingCarrierUsed> string </ShippingCarrierUsed>
  </Shipment>
</SetShipmentTrackingInfoRequest>
Argument Type Occurrence Meaning
IsPaid boolean Optional The seller includes and sets this field to true if the buyer has paid for the order. If the call is successful, the order line item(s) are marked as Paid in My eBay.

If the seller includes and sets this field to false, the order line item(s) are marked (or remain) as Not Paid in My eBay.

If this field is not included, the paid status of the order line item(s) remain unchanged in My eBay.
IsShipped boolean Optional When shipment tracking information is provided through the Shipment container in the same request, the IsShipped status is set to true automatically. If the call is successful, the specified order or order line item(s) are marked as Shipped in My eBay.

If the seller includes and sets this field to false, the order or order line item(s) are marked (or remain) as Not Shipped in My eBay.
Default: true.
OrderID string Conditional A unique identifier that identifies a single line item or multiple line item (Combined Invoice) order.

For a single line item order, the OrderID value is identical to the OrderLineItemID value that is generated upon creation of the order line item. For a Combined Invoice order, the OrderID value is created by eBay when the buyer or seller (sharing multiple, common order line items) combines multiple order line items into a Combined Invoice order through the eBay site. A Combined Invoice order can also be created by the seller through the AddOrder call. Either the OrderID or the OrderLineItemID value must be passed in the request.

See Combined Invoice.

OrderLineItemID string Conditional A unique identifier for an eBay order line item. This field is created as soon as there is a commitment to buy from the seller, and its value is based upon the concatenation of ItemID and TransactionID, with a hyphen in between these two IDs. Either the OrderLineItemID or the OrderID value must be passed in the request.
Shipment ShipmentType Optional Container consisting of the shipping carrier name, the package tracking number, and optionally, the timestamp of the shipment.
Shipment.ShipmentLineItem ShipmentLineItemType Optional Contains information about one or more order line items in a Global Shipping Program package. Required or returned if the value of ShippingCarrierUsed is GlobalShipping_MultiCarrier.
Shipment.ShipmentLineItem
  .LineItem
LineItemType Optional,
repeatable: [1..*]
Contains information about one order line item in a Global Shipping Program package. The package can contain multiple units of a given order line item, and multiple order line items.
Shipment.ShipmentLineItem
  .LineItem.CountryOfOrigin
string Optional The Country of Manufacture for the order line item; this is required for customs. This should identify the country in which more than 50% of the value of the item was created.

This value must conform to the ISO 3166 two-letter country code standard. To see the list of currently supported codes, and the English names associated with each code (e.g., KY="Cayman Islands"), call GeteBayDetails with DetailName set to CountryDetails.
Shipment.ShipmentLineItem
  .LineItem.Description
string Optional The item description of the order line item, based on its ItemID.
Shipment.ShipmentLineItem
  .LineItem.ItemID
ItemIDType (string) Optional Unique identifier for the eBay item listing of the order line item. A listing can have multiple order line items (transactions), but only one ItemID. Unless an OrderLineItemID or SKU value is specified in the same node, this field is required for each ItemTransactionID node included in the request.
Shipment.ShipmentLineItem
  .LineItem.Quantity
int Optional The number of units of the order line item in this package; this is required for customs. The seller must ensure that this matches the quantity of the order line item enclosed in the package.

This value must be a positive integer, and it can't be greater than the quantity of this item specified in the original transaction.
Shipment.ShipmentLineItem
  .LineItem.TransactionID
string Optional Unique identifier for an eBay order line item (transaction). The TransactionID should match the ItemID specified in each ItemTransactionID node included in the request. Optionally, an OrderLineItemID value can substitute for the ItemID/TransactionID pair.
Shipment
  .ShipmentTrackingNumber
string Conditional The tracking number associated with one package of a shipment. The seller is responsible for the accuracy of the shipment tracking number. eBay verifies the tracking number is unique (across all of a seller's orders) and consistent with the numbering scheme used by the specified shipping carrier. eBay cannot verify the accuracy of the tracking number. This field is required if ShippingCarrierUsed is included in the call request.

Sellers can specify multiple tracking numbers for the same ShippingCarrierUsed by separating the tracking numbers with commas.

ShippingCarrierUsed and ShipmentTrackingNumber are dependent upon each other. You must either specify both, or specify neither.
Shipment.ShippedTime dateTime Optional The date and time that the seller handed off the package(s) to the shipping carrier. If this field is not included in the request, the timestamp of the call execution is used as the shipped time. Note that sellers have the ability to set this value up to 3 calendar days in the future.
Shipment.ShippingCarrierUsed string Conditional The shipping carrier used to ship the package. This value can be any combination of alphanumeric characters and it is not checked and verified by eBay. This field is required if ShipmentTrackingNumber is included in the call request.

ShippingCarrierUsed and ShipmentTrackingNumber are dependent upon each other. You must either specify both, or specify neither.



Back to top

SetShipmentTrackingInfo Output

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also Samples.

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<SetShipmentTrackingInfoResponse xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Output Fields -->
  <OrderLineItemID> string </OrderLineItemID>
  <!-- Standard Output Fields -->
  <Ack> AckCodeType </Ack>
  <Errors> ErrorType
    <ErrorClassification> ErrorClassificationCodeType </ErrorClassification>
    <ErrorCode> token </ErrorCode>
    <ErrorParameters ParamID="string"> ErrorParameterType
      <Value> string </Value>
    </ErrorParameters>
    <!-- ... more ErrorParameters nodes allowed here ... -->
    <LongMessage> string </LongMessage>
    <SeverityCode> SeverityCodeType </SeverityCode>
    <ShortMessage> string </ShortMessage>
  </Errors>
  <!-- ... more Errors nodes allowed here ... -->
</SetShipmentTrackingInfoResponse>
Return Value Type Occurrence Meaning
Call-specific Output Fields [Jump to standard fields]
OrderLineItemID string Always OrderLineItemID is required upon input and always returned in the response. You can use this field to track whether or not a response is returned for every request, and to match specific responses to Specific requests.
Standard Output Fields  
Ack AckCodeType Always A token representing the application-level acknowledgement code that indicates the response status (e.g., success). The AckCodeType list specifies the possible values for the Ack field.

Applicable values:

•   CustomCode

Reserved for internal or future use.

•   Failure

Request processing failed

•   Success

Request processing succeeded

•   Warning

Request processing completed with warning information being included in the response message


(Not all values in AckCodeType apply to this field.)
Errors ErrorType Conditionally,
repeatable: [0..*]
A list of application-level errors (if any) that occurred when eBay processed the request.

See Error Handling.

Errors.ErrorClassification ErrorClassificationCodeType Conditionally API errors are divided between two classes: system errors and request errors.

Applicable values:

•   CustomCode

Reserved for internal or future use.

•   RequestError

An error has occurred either as a result of a problem in the sending application or because the application's end-user has attempted to submit invalid data (or missing data). In these cases, do not retry the request. The problem must be corrected before the request can be made again. If the problem is due to something in the application (such as a missing required field), the application must be changed. If the problem is a result of end-user data, the application must alert the end-user to the problem and provide the means for the end-user to correct the data. Once the problem in the application or data is resolved, resend the request to eBay with the corrected data.

•   SystemError

Indicates that an error has occurred on the eBay system side, such as a database or server down. An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form.


Errors.ErrorCode token Conditionally A unique code that identifies the particular error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms. See the "Errors by Number" document.
Errors.ErrorParameters ErrorParameterType Conditionally,
repeatable: [0..*]
This optional element carries a list of context-specific error variables that indicate details about the error condition. These are useful when multiple instances of ErrorType are returned.
Errors.ErrorParameters
  [ attribute ParamID ]
string Conditionally This optional element carries a list of context-specific error variables that indicate details about the error condition. These are useful when multiple instances of ErrorType are returned.
Errors.ErrorParameters.Value string Conditionally The value of the variable (e.g., the attribute set ID)
Errors.LongMessage string Conditionally A more detailed description of the condition that raised the error.
Errors.SeverityCode SeverityCodeType Conditionally Indicates whether the error is a severe error (causing the request to fail) or an informational error (a warning) that should be communicated to the user.

Applicable values:

•   CustomCode

Reserved for internal or future use.

•   Error

The request that triggered the error was not processed successfully. When a serious application-level error occurs, the error is returned instead of the business data.

If the source of the problem is within the application (such as a missing required element), change the application before you retry the request.

  • If the problem is due to end-user input data, please alert the end-user to the problem and provide the means for them to correct the data. Once the problem in the application or data is resolved, you can attempt to re-send the request to eBay.
  • If the source of the problem is on eBay's side, An application can retry the request as-is a reasonable number of times (eBay recommends twice). If the error persists, contact Developer Technical Support. Once the problem has been resolved, the request may be resent in its original form.


See the Compatible Application Check section of the eBay Features Guide for more information.

•   Warning

The request was processed successfully, but something occurred that may affect your application or the user. For example, eBay may have changed a value the user sent in. In this case, eBay returns a normal, successful response and also returns the warning.

When a warning occurs, the error is returned in addition to the business data. In this case, you do not need to retry the request (as the original request was successful). However, depending on the cause or nature of the warning, you might need to contact either the end user or eBay to effect a long term solution to the problem to prevent it from reoccurring in the future.


Errors.ShortMessage string Conditionally A brief description of the condition that raised the error.



Back to top

SetShipmentTrackingInfo Samples

New to making API calls? Please see Making an API Call.

Note: Some data in these samples might no longer be active. If necessary, you can substitute current data in your requests.

Sample: Basic Call

Request that you use to record that an order has been shipped. Use the SetShipmentTrackingInfo request to associate each line item in a SoldReport to the shipped time, tracking service, and tracking number that you used when shipping an item.

Description

User megaonlinemerchant wants to keep track of the carrier information and tracking number for each item in her Sold Report that she has shipped to date. She starts order processing and creates a data file to set the shipment tracking info. at the same time she creates the data file to acknowledged orders in her Sold Report.

Input

The fields in the following SetShipmentTrackingInfo request represent a shipped item from one of megaonlinemerchant's basketball shoe listings. In this sample, we have included a basic SetShipmentTrackingInfo request. In a more typical SetShipmentTrackingInfo request file, you might record and upload data for thousands of shipped items.

XML format (HTTP POST). Also available are the .txt version of this XML.

<?xml version="1.0" encoding="UTF-8"?>
<BulkDataExchangeRequests>
  <Header>
    <Version>591</Version>
    <SiteID>0</SiteID>
  </Header>
  <SetShipmentTrackingInfoRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>110035505229-23336925001</OrderID>
    <OrderLineItemID>110035505229-23336925001</OrderLineItemID>
    <Shipment> 
      <ShipmentTrackingNumber>1Z 999 999 99 9999 999 9</ShipmentTrackingNumber>
      <ShippedTime>2008-11-25T12:00:00.000Z</ShippedTime>
      <ShippingCarrierUsed>UPS</ShippingCarrierUsed>
    </Shipment>
  </SetShipmentTrackingInfoRequest>
  <SetShipmentTrackingInfoRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>110035571629-23291233001</OrderID>
    <OrderLineItemID>110035571629-23291233001</OrderLineItemID>
    <Shipment> 
      <ShipmentTrackingNumber>1Z 888 888 88 8888 888 8</ShipmentTrackingNumber>
      <ShippedTime>2008-11-25T12:00:00.000Z</ShippedTime>
      <ShippingCarrierUsed>UPS</ShippingCarrierUsed>
    </Shipment>
  </SetShipmentTrackingInfoRequest>
  <SetShipmentTrackingInfoRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>110035504829-23270675001</OrderID>
    <OrderLineItemID>110035504829-23270675001</OrderLineItemID>
    <Shipment> 
      <ShipmentTrackingNumber>1Z 777 777 77 7777 777 7</ShipmentTrackingNumber>
      <ShippedTime>2008-11-25T12:00:00.000Z</ShippedTime>
      <ShippingCarrierUsed>UPS</ShippingCarrierUsed>
    </Shipment>
  </SetShipmentTrackingInfoRequest>
</BulkDataExchangeRequests>

Output

The SetShipmentTrackingInfo response file includes the OrderID and OrderLineItemID of the item you have shipped, call Success or Failure, and any error numbers and messages returned by the call request. For multiple line items, each shipment is listed as a separate node.

XML format.
<?xml version="1.0" encoding="utf-8"?>
<BulkDataExchangeResponses xmlns="urn:ebay:apis:eBLBaseComponents">
<SetShipmentTrackingInfoResponse>
<Ack>Success</Ack>
<OrderLineItemID>110035505229-23336925001</OrderLineItemID>
</SetShipmentTrackingInfoResponse>
<SetShipmentTrackingInfoResponse>
<Ack>Success</Ack>
<OrderLineItemID>110035571629-23291233001</OrderLineItemID>
</SetShipmentTrackingInfoResponse>
<SetShipmentTrackingInfoResponse>
<Ack>Success</Ack>
<OrderLineItemID>110035504829-23270675001</OrderLineItemID>
</SetShipmentTrackingInfoResponse>
</BulkDataExchangeResponses>



Back to top

SetShipmentTrackingInfo Change History

Version Description
809
2013-02-06
  • SetShipmentTrackingInfoRequest (doc change): For orders on the eBay India site, SetShipmentTrackingInfo cannot be used if the buyer uses PaisaPay as the payment method.
727
2011-06-22
  • ShipmentTrackingNumber, ShippingCarrierUsed (modified): ShipmentTrackingNumber and ShippingCarrierUsed are no longer always required. These fields are now conditionally required. If you specify one, you must specify the other, but now they can both be omitted from the request.
589
2008-11-29
  • (added) New call.

Back to top

User-Contributed Notes

 

Copyright © 2008–2014 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.