Register with eBay

Finances API

Fulfillment API

Post-Order API

Trading API

Payment services regulations applicable in the EU and the UK require all regulated Account Servicing Payment Service Providers (ASPSPs) to provide secure APIs that allow regulated Third Party Payment Providers (TPPs) to access account and payment services on behalf of account holders. The regulations further dictate that a TPP should be able to use a qualified certificate issued by any Electronic Identification, Authentication and Trust Services (eIDAS) Qualified Trust Service Provider (QTSP) in order to identify and authenticate themselves to an ASPSP.

This document provides information about how TPPs can register with eBay and obtain all necessary client details and tokens required to make API calls for clients domiciled in the EU or the UK.

NOTE: Each TPP may register up to 15 different applications provided each application has a unique software ID.

Production/Sandbox environments

In addition to its standard Production environment, eBay provides developers access to a Sandbox environment in which developers can test the behavior of their applications throughout development.

Registration process

This process applies to registering clients for both eBay's Production environment as well as eBay's Sandbox (test) environment.

NOTE: There are some minor differences in the procedure that are unique to the Sandbox environment. These will be identified and described where applicable.

Step 1: Register your client with eBay

TPPs in possession of a valid eIDAS Qualified Website Authentication Certificate (QWAC) may register their client with eBay using the Client Registration API which is based on, and conforms with, RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol (except as noted in the List of Deviations from RFC 7591). Requests that conform with RFC 7591 will be accepted, however some fields will be ignored.

NOTE: eBay does not support Qualified Electronic Seal (QSEAL) certificates.

Important! When calling the registerClient method, Third-Party Providers (TPPs) are required to pass their valid eIDAS certificate to eBay via Mutual Transport Layer Security (MTLS) handshake Certificate Request messages.

Refer to the Client Registration API reference documentation for complete information about using the API.

NOTE: Make note of the following values as they will be required in upcoming steps:

client_id value
client_secret value

Using Sandbox for testing

As mentioned above, developers who wish to test their applications may do so using eBay's Sandbox environment. However, in order to do so, the application must first be registered with eBay's Sandbox environment by calling the Register Client API using the following Sandbox Resource URI:

POST https://tppzsb.ebay.com/developer/registration/v1/client/register

Once the application has been successfully registered, login credentials for a Test User (i.e., username and password,) may then be ascertained. This is a fairly straightforward process that uses a portion of the client_ID returned by the API.

The prototype for both username and password is:

TESTUSER_{characters_following_SBX-_in_clientID}

For example, a registered application returns:

"clientId": "SMP01-clientid-SBX-abcde0123-4f56g789"

The corresponding Sandbox credentials would be:

username: TESTUSER_abcde0123-4f56g789

password: TESTUSER_abcde0123-4f56g789

Step 2: Obtain user consent

A TPP application must obtain the user's consent before it can make requests for that user.

Refer to Getting User Consent for complete information.

NOTE: Verify that the appropriate target endpoint is being used based on the environment for which the application is being registered.

Sandbox Environment: When obtaining consent within the Sandbox environment, when prompted, use the Sandbox credentials created in Step 1 above to login.

Once the user has granted their consent, the user is redirected per the first redirect_uri in the redirect_uris array returned by the Register Client API call. The single-use authorization code is returned as the code query parameter for the redirect_uri.

For example, the following redirect_uri is returned:

https://client.example.org/callback2?code=v********************D&expires_in=299

The authorization code is:

v********************D

The authorization code is required when creating a user access token in Step 3.

NOTE: This authorization code cannot be used to make API requests. A valid User Access Token is required.

Step 3: Create user access token

Finally, in order to make API calls, a User Access Token must be created/retrieved by issuing an Authorization Code Grant Request. The following previously generated and returned values are required as part of this request:

client_id (returned by the Client Registration API)
client_secret (returned by the Client Registration API)
authorization code (returned by User Consent in Step 2)

Refer to Exchanging the authorization code for a User access token for complete information.

NOTE: Verify that the appropriate target endpoint is being used based on the environment for which the application is being registered.

Step 4: Make API calls

Refer to the following tabs for complete information about making API calls within the Production and Sandbox environments:

Error codes

