Post-Order API Release Notes
Just getting started with the Post-Order API? The navigation bar contains links to the API Reference, the Usage Guide, and more.
See the following for a general introduction to the Post-Order API, and other resources offered by the eBay Developers Program:
- Post-Order API - Usage Guide – An introduction to the Post-Order API
- Developers Program – Join page
- Developer Support – Request support or file a bug
- Knowledge Base – Answers to API questions
- API Site Status – Current server status
API Releases
The following table lists the official releases for the Post-Order API, Version 2:
| Release Version | Release Date | Description of Release | |
|---|---|---|---|
| Version 2.7.2 | 2022-06-15 | New error code added | |
| Version 2.7.1 | 2020-12-07 | Improvement/enhancement of existing errors | |
| Version 2.7 | 2020-08-17 | Fields added to support currency conversion for managed payments sellers selling internationally, and containers added to show net charge amount and fee credits for cancelled/returned orders | |
| Version 2.6 | 2020-05-13 | eBay managed payments info added for buyer refunds | |
| Version 2.5 | 2019-10-21 | Updates to Cancellation resource. | |
| Version 2.4 | 2019-06-12 | Added ability to auto-relist an item when refund is issued. | |
| Version 2.3 | 2019-01-01 | Added ability for sellers to provide return instructions. | |
| Version 2.2 | 2015-09-28 | Added seller shipping label functionality. | |
| Version 2.1 | 2015-08-24 | Added order inquiry and order escalation functionality. | |
| Version 2.0 | 2015-06-29 | Initial Version 2 Release |
Post-Order API – version 2.7.2
New error code added
The following error code was added with this release:
- 292057: You've exceeded the default payment method's limit. Please use a different payment option or try again later.
Post-Order API – version 2.7.1
New error codes added; description updates
The following error codes were added or updated with this release:
- 1754: Your refund did not go through. Please use a different payment option and try again.
- 1755: Your refund did not go through. Please add a payment option to refund the buyer.
- 1764: Your refund did not go through. Please try again later or contact us.
- 292054: Your refund did not go through. Please use a different payment option and try again.
Post-Order API – version 2.7
Schema Changes
| Name | Part of Schema | Type of Change |
|---|---|---|
AppealDetails.appealRefundAmount |
Field | New |
Amount.exchangeRate |
Field | New |
ActualRefund.feeCreditAmount |
Field | New |
RefundAmounts.feeCreditAmount |
Field | New |
ActualRefundDetail.netChargeAmount |
Field | New |
CaseDetails.refundChargeAmount |
Field | New |
InquiryDetails.refundChargeAmount |
Field | New |
Changed Methods
Fields added to support currency conversion for managed payments sellers selling internationally
Currency conversion will be performed by eBay for managed payments sellers selling internationally. Currency conversion comes into play when a buyer is refunded.
To support this new capability, the following containers/fields were added:
- Amount.exchangeRate: exchangeRate field added to Amount type. This field is populated whenever currency conversion is necessary, such as in the case when a buyer refund occurs for an international order where the listing site's currency is different than the seller's default currency.
- actualRefund.feeCreditAmount: this container is returned in the 'Get Cancellation' method if a buyer refund for an eBay managed payments order was issued, and provides the amount of any selling fee credits due back to the seller per eBay policy.
- caseDetails.refundAmounts.feeCreditAmount: this container is returned in the 'Get Case' method if a buyer refund for an eBay managed payments order was issued, and provides the amount of any selling fee credits due back to the seller per eBay policy.
- inquiryDetails.refundAmounts.feeCreditAmount: this container is returned in the 'Get Inquiry' method if a buyer refund for an eBay managed payments order was issued, and provides the amount of any selling fee credits due back to the seller per eBay policy.
- actualRefund.feeCreditAmount: this container is returned in the 'Get Return' method if a buyer refund for an eBay managed payments order was issued, and provides the amount of any selling fee credits due back to the seller per eBay policy.
- actualRefundDetail.netChargeAmount: this container is returned in the 'Get Cancellation' method if a buyer refund for an eBay managed payments order was issued, and provides the 'net' charge to the seller for the buyer refund. The 'net' charge is calculated by subtracting any selling fee credits due back to the seller from the total amount of the refund. In the case of an international order refund where the the listing site's currency is different than the seller's default currency, the amount in both currencies are shown, as well as the exchange rate used to perform the currency conversion.
- caseDetails.refundChargeAmount: this container is returned in the 'Get Case' method if a buyer refund for an eBay managed payments order was issued, and provides the charge to the seller for the buyer refund. In the case of an international order refund where the the listing site's currency is different than the seller's default currency, the amount in both currencies are shown, as well as the exchange rate used to perform the currency conversion.
- inquiryDetails.refundChargeAmount: this container is returned in the 'Get Inquiry' method if a buyer refund for an eBay managed payments order was issued, and provides the charge to the seller for the buyer refund. In the case of an international order refund where the the listing site's currency is different than the seller's default currency, the amount in both currencies are shown, as well as the exchange rate used to perform the currency conversion.
- actualRefundDetail.netChargeAmount: this container is returned in the 'Get Return' method if a buyer refund for an eBay managed payments order was issued, and provides the 'net' charge to the seller for the buyer refund. The 'net' charge is calculated by subtracting any selling fee credits due back to the seller from the total amount of the refund. In the case of an international order refund where the the listing site's currency is different than the seller's default currency, the amount in both currencies are shown, as well as the exchange rate used to perform the currency conversion.
- appealDetails.appealRefundAmount: this container is returned in the 'Get Case' method if a seller appeals a case decision, wins the appeal, and is awarded a seller credit.
- appealDetails.appealRefundAmount: this container is returned in the 'Get Inquiry' method if a seller appeals a case decision, wins the appeal, and is awarded a seller credit.
Post-Order API – version 2.6
Schema Changes
| Name | Part of Schema | Type of Change |
|---|---|---|
ActualRefund |
Type | New |
ActualRefundDetail |
Type | New |
FundingMethodBrandEnum |
Type | New |
FundingMethodTypeEnum |
Type | New |
FundingSource |
Type | New |
FundingSourceType |
Type | New |
FundingStatusEnum |
Type | New |
RefundInfo |
Type | New |
RefundFundingType |
Type | New |
ActualRefundDetailType.fundings |
Field | New |
ActualRefundDetailType.outstandingAmount |
Field | New |
CancelDetail.refundInfo |
Field | New |
MoneyMovementEntry.fundingSource |
Field | New |
MoneyMovementEntry.fundingStatus |
Field | New |
CancelCloseReasonEnum.FULL_REFUNDED_AS_PAYOUT |
Enum | New |
CancelCloseReasonEnum.PAYOUT_FAILED |
Enum | New |
CancelCloseReasonEnum.SELLER_CANCEL_UNPAID |
Enum | New |
RefundPaymentTypeEnum.INTERMEDIATED_REFUND |
Enum | New |
Changed Methods
New eBay managed payments schema added for buyer refunds
New eBay managed payments schema added to four 'Get' calls to indicate the seller payment source that is being used to fund a buyer refund. This new schema is only applicable in the case of a buyer refund coming from a seller who is opted in to eBay managed payments. eBay managed payments is currently only available to some sellers on the eBay US and eBay Germany marketplaces, and this capability is scheduled to roll out to sellers on the eBay UK, eBay Canada, and eBay Australia marketplaces in July 2020.
The new containers and fields are summarized below
- cancelDetail.refundInfo: this container is returned in the 'Get a Cancellation Request' method if a buyer refund for an eBay managed payment was issued, or is scheduled to be issued for a cancelled order.
- moneyMovementEntryList.fundingSource: this container is returned in the 'Get Case' method if a buyer refund for an eBay managed payment was issued, and provides details about the seller's funding source to issue the refund.
- moneyMovementEntryList.fundingStatus: this field is returned in the 'Get Case' method if a buyer refund for an eBay managed payment was issued, and provides the status of the refund.
- moneyMovementEntryList.fundingSource: this container is returned in the 'Get Inquiry' method if a buyer refund for an eBay managed payment was issued, and provides details about the seller's funding source to issue the refund.
- moneyMovementEntryList.fundingStatus: this field is returned in the 'Get Inquiry' method if a buyer refund for an eBay managed payment was issued, and provides the status of the refund.
- actualRefundDetail.fundings: this array is returned in the 'Get Return' method if a buyer refund for an eBay managed payment was issued, and provides details about the seller's funding source to issue the refund.
- actualRefundDetail.fundings: this field is returned in the 'Get Return' method if a buyer refund for an eBay managed payment was issued, and provides the amount still due to the buyer (if any) for a buyer refund.
Four new error codes added
The following four error codes were added with this release:
- 292050: The tracking number cannot exceed {0} characters.
- 292051: Refund failure due to insufficient funds awaiting payout. Please add a payment instrument and try again.
- 292052: We were unable to charge your payment instrument. Please update your payment instrument and try again.
- 292053: We couldn't process your refund. Please try again or contact us for help.
Post-Order API – version 2.5
This release updates the Cancellation and Return services in Post-Order API, Version 2.5
Note that this release does not introduce any new methods to the Post-Order API.
Cancellation schema updates
There are three types of updates to the Cancellation schema: new schema objects, updated object types, and updated values supported in enumeration types. Please see the Post-Order API Reference for details on these new and updated types.
New Cancellation object types
This update introduces the following new complex object and enumeration types in the Cancellation resource:
- ErrorData (plus three supporting types)
- MoneyMovementDetailType
- PayoutRecoupInfo
- RelistLineItem
- MoneyMovementTypeEnum
- EligibilityCheckTypeEnum
- MoneyMovementStatusEnum
- PartialOrderTypeEnum
- RelistStatusEnum
- UserRoleFilterEnum
Updated Cancellation object types
- The search request has a new query parameter, role.
- The cancelDetail object has the following new response fields: buyerLoginName, cancelState, cancelStatus, moneyMovementInfo, partialOrderType, payoutRecoupInfo, sellerLoginName
- The cancelSummary object has the following new response fields: buyerLoginName, cancelState, cancelStatus, partialOrderType, payoutRecoupInfo, sellerLoginName
- The CreateCancelRequest object has the following new input field: relistLineItem
- The CreateCancelResponse object has the following new response field: warnings
- The ItemEligibilityResult object has the following new response field: cancelQuanity
Updated values in Cancellation enumeration types
The following enumeration types have updated values, please see the documentation for details:
- CancelActivityTypeEnum
New values: SYSTEM_TIMEOUT_FOR_NOTIFY_REFUND_STATUS, SYSTEM_PAYOUT, SYSTEM_NOTIFY_PAYOUT_STATUS, SYSTEM_TIMEOUT_FOR_NOTIFY_PAYOUT_STATUS, SYSTEM_CHARGEBACK_OPENED - CancelCloseReasonEnum
New values: FULL_REFUNDED_T2_FAILED, FULL_REFUNDED_T2_ONLY, CHARGEBACK_DISPUTE_FILED - CancelReasonEnum
New values: BUYER_ASKED_CANCEL, ADDRESS_ISSUES, ORDER_UNPAID
Removed values: ORDER_MISTAKE, PRICE_TOO_HIGH, FOUND_CHEAPER_PRICE, WONT_ARRIVE_IN_TIME, BUYER_CANCEL_OR_ADDRESS_ISSUE, OTHER - EligibilityFailureReasonEnum
New values: DELETED_BUYER, PAYMENT_PENDING, CHARGEBACK_OPENED, PARTIAL_CANCEL_NOT_ALLOWED, PARTIAL_QUANTITY_NOT_ALLOWED, REQUESTED_QUANTITY_NOT_AVAILABLE, ITEM_LEVEL_ELIGIBILITY_FAILURE, INVALID_LINEITEM, DUPLICATE_LINEITEM, FULL_REFUNDED_LINEITEM - PaymentStatusEnum
New values: ONLINE_PAID
Return schema updates
There are three types of updates to the Return schema: new schema objects, updated object types, and updated values supported in enumeration types. Please see the Post-Order API Reference for details on these new and updated types.
New Return object types
This update introduces the following new complex object and enumeration types in the Return resource:
- ReturnPayoutRecoupInfoType
- RefundDeductionType
- Refund_MoneyMovementStatusEnum
- ReturnReasonTypeEnum
- ShippingLabelFormatEnum
- UserRoleFilterEnum
Updated Return object types
The following object types have been updated in this release:
- The search method query parameters have been updated to include the order_id, return_id, role, and states options.
- The DecideReturnRequest object has the following new request fields: keepOriginalItem, rMAProvided
- The GetShippingLabelResponse object has the following new response field: labelFormat
- The IssueRefundRequest object has the following new request field: sessionId
- The ResponseHistoryAttributesType object has the following new request fields: keepOriginalItem, refundDeductionType
- The ReturnCloseInfoType object has the following new response field: returnCloseDate
- The ReturnCreationInfoType object has the following new response field: reasonType
- The ReturnDetailType object has the following new response field: payoutRecoupInfo
- The ReturnFileType object has the following new fields: fielName, secureUrl
- The ReturnShippingCostDetailType object has the following new field: subsidyAmount
- The ReturnSummaryType object has the following new request fields: orderId, timeoutDate
Updated values in Return enumeration types
The following enumeration types have updated values, please see the documentation for details:
- ActivityOptionEnum
New values: UPDATE_RETURN_SHIPPING_CARRIER, TIME_OUT_AFTER_REFUNDED_AS_PAYOUT, SYSTEM_IMMEDIATE_REFUND, SYSTEM_BUYER_REFUND_AS_PAYOUT, SYSTEM_BUYER_PARTIAL_REFUND_AS_PAYOUT, SELLER_RETRY_REFUND, CHARGEBACK_OPEN - BuyerCloseReturnReasonEnum
New values: CHARGE_BACK_OPENED - CloseReturnReasonEnum
New values: LVT_IMMEDIATE_REFUND, BUYER_REFUND_AS_PAYOUT, BUYER_PARTIAL_REFUND_AS_PAYOUT, CHARGEBACK_DISPUTE_FILED - EligibilityCheckTypeEnum
New values: UNPAID_TRANSACTION, RETURN_REASON_SELECTION - EscalateReasonEnum
New values: NEW_ITEM_NOT_RECEIVED, RECEIVED_WRONG_ITEM - FilePurposeEnum
New values: REFUND_RELATED - MoneyMovementStatusEnum
New values: REVERSED, TIMEDOUT - MoneyMovementTypeEnum
New values: LVT_IMMEDIATE_REFUND, REFUND_IMPORT_TAX_FEE, BUYER_REFUND_AS_PAYOUT, BUYER_PARTIAL_REFUND_AS_PAYOUT, RECOUP_FROM_SELLER_T1, REFUND_PPF, REFUND_STATE_TAX, REFUND_SNAD_FVF, REFUND_SNAD_FVF_SHIPPING - RefundFeeTypeEnum
New values: ITEM_IMPORT_TAX, SHIPPING_IMPORT_TAX, ITEM_TAX, SHIPPING_TAX - ReturnCountFilterEnum
New values: SELLER_ACTION_DUE, SELLER_ACTION_OVERDUE, SELLER_NO_ACTION, EBAY_PLUS - ReturnStateEnum
New values: REPLACEMENT_LABEL_PENDING, REPLACEMENT_LABEL_PENDING_TIMEOUT, PARTIAL_REFUND_AS_PAYOUT_INITIATED, REPLACEMENT_OFFER_PENDING, REFUND_AS_PAYOUT_INITIATED, REFUND_FAILED - ShippingCarrierEnum
New values: POSTE, BARTOLINI, NEXIVE, LA_POSTE, MONDIAL_RELAY, COLISSIMO, CORREOS, SEUR, MRW - StatusType
New values: WARNING
Return Rules schema updates
All the methods and types defined for the RULES resource have been deprecated and removed from the schema and documentation.
The functionality for return rules continues to be supported and updated in Seller Hub, where sellers can establish and maintain the rules by which they want to handle order returns.
Documentation changes and errata
The following method response fields in the Cancellation resource have been removed from the Post-Order API Reference documentation:
- cancelDetail.itemId
- cancelDetail.state (use cancelState instead)
- cancelDetail.status (use cancelStatus instead)
- cancelDetail.transactionId
- cancelSummary.state (use cancelState instead)
- cancelSummary.status (use cancelStatus instead)
Post-Order API – version 2.4
This Post-Order API, Version 2 feature update gives sellers the ability to automatically relist an item when they issue a refund.
New features
Auto-relist an item when a refund is issued for a return
Sellers now have the ability to request that an item be automatically relisted when the seller issues a refund for a returned item.
The new Boolean relistItem field in the POST /post-order/v2/return/{returnId}/issue_refund call lets sellers indicate that they want eBay to automatically relist the returned item when the seller issues the refund for the return.
Sellers can check the eligibility for an item to be relisted by calling Get Return. In the response, check the itemDetail.relistStatus field for eligibility. This field will also show the status of a relist request as either SUCCESS (the relist succeeded) or FAILED (the relist request did not succeed).
If the relist request succeeds, call Get Return and check the itemDetail.relistedItemId to get the listing ID of the newly relisted item (the ID should match the ID of the original item listing).
Index of Changed Calls
This release adds new fields to the following two operations in order returns:
Schema Changes
This release has the following schema updates:
- GET /post-order/v2/return/{returnId} adds the following return fields:
- POST /post-order/v2/return/{returnId}/issue_refund adds the following input field:
Post-Order API – version 2.3
This Post-Order API, Version 2 feature update gives sellers the ability to add return instructions for buyers.
New features
Sellers can add return instructions for buyers
Seller can specify return instructions using the comments.content field of the POST /post-order/v2/return/{returnId}/decide call. Added comments are displayed on the Return Details page when the buyer visits the page to retrieve their return shipping label.
Note that the content field is not new, but the functionality to display the comments to the buyer has been added starting in January 2019.
Documentation changes and errata
The Processing return requests section of the Features Guide has been updated to clarify the API flows for item returns. Please review the new flows if you (the seller) provide your own shipping labels or if you use eBay-supplied labels.
Post-Order API – version 2.2
This is a feature update for the Post-Order API, Version 2.
Index of Changed Calls
This release adds new upload seller shipping label functionality to the Post-Order API.
New Calls
None
Changed Calls
- POST /post-order/v2/return/{returnId}/add_shipping_label
- POST /post-order/v2/return/{returnId}/file/upload
- POST /post-order/v2/return
- GET /post-order/v2/return/{returnId}
Schema Changes
| Name | Part of Schema | Type of Change |
|---|---|---|
LabelActionEnum |
Enumerated type | New |
NoSellerUploadLabelReasonEnum |
Enumerated type | New |
ProvideLabelRequest.forwardShippingLabelProvided |
Element | New |
ProvideLabelRequest.labelAction |
Element | New |
ProvideLabelRequest.noLabelReason |
Element | New |
ReturnHoldInfoType.holdTransactionId |
Element | New |
New Features
Sellers Can Provide Own Shipping Labels to Buyers
The POST /post-order/v2/return/{returnId}/add_shipping_label call was enhanced to enable the seller to provide their own shipping labels to buyers for return shipping. To do this, the seller first uses the POST /post-order/v2/return/{returnId}/file/upload call to upload a scanned image of the seller's shipping label to the return request. Then, the seller uses the POST /post-order/v2/return/{returnId}/add_shipping_label call to make this shipping label available to the buyer. See the POST /post-order/v2/return/{returnId}/add_shipping_label sample to find out more about how this is done.
Other Enhancements to "add_shipping_label" Call
In addition to being able to provide a seller-generated shipping label to the buyer, the new labelAction field in the POST /post-order/v2/return/{returnId}/add_shipping_label call allows the seller to perform the following actions:
- Inform the buyer to use the eBay return shipping label
- Inform the buyer that the seller-generated shipping label has already been sent
- Inform the buyer that no shipping label is available (and state the reason through the noLabelReason field
- Instruct the buyer to purchase their own shipping label, but the seller will reimburse them for the return shipping cost
New holdTransactionId Field
New holdTransactionId field is conditionally returned in the POST /post-order/v2/return and GET /post-order/v2/return/{returnId} calls if a return request has been placed in hold status.
Documentation Changes and Errata
Shipping Returns Section of Features Guide Updated
The Shipping returns section of the Features Guide was updated to account for the new upload seller shipping label functionality.
Return Call Samples Updated
The POST /post-order/v2/return/{returnId}/file/upload and POST /post-order/v2/return/{returnId}/add_shipping_label call samples have been updated to account for the new upload seller shipping label functionality.
Various Documentation Updates
The API Reference, the Usage Guide, and the Post-Order content of the eBay Features Guide have been revised and extended for clarity and accuracy as of December 3, 2015. Existing code should still behave the same.
Post-Order API – version 2.1
This is a feature update for the Post-Order API, Version 2.
Index of Changed Calls
This release adds new operations for order inquiries (/inquiry)and order escalations (/casemanagement) to the Post-Order API.
New Calls
- POST /post-order/v2/inquiry/
- GET /post-order/v2/inquiry/{inquiryId}
- POST /post-order/v2/inquiry/{inquiryId}/check_eligibility
- POST /post-order/v2/inquiry/{inquiryId}/close
- POST /post-order/v2/inquiry/{inquiryId}/confirm_refund
- POST /post-order/v2/inquiry/{inquiryId}/escalate
- POST /post-order/v2/inquiry/{inquiryId}/issue_refund
- POST /post-order/v2/inquiry/{inquiryId}/provide_refund_info
- POST /post-order/v2/inquiry/{inquiryId}/provide_shipment_info
- POST /post-order/v2/inquiry/{inquiryId}/send_message
- POST /post-order/v2/casemanagement/appeal
- POST /post-order/v2/casemanagement/close
- POST /post-order/v2/casemanagement/issue_refund
- POST /post-order/v2/casemanagement/provide_return_address
- POST /post-order/v2/casemanagement/provide_shipment_info
- GET /post-order/v2/casemanagement/{caseId}
New Features
This release contains several new operations that offer flows for order inquiries and escalations.
See the New Calls section for a complete list of the new operations, and the Usage Guide for details on the newly supported use cases.
Documentation Changes and Errata
The documentation has been updated to support the new inquiry and escalation operations and use cases.
Initial Version 2 Release – version 2.0
This is the initial release of the Post-Order API, Version 2.
Index of Changed Calls
The following /return and /cancellation operations are included in this initial release of the Post-Order API, Version 2.
New Calls
- POST /post-order/v2/cancellation/cancel
- POST /post-order/v2/cancellation/check_eligibility
- GET /post-order/v2/cancellation/search
- GET /post-order/v2/cancellation/{cancelId}
- POST /post-order/v2/cancellation/{cancelId}/approve
- POST /post-order/v2/cancellation/{cancelId}/confirm
- POST /post-order/v2/cancellation/{cancelId}/reject
- POST /post-order/v2/return
- POST /post-order/v2/return/check_eligibility
- POST /post-order/v2/return/draft
- GET /post-order/v2/return/draft/{draftId}
- PUT /post-order/v2/return/draft/{draftId}
- POST /post-order/v2/return/draft/{draftId}/file/upload
- DELETE /post-order/v2/return/draft/{draftId}/file/{fileId}
- GET /post-order/v2/return/draft/{draftId}/files
- POST /post-order/v2/return/estimate
- GET /post-order/v2/return/metadata/{metadataKey}
- GET /post-order/v2/return/search
- GET /post-order/v2/return/{returnId}
- POST /post-order/v2/return/{returnId}/add_shipping_label
- POST /post-order/v2/return/{returnId}/cancel
- GET /post-order/v2/return/{returnId}/check_label_print_eligibility
- POST /post-order/v2/return/{returnId}/decide
- POST /post-order/v2/return/{returnId}/escalate
- POST /post-order/v2/return/{returnId}/file/submit
- POST /post-order/v2/return/{returnId}/file/upload
- DELETE /post-order/v2/return/{returnId}/file/{fileId}
- GET /post-order/v2/return/{returnId}/files
- GET /post-order/v2/return/{returnId}/get_shipping_label
- POST /post-order/v2/return/{returnId}/initiate_shipping_label
- POST /post-order/v2/return/{returnId}/issue_refund
- POST /post-order/v2/return/{returnId}/mark_as_received
- POST /post-order/v2/return/{returnId}/mark_as_shipped
- POST /post-order/v2/return/{returnId}/mark_refund_received
- POST /post-order/v2/return/{returnId}/mark_refund_sent
- POST /post-order/v2/return/{returnId}/send_message
- POST /post-order/v2/return/{returnId}/send_shipping_label
- GET /post-order/v2/return/{returnId}/tracking
- POST /post-order/v2/return/{returnId}/void_shipping_label