eBay Merchant Data APIVersion 1331
 

OrderAck

Note: Large Merchant Services (LMS) functionality as a SOAP service has been decommissioned. It is fully migrated into the REST-based Sell Feed API The Sell Feed API supports the same XML data files that LMS supported but through REST methods. For more information, see the LMS Feed Guide. OrderAck is used to acknowledge that a single line item order, or an individual line item within a multiple line item order has been received. Once an order or order line item is successfully acknowledged with an OrderAck call, that order or order line item will not appear in the OrderReport response when you run either of those calls again.



Input

See also Samples.

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

<?xml version="1.0" encoding="utf-8"?>
<OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <!-- Call-specific Input Fields -->
  <OrderID> string </OrderID>
  <OrderLineItemID> string </OrderLineItemID>
</OrderAckRequest>
Argument Type Occurrence Meaning
OrderID string Conditional A unique identifier for an eBay order. An eBay order can contain one or more order line items. This field is used to acknowledge a single line item order. If the eBay order has multiple line items, an OrderAck call will be required to acknowledge each of those order line items, and the OrderLineItemID field must be used instead.

Typically, the OrderAck call will only be used on orders/line items that have already been paid for and shipped.

Note: In June 2019, eBay introduced a new order ID format, but allowed developers/sellers to decide whether to immediately adopt the new format, or to continue working with the old format. Users who wanted to adopt the new format, could either use a Trading WSDL Version 1113 (or newer), or they could even use an older Trading WSDL but set the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header value to 1113 in API calls. Beginning in June 2020, only the new order ID format will be returned in response payloads for paid orders, regardless of the WSDL version number or compatibility level.

Note that the unique identifier of a 'non-immediate payment' order will change as it goes from an unpaid order to a paid order. Due to this scenario, all calls that accept Order ID values as filters in the request payload, including the OrderAck call, will support the identifiers for both unpaid and paid orders. However, the OrderAck call is typically only used to acknowledge orders/line items that have already been paid for, so the new order ID format will be used for this call in most cases. The new order ID format is a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. Unlike in the past, instead of just being known and exposed to the seller, these unique order identifiers will also be known and used/referenced by the buyer and eBay customer support.

Sellers can check to see if an order has been paid by looking for a value of 'Complete' in the CheckoutStatus.Status field in the response of GetOrders or GetOrderTransactions call, or in the Status.CompleteStatus field in the response of GetItemTransactions or GetSellerTransactions call. Sellers should not fulfill orders until buyer has made payment.

Max length: 40.
OrderLineItemID string Conditional A unique identifier for an order line item within an eBay order. An eBay order can contain one or more order line items. If you use this field, only the specified order line item will be acknowledged, and any additional order line items within the eBay order will remain unacknowledged.

If an order only has one order line item, either the OrderID or the OrderLineItemID field will acknowledge the entire order.



Output

See also Samples.

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

<?xml version="1.0" encoding="utf-8"?>
<OrderAckResponse 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 ... -->
</OrderAckResponse>
Return Value Type Occurrence Meaning
Call-specific Output Fields [Jump to standard fields]
OrderLineItemID string Always This is the unique identifier of the order line item that was successfully acknowledged. This field is returned whether an OrderID (for a single line item order) or an OrderLineItemID value was passed into the call request.
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
This value indicates that the call request processing failed.
Success
This value indicates that the call request was processed successfully without any issues.
Warning
This value indicates that the call request was successful, but processing was not without any issues. These issues can be checked in the Errors container, that will also be returned when one or more known issues occur with the call request.

(Not all values in AckCodeType apply to this field.)

Code so that your app gracefully handles any future changes to this list.
Errors ErrorType Conditionally,
repeatable: [0..*]
A list of application-level errors (if any) that occurred when eBay processed the request.
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.

Code so that your app gracefully handles any future changes to this list.
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 Errors By Number.

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 This is the value of the request parameter noted in the ParamID attribute. So, if the ParamID value was ItemID, the value in this field would be the actual value of that ItemID.
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.

Code so that your app gracefully handles any future changes to this list.
Errors.ShortMessage string Conditionally A brief description of the condition that raised the error.



Samples

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

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Available samples:

Sample: Acknowledging Single Line Item Orders

This call is used to acknowledge that orders have been received. The OrderID and OrderLineItemID values are passed in for each order line item. For single line item orders, these two values are the same. All orders that are acknowledged through the OrderAck call will no longer appear in the SoldReport responses.

Description

User m****************t wants to send an order acknowledgement for three single line item orders that appeared in the SoldReport reponse, so that they will not appear in a subsequent SoldReport response.

Input

In this OrderAck sample, m****************t's is acknowledging three single line item orders. Since the orders are all single line item orders, the OrderID and OrderLineItemID values are the same. An OrderAckRequest node is required for each order line item. Although this sample covers only three orders, it is not uncommon that an OrderAck call is used to acknowledge thousands of order line items. In a more typical OrderAck request file, a seller might acknowledge thousands of sold items.

XML format.

<?xml version="1.0" encoding="UTF-8"?>
<BulkDataExchangeRequests>
  <Header>
    <Version>591</Version>
    <SiteID>*</SiteID>
  </Header>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>1**********9-2*********1</OrderID>
    <OrderLineItemID>1**********9-2*********1</OrderLineItemID>
  </OrderAckRequest>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>1**********9-2*********1</OrderID>
    <OrderLineItemID>1**********9-2*********1</OrderLineItemID>
  </OrderAckRequest>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>1**********9-2*********1</OrderID>
    <OrderLineItemID>1**********9-2*********1</OrderLineItemID>
  </OrderAckRequest>