When issuing Finances, Fulfillment, Post-Order, and/or Trading API calls in either the Production or Sandbox environment, an error code may be returned if information is missing or improperly formatted, a certificate has expired, etc. Refer to the following table for information about these error codes.

Code	Meaning
215500	Caller is not registered
215501	Invalid license
215502	Certificate not issued by a valid Qtsp
215503	Certificate expired
215504	Certificate revoked
215506	Not a valid signature
215507	Role not matching
215508	Invalid certificate
215510	Missing certificate
215511	Internal errors as validating client certificate
215512	Internal errors as calling another service

Finances API

This page provides information required to call each method of the Finances API available for use by registered TPPs.

NOTE: When making the following call(s), it is imperative that the appropriate Resource URI listed for each method be used. Using a Gateway URI other than that listed below will result in failed calls.

The Finances API is used to retrieve detailed information on seller payouts for eBay orders, and also retrieve details on all monetary transactions on eBay's system between the seller, buyer, and eBay.

getPayout

This method retrieves details for a specific seller payout. The unique identfier of the payout is passed in as a path parameter at the end of the call URI.

Use the getPayouts method to retrieve unique identifiers of payouts.

Resource URI (Production): GET https://tppz.ebay.com/sell/finances/v1/payout/{payout_Id}
Resource URI (Sandbox): GET https://tppz.sandbox.ebay.com/sell/finances/v1/payout/{payout_Id}
Refer to the getPayout Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

getPayouts

This method is used to retrieve the details of one or more seller payouts.

Resource URI (Production): GET https://tppz.ebay.com/sell/finances/v1/payout?limit=integer&offset=integer&filter=FilterField&sort=SortField
Resource URI (Sandbox): GET https://tppz.sandbox.ebay.com/sell/finances/v1/payout?limit=integer&offset=integer&filter=FilterField&sort=SortField
Refer to the getPayouts Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

getPayoutSummary

This method is used to retrieve cumulative values for payouts in a particular state, or all states.

Resource URI (Production): GET https://tppz.ebay.com/sell/finances/v1/payout_summary?filter=FilterField
Resource URI (Sandbox): GET https://tppz.sandbox.ebay.com/sell/finances/v1/payout_summary?filter=FilterField
Refer to the getPayoutSummary Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

getSellerFundsSummary

This method retrieves all pending funds that have not yet been distibuted through a seller payout.

Resource URI (Production): GET https://tppz.ebay.com/sell/finances/v1/seller_funds_summary
Resource URI (Sandbox): GET https://tppz.sandbox.ebay.com/sell/finances/v1/seller_funds_summary
Refer to the getSellerFundsSummary Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

getTransactions

This method allows a seller to retrieve monetary transactions.

Resource URI (Production): GET https://tppz.ebay.com/sell/finances/v1/transaction?limit=integer&offset=integer&filter=FilterField&sort=SortField
Resource URI (Sandbox): GET https://tppz.sandbox.ebay.com/sell/finances/v1/transaction?limit=integer&offset=integer&filter=FilterField&sort=SortField
Refer to the getTransactions Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

getTransactionSummary

This method retrieves cumulative values for five types of monetary transactions: order sales, seller credits, buyer refunds, buyer-initiated payment disputes, shipping label purchases, and transfers.

Resource URI (Production): GET https://tppz.ebay.com/sell/finances/v1/transaction_summary?filter=FilterField
Resource URI (Sandbox): GET https://tppz.sandbox.ebay.com/sell/finances/v1/transaction_summary?filter=FilterField
Refer to the getTransactionSummary Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

getTransfer

This method retrieves detailed information regarding a TRANSFER transaction type.

Resource URI (Production): GET https://tppz.ebay.com/sell/finances/v1/transfer/{transfer_Id}
Resource URI (Sandbox): GET https://tppz.sandbox.ebay.com/sell/finances/v1/transfer/{transfer_Id}
Refer to the getTransfer Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

API Changes

For all the API changes, please refer to the Finances API Release Notes page. For all incompatible changes and API deprecations and decommissions, please refer to the API Deprecation Status page.

Fulfillment API

This page provides information required to call each method of the Fulfillment API available for use by registered TPPs.

The Fulfillment API is used to retrieve and fulfill orders, issue refunds, and manage third-party payment disputes initiated by buyers.

issueRefund

This method allows a seller to issue a full or partial refund to a buyer for an order.

Resource URI (Production): POST https://tpp.ebay.com/sell/fulfillment/v1/order/{order_id}/issue_refund
Resource URI (Sandbox): POST https://tpp.sandbox.ebay.com/sell/fulfillment/v1/order/{order_id}/issue_refund
Refer to the issueRefund Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

API Changes

For all the API changes, please refer to the Fulfillment API Release Notes page. For all incompatible changes and API deprecations and decommissions, please refer to the API Deprecation Status page.

Post-Order API

This page provides information required to call each method of the Post-Order API available for use by registered TPPs.

The Post-Order API allows a buyer to cancel, return, and inquire about orders.

Issue Inquiry Refund

This method allows a seller to issue a full refund to a buyer for a missing line item. This method will be used if the buyer is seeking a full refund for the missing line item and the seller has yet to ship the line item.

Resource URI (Production): POST https://tpp.ebay.com/post-order/v2/inquiry/{inquiryId}/issue_refund
Refer to the Issue Inquiry Refund Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

Issue Case Refund

This method issues a full refund to a buyer to resolve an Item Not Received (INR) or Return case that was filed against the seller.

Resource URI (Production): POST https://tpp.ebay.com/post-order/v2/casemanagement/{caseId}/issue_refund
Refer to the Issue Case Refund Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

Issue Return Refund

This method issues a refund to the buyer.

Resource URI (Production): POST https://tpp.ebay.com/post-order/v2/return/{returnId}/issue_refund
Refer to the Issue Return Refund Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

Process Return Request

This method is used by either a seller or buyer to perform an action against a return request.

Resource URI (Production): POST https://tpp.ebay.com/post-order/v2/return/{returnId}/decide
Refer to the Process Return Request Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

Create Cancellation Request

This method initiates an order cancellation on behalf of a seller and, if needed, can create an order cancellation on behalf of a buyer.

Resource URI (Production): POST https://tpp.ebay.com/post-order/v2/cancellation
Refer to the Create Cancellation Request Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

Approve Cancellation Request

This method approves a buyer's order cancellation request on behalf of the seller.

Resource URI (Production): POST https://tpp.ebay.com/post-order/v2/cancellation/{cancelId}/approve
Refer to the Approve Cancellation Request Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

API Changes

For all the API changes, please refer to the Post-Order API Release Notes page. For all incompatible changes and API deprecations and decommissions, please refer to the API Deprecation Status page.

Trading API

Tip: Although the GetAccount call of the Trading API is still supported, we strongly recommend that new developers and TPPs consider using the getTransactions method of the Finances API as an alternative. The getTransactions method has more robust search filters than GetAccount, and returns more detailed information about money that is exchanged between buyer, seller, and eBay.

This page provides information required to call each method of the Trading API available for use by registered TPPs.

NOTE: When making the following call(s), it is imperative that the appropriate URI listed for each method be used. Using a URI other than that listed below will result in failed calls.

The Trading API allows sellers to list and manage inventory, fulfill orders, and communicate with customers.

GetAccount

This method retrieves a seller's invoice data for their eBay account, including the account's summary data.

This method is available in two formats:

SOAP format
XML format

Information and required values are provided below in order to call GetAccount using either of these formats.

SOAP API URIs
- Production: https://tpp.ebay.com/wsapi
- Sandbox: https://tpp.sandbox.ebay.com/wsapi
XML API URIs
- Production: https://tpp.ebay.com/ws/api.dll
- Sandbox: https://tpp.sandbox.ebay.com/ws/api.dll
HTTP Headers:
- Required: X-EBAY-API-CALL-NAME:GetAccount
- Required: X-EBAY-API-IAF-TOKEN:{User Access Token}
- Recommended: X-EBAY-API-SITEID:{numeric site id}
  
  This is the numeric ID for the specific eBay site to which you want to send the request. Refer to SiteCodeType for the list of valid site ID values.
  
  Note that numeric values must be used. For example, for Australia, the Site ID value is 15.
Refer to the GetAccount Reference Documentation for additional information, including:
- URI parameters
- Request payload and fields
- Response payload and fields
- Status and error codes, and warnings

API Changes

For all the API changes, please refer to the Trading API Release Notes page. For all incompatible changes and API deprecations and decommissions, please refer to the API Deprecation Status page.