eBay Merchant Data APIVersion 1113

OrderAck

This call 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 or SoldReport 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.

Note: As of June 2019, eBay has changed the format of order identifier values. The new 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.

For developers and sellers who are already integrated with the Trading API's order management calls, this change shouldn't impact your integration unless you parse the existing order identifiers (e.g., OrderID or OrderLineItemID), or otherwise infer meaning from the format (e.g., differentiating between a single line item order versus a multiple line item order). Because we realize that some integrations may have logic that is dependent upon the old identifier format, eBay is rolling out this Trading API change with version control to support a transition period of approximately 9 months before applications must switch to the new format completely.

During the transition period, for developers/sellers using a Trading WSDL older than Version 1113, they can use the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header in API calls to control whether the new or old OrderID format is returned in call response payloads. To get the new OrderID format, the value of the X-EBAY-API-COMPATIBILITY-LEVEL HTTP header must be set to 1113. During the transition period and even after, the new and old OrderID formats will still be supported/accepted in all Trading API call request payloads. After the transition period (which will be announced), only the new OrderID format will be returned in all Trading API call response payloads, regardless of the Trading WSDL version used or specified compatibility level.

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.

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.

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 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 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 megaonlinemerchant 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, megaonlinemerchant'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>0</SiteID>
  </Header>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>110035505229-23336925001</OrderID>
    <OrderLineItemID>110035505229-23336925001</OrderLineItemID>
  </OrderAckRequest>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>110035571629-23291233001</OrderID>
    <OrderLineItemID>110035571629-23291233001</OrderLineItemID>
  </OrderAckRequest>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>110035504829-23270675001</OrderID>
    <OrderLineItemID>110035504829-23270675001</OrderLineItemID>
  </OrderAckRequest>
</BulkDataExchangeRequests>

Output

The OrderAck response file includes an OrderAckResponse node for each order line item that megaonlinemerchant'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>110035505229-23336925001</OrderLineItemID>
  </OrderAckResponse>
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>110035571629-23291233001</OrderLineItemID>
  </OrderAckResponse>
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>110035504829-23270675001</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 megaonlinemerchant 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, megaonlinemerchant's is acknowledging three order line items that are a part of two separate orders. The first order line item in the request, 110035505229-23336925001, makes up a single line item order, so the OrderID and OrderLineItemID values are the same. The order line items identified as 150004254168-7932295005 and 150004254165-7932296005 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>0</SiteID>
  </Header>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>110035505229-23336925001</OrderID>
    <OrderLineItemID>110035505229-23336925001</OrderLineItemID>
  </OrderAckRequest>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>6082929012</OrderID>
    <OrderLineItemID>150004254168-7932295005</OrderLineItemID>
  </OrderAckRequest>
  <OrderAckRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <OrderID>6082929012</OrderID>
    <OrderLineItemID>150004254165-7932296005</OrderLineItemID>
  </OrderAckRequest>
</BulkDataExchangeRequests>

Output

The OrderAck response file includes an OrderAckResponse node for each order line item that megaonlinemerchant'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>110035505229-23336925001</OrderLineItemID>
  </OrderAckResponse>
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>150004254168-7932295005</OrderLineItemID>
  </OrderAckResponse>
  <OrderAckResponse>
    <Ack>Success</Ack>
    <OrderLineItemID>150004254165-7932296005</OrderLineItemID>
  </OrderAckResponse>
</BulkDataExchangeResponses>

Back to list of samples



Change History

Change Date Description
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.