</BulkDataExchangeRequests>

Output

The OrderAck response file includes an OrderAckResponse node for each order line item that m****************t's is attempting to acknowledge. Each OrderAckResponse node includes the unique identifier of the order line item (OrderLineItemID) and an ack value of 'Success' or 'Failure'. In this sample, all three single line item orders were acknowledged successfully, and these order line items will no longer appear in a SoldReport response. If any errors or warnings occured at the call level, they would have been emitted in the response through an Errors container.

XML format.
<?xml version="1.0" encoding="utf-8"?>
<BulkDataExchangeResponses xmlns="urn:ebay:apis:eBLBaseComponents">
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>1**********9-2*********1</OrderLineItemID>
  </OrderAckResponse>
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>1**********9-2*********1</OrderLineItemID>
  </OrderAckResponse>
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>1**********9-2*********1</OrderLineItemID>
  </OrderAckResponse>
</BulkDataExchangeResponses>

Back to list of samples

Sample: Acknowledging Single and Multiple Line Item Orders

This call is used to acknowledge that orders have been received. The OrderID and OrderLineItemID values are passed in for each order line item. For single line item orders, these two values are the same. For multiple line item orders, the OrderID value is the Combined Payment order ID that is automatically generated by eBay when multiple order line items are combined into one order and the buyer makes one payment for multiple order line items. All orders that are acknowledged through the OrderAck call will no longer appear in any SoldReport responses.

Description

User m****************t wants to send an order acknowledgement for two orders. One order is a single line item order, and the other order contains two order line items. Once these three order line items are acknowledged through this OrderAck call, they will no longer appear in any SoldReport responses.

Input

In this OrderAck sample, m****************t's is acknowledging three order line items that are a part of two separate orders. The first order line item in the request, 1**********9-2*********1, makes up a single line item order, so the OrderID and OrderLineItemID values are the same. The order line items identified as 1**********8-7********5 and 1**********5-7********6 are two order line items that are a part of the same Combined Payment order, so a separate, unique OrderID value was created by eBay as soon as these items became part of a Combined Payment order. An OrderAckRequest node is required for each order line item. Notice that the second and third order line items passed in the request have the same Combined Payment OrderID value.

XML format.

<?xml version="1.0" encoding="UTF-8"?>
<BulkDataExchangeRequests>
  <Header>
    <Version>819</Version>
    <SiteID>*</SiteID>
  </Header>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>1**********9-2*********1</OrderID>
    <OrderLineItemID>1**********9-2*********1</OrderLineItemID>
  </OrderAckRequest>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>6********2</OrderID>
    <OrderLineItemID>1**********8-7********5</OrderLineItemID>
  </OrderAckRequest>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>6********2</OrderID>
    <OrderLineItemID>1**********5-7********6</OrderLineItemID>
  </OrderAckRequest>
</BulkDataExchangeRequests>

Output

The OrderAck response file includes an OrderAckResponse node for each order line item that m****************t's is attempting to acknowledge. Each OrderAckResponse node includes the unique identifier of the order line item (OrderLineItemID) and an ack value of 'Success' or 'Failure'. In this sample, all three order line items (two of which were part of the same Combined Payment order) were acknowledged successfully, and these order line items will no longer appear in a SoldReport response. If any errors or warnings occured at the call level, they would have been emitted in the response through an Errors container.

XML format.
<?xml version="1.0" encoding="utf-8"?>
<BulkDataExchangeResponses xmlns="urn:ebay:apis:eBLBaseComponents">
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>1**********9-2*********1</OrderLineItemID>
  </OrderAckResponse>
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>1**********8-7********5</OrderLineItemID>
  </OrderAckResponse>
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>1**********5-7********6</OrderLineItemID>
  </OrderAckResponse>
</BulkDataExchangeResponses>

Back to list of samples



Change History

Change Date Description
1145
2020-03-13
  • OrderID (doc change): Updated OrderID request field description to state that beginning in April 2020, users will no longer be able to control whether returned order ID values for paid orders are in the old or new format, regardless of the WSDL version number and/or compatibility level. Previously, when the new order ID format was introduced in June 2019, the user could control whether they wanted to see the new or old order ID format in response payloads. Note that with the new order ID format, the unique identifier of an order will change as the order goes from unpaid to paid status. OrderAck will still accept order ID values for unpaid orders, but OrderAck is generally used to acknowledge orders that have been paid for.
1113
2019-06-21
  • OrderID (modified): The new format of order identifier values was rolled out. Both the new and old order ID format will be accepted in request payloads to identify an eBay order. The format (old or new) that is returned in response payloads is dependent on the WSDL version and/or compatibility level. See the 1113 Release Notes for more details.
1107
2019-05-10
  • OrderID (modified): Starting in June 2019, eBay will start changing the format of order identifier values. The new format will be a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. To enable and use the new format, the user will need to use the 1107 WSDL (or newer as versions roll out) and set the compatibility level to 1113. There will be a nine-month transition period where the old format will still be supported.
0821
2013-04-24
  • (doc change) Added a new sample to demonstrate how to acknowledge multiple line item orders.
0589
2008-11-29
  • (added) New call.