eBay Getting Started: API Integration Guide (2026)

Getting started overview

Integrating with eBay's APIs involves a structured process that begins with setting up a developer account, generating application keys, and understanding the authentication mechanisms. The eBay Developer Program provides a suite of APIs designed to support various marketplace operations, from managing seller listings to automating buyer interactions. Developers can access these APIs to build applications that enhance their eBay experience or create tools for other users.

To ensure a smooth integration, eBay offers a sandbox environment for testing API calls without affecting live marketplace data. This environment is crucial for development and debugging before deploying to production. The primary authentication method for eBay APIs is OAuth 2.0, which secures access to user-specific data and actions. Understanding the OAuth 2.0 authorization flow, including obtaining user consent and exchanging authorization codes for access tokens, is fundamental for most eBay API interactions.

This guide outlines the essential steps to get an eBay API integration operational, from initial account setup to making your first successful API request. It covers the creation of developer accounts, generation of application keys, and the basic structure of an authenticated API call. For detailed information on specific API endpoints and data models, refer to the official eBay API documentation.

Create an account and get keys

To begin using the eBay APIs, you must first register for an eBay Developer Program account and create an application. This process provides you with the necessary credentials to authenticate your API requests.

Step 1: Register for an eBay Developer Account

1. Navigate to the eBay Developer Program website.
2. Click on 'Register' or 'Sign In' if you already have an eBay user account. You will typically use your standard eBay user credentials to log in to the developer portal.
3. Complete the registration process, which may include agreeing to the eBay API License Agreement.

Step 2: Create an Application and Generate Keys

Once registered and logged into the developer portal, you will need to create an application to obtain your API keys.

1. From your developer account dashboard, locate the 'Application Keys' or 'My Apps' section.
2. Click 'Create a new application'.
3. Provide a unique application name. This name helps you identify your application within the developer portal.
4. eBay will generate a set of application keys for both the sandbox (testing) and production environments. These typically include:
• App ID (Client ID): A unique identifier for your application.
• Dev ID: An identifier for your developer account.
• Cert ID (Client Secret): A confidential key used with your App ID for authentication.
5. Store these keys securely. The Cert ID, especially, should be treated as sensitive information and never exposed in client-side code.

Step 3: Configure Redirect URIs for OAuth 2.0

For APIs that require user authorization (e.g., managing a seller's listings), you will need to configure Redirect URIs. These URIs are callback URLs where eBay redirects the user after they grant or deny authorization to your application.

1. In your application settings within the developer portal, find the OAuth Redirect URI settings.
2. Add the URL(s) where your application will receive the authorization code after a user grants consent. For local development, you might use http://localhost:8080/callback or similar.
3. Ensure these URIs are correctly configured for both your sandbox and production environments.

Your first request

Making your first API request involves selecting an API, authenticating, and constructing the request. This example focuses on using the Buy API's Browse endpoint, which typically requires only application-level authentication (client credentials flow) for public data.

Authentication: Client Credentials Flow (Application Access Token)

Many eBay APIs, especially those for public data access (like browsing listings), use the client credentials flow to obtain an application access token. This token grants your application access to non-user-specific resources.

1. Obtain an Application Access Token

To get an application access token, you make a POST request to the eBay OAuth token endpoint. You will use your App ID (Client ID) and Cert ID (Client Secret) for basic authentication.

curl -X POST 'https://api.ebay.com/identity/v1/oauth2/token'
  -H 'Content-Type: application/x-www-form-urlencoded'
  -H 'Authorization: Basic <Base64EncodedAppID:CertID>'
  -d 'grant_type=client_credentials&scope=https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope'

Replace <Base64EncodedAppID:CertID> with the Base64 encoding of your App ID and Cert ID joined by a colon (e.g., base64.b64encode(b'YOUR_APP_ID:YOUR_CERT_ID').decode('utf-8') in Python). The response will contain an access_token and its expires_in duration.

2. Make a Simple Browse API Request

With your application access token, you can now make a request to a public API endpoint. Let's use the Browse API to retrieve details for a specific item.

curl -X GET 'https://api.ebay.com/buy/browse/v1/item/v1|225916053351|0'
  -H 'Authorization: Bearer <YourApplicationAccessToken>'
  -H 'X-EBAY-C-MARKETPLACE-ID: EBAY_US'
  -H 'Content-Type: application/json'

Replace <YourApplicationAccessToken> with the token obtained in the previous step. The item ID v1|225916053351|0 is an example for demonstration purposes. The X-EBAY-C-MARKETPLACE-ID header specifies the eBay marketplace (e.g., EBAY_US for the United States). The response will be a JSON object containing item details.

Common next steps

After successfully making your first API call, consider these next steps to further develop your eBay integration:

Troubleshooting the first call

Encountering issues during your initial API calls is common. Here are some troubleshooting tips for eBay API integrations:

• Authentication Errors (401 Unauthorized):
  • Incorrect Credentials: Double-check your App ID, Cert ID, and Dev ID. Ensure they are correctly Base64 encoded for the Authorization: Basic header in the token request.
  • Expired Token: Access tokens have a limited lifespan. Ensure you are using a fresh token. Implement logic to refresh tokens before they expire.
  • Missing Bearer Prefix: For API calls using an access token, ensure the Authorization header is formatted as Bearer <YourAccessToken>.
  • Wrong Environment: Verify you are using sandbox keys for sandbox endpoints and production keys for production endpoints.
• Bad Request Errors (400 Bad Request):
  • Missing Required Headers: Some APIs require specific headers, such as X-EBAY-C-MARKETPLACE-ID. Consult the API Reference for required headers.
  • Invalid JSON Payload: If sending a POST/PUT request with a JSON body, ensure it is syntactically correct and adheres to the API's schema. Use a JSON validator if unsure.
  • Incorrect Parameters: Verify that all query parameters and request body fields match the API documentation's specifications, including data types and allowed values.
• Forbidden Errors (403 Forbidden):
  • Insufficient Scope: The access token might not have the necessary scopes to perform the requested action. Review the required scopes for the specific API call.
  • User Consent: For actions on behalf of a specific eBay user, ensure the user has granted your application permission (via the OAuth 2.0 authorization code flow).
  • Rate Limits: You might have exceeded the API's daily request limit. Check the X-EBAY-C-RATE-LIMIT- headers in responses for rate limit information.
• Not Found Errors (404 Not Found):
  • Incorrect Endpoint URL: Verify the API endpoint URL is accurate and matches the documentation.
  • Invalid Resource ID: If fetching a specific resource (e.g., an item), ensure the ID is valid and exists.
• Server Errors (5xx Errors):
  • These indicate an issue on eBay's side. While less common for initial setup, if encountered, check the eBay Developer System Status page for known outages or issues.
  • Implement retry logic with exponential backoff for transient server errors.
• Debugging Tools: Utilize tools like Postman, Insomnia, or browser developer tools (for web-based requests) to inspect request and response headers and bodies.