Search for eBay inventory items

Fetch a specific eBay inventory item by SKU

Generate the eBay OAuth authorization URL for user consent. The user should open this URL in a browser to grant permissions to the application. This supports the OAuth 2.0 Authorization Code grant flow. The redirect URI can be provided as a parameter or will be read from EBAY_REDIRECT_URI environment variable.

IMPORTANT: eBay has different OAuth scopes available for production vs sandbox environments:

• Sandbox includes additional Buy API scopes (e.g., buy.order.readonly, buy.guest.order, buy.shopping.cart) and extended Identity scopes

• Production includes sell.edelivery, commerce.message (explicit), and commerce.shipping scopes not available in sandbox

• If you provide custom scopes, they will be validated against the current environment (set via EBAY_ENVIRONMENT). Any scopes not valid for the environment will generate warnings.

OAUTH FLOW INSTRUCTIONS:

1. Generate OAuth URL with this tool (optionally specify scopes)

2. User opens URL in browser, authorizes, and gets redirected with a code parameter

3. Use ebay_exchange_authorization_code tool with the code (URL-encoded format accepted)

4. Tokens are automatically stored and will auto-refresh every 2 hours

COMMON SCOPES:

• Basic (always included): https://api.ebay.com/oauth/api_scope

• Inventory: https://api.ebay.com/oauth/api_scope/sell.inventory

• Inventory (readonly): https://api.ebay.com/oauth/api_scope/sell.inventory.readonly

• Account: https://api.ebay.com/oauth/api_scope/sell.account

• Fulfillment: https://api.ebay.com/oauth/api_scope/sell.fulfillment

TROUBLESHOOTING:

• Authorization codes expire in ~5 minutes - get fresh code if "invalid grant" error

• "Insufficient permissions" errors mean you need to re-authorize with additional scopes

• OAuth URL format: Use + to separate scopes (e.g., scope=scope1+scope2), not %2B

• Refresh tokens last 18 months and are saved to .env file for persistence

Set the user access token and refresh token for authenticated API requests. These tokens should be obtained through the OAuth authorization code flow. Tokens will be persisted to disk and automatically refreshed when needed. User tokens provide higher rate limits (10,000-50,000 requests/day) compared to client credentials (1,000 requests/day).

Set user access and refresh tokens with custom expiry times. This is an enhanced version of ebay_set_user_tokens that accepts expiry times and can automatically refresh the access token if it's expired but the refresh token is valid. Useful when user provides tokens that may already be partially expired.

Check the current OAuth token status. Returns information about whether user tokens or client credentials are being used, and whether tokens are valid.

Clear all stored OAuth tokens (both user tokens and client credentials). This will require re-authentication for subsequent API calls.

Validate token expiry times and get recommendations. Checks if access/refresh tokens are expired or expiring soon, and provides actionable recommendations (e.g., refresh access token, re-authorize user).

Convert a date string or number to Unix timestamp (milliseconds). Supports ISO 8601 dates, Unix timestamps (seconds or milliseconds), and relative time (e.g., "in 2 hours", "in 7200 seconds"). Useful when setting token expiry times from user input.

Display all eBay API credentials and current token information. Shows client ID, client secret (masked), environment (production/sandbox), redirect URI, and current token status including access token (masked), refresh token (masked), app token (masked), and their expiry times. Useful for debugging authentication issues and verifying configuration.

Manually refresh the user access token using the stored refresh token. This is useful when you want to proactively refresh an access token before it expires, or when recovering from authentication errors. Requires that user tokens are already set (either via EBAY_USER_REFRESH_TOKEN in .env or via ebay_set_user_tokens_with_expiry). Returns the new access token and expiry time.

Exchange an OAuth authorization code for access and refresh tokens. This completes the OAuth 2.0 Authorization Code grant flow. After the user authorizes the application using the URL from ebay_get_oauth_url, eBay redirects back with an authorization code in the URL. Use this tool to exchange that code for tokens that can be used to make API calls. The tokens will be automatically stored and used for subsequent API requests.

IMPORTANT NOTES:

• Authorization codes expire in ~5 minutes - if you get "invalid grant" error, get a fresh code

• Codes can be URL-encoded (e.g., v%5E1.1%23...) - this tool automatically decodes them

• Extract the code parameter from the redirect URL (your RuName Accept URL): https://your-redirect-uri?code=YOUR_CODE&expires_in=299

• Tokens are saved to .env file and will auto-refresh every 2 hours

• Refresh tokens last 18 months before requiring re-authorization

COMMON ERRORS:

• "invalid or was issued to another client": Code expired, get fresh code

• "Insufficient permissions": Re-run OAuth flow with additional scopes in ebay_get_oauth_url

For complete OAuth guide with scopes, troubleshooting, and examples, see: docs/auth/OAUTH_QUICK_REFERENCE.md

Retrieve custom policies defined for the seller account

Get fulfillment policies for the seller.

Required OAuth Scope: sell.account.readonly or sell.account Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.account.readonly

Get payment policies for the seller

Get return policies for the seller

Create a new fulfillment policy.

Required OAuth Scope: sell.account Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.account

Get a specific fulfillment policy by ID

Get a fulfillment policy by name

Update an existing fulfillment policy

Delete a fulfillment policy

Create a new payment policy

Get a specific payment policy by ID

Get a payment policy by name

Update an existing payment policy

Delete a payment policy

Create a new return policy

Get a specific return policy by ID

Get a return policy by name

Update an existing return policy

Delete a return policy

Create a new custom policy

Get a specific custom policy by ID

Update an existing custom policy

Delete a custom policy

Get seller KYC (Know Your Customer) status

Opt-in to a payments program

Get payments program status

Get seller rate tables

Create or replace sales tax table for a jurisdiction

Bulk create or replace sales tax tables

Delete sales tax table for a jurisdiction

Get sales tax table for a jurisdiction

Get all sales tax tables for a country

Get seller subscription information

Opt-in to a seller program

Opt-out of a seller program

Get seller programs the account is opted into

Get seller's current set of privileges, including whether or not the seller's eBay registration has been completed, as well as the details of their site-wide sellingLimit (the maximum dollar value and quantity of items a seller can sell per day).

Required OAuth Scope: sell.account.readonly or sell.account

Check the seller eligibility status for eBay advertising programs. This allows developers to determine if a seller is eligible for various advertising programs on eBay.

Required OAuth Scope: sell.account.readonly or sell.account

Get payments program status for a marketplace. Note: This method is deprecated as all seller accounts globally have been enabled for the new eBay payment and checkout flow.

Required OAuth Scope: sell.account.readonly or sell.account

Get payments program onboarding information. Note: This method is deprecated as all seller accounts globally have been enabled for the new eBay payment and checkout flow.

Required OAuth Scope: sell.account.readonly or sell.account

Retrieve all inventory items for the seller.

Required OAuth Scope: sell.inventory.readonly or sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory.readonly

Get a specific inventory item by SKU.

Required OAuth Scope: sell.inventory.readonly or sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory.readonly

Create or replace an inventory item.

Required OAuth Scope: sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory

Delete an inventory item by SKU.

Required OAuth Scope: sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory

Get all offers for the seller

Create a new offer for an inventory item

Publish an offer to create a listing

Bulk create or replace multiple inventory items

Bulk get multiple inventory items

Bulk update price and quantity for multiple offers

Get product compatibility information for an inventory item

Create or replace product compatibility for an inventory item

Delete product compatibility for an inventory item

Get an inventory item group (variation group)

Create or replace an inventory item group

Delete an inventory item group

Get all inventory locations

Get a specific inventory location

Create or replace an inventory location

Delete an inventory location

Disable an inventory location

Enable an inventory location

Update location details for an inventory location

Get a specific offer by ID

Update an existing offer

Delete an offer

Withdraw a published offer

Bulk create multiple offers

Bulk publish multiple offers

Get listing fees for offers before publishing

Bulk migrate listings to the inventory model

Get inventory locations for a specific listing (SKU location mapping).

Required OAuth Scope: sell.inventory.readonly or sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory.readonly

Create or replace SKU location mapping for a listing. Maps a SKU to multiple fulfillment center locations.

Required OAuth Scope: sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory

Delete SKU location mapping for a listing. Removes all fulfillment center location mappings for a SKU.

Required OAuth Scope: sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory

Publish an offer for an inventory item group (variation listing).

Required OAuth Scope: sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory

Withdraw an offer for an inventory item group (variation listing).

Required OAuth Scope: sell.inventory Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.inventory

Retrieve orders for the seller.

Required OAuth Scope: sell.fulfillment.readonly or sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly

Get details of a specific order.

Required OAuth Scope: sell.fulfillment.readonly or sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly

Create a shipping fulfillment for an order.

Required OAuth Scope: sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment

Get all shipping fulfillments for an order.

Required OAuth Scope: sell.fulfillment.readonly or sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly

Get a specific shipping fulfillment by ID.

Required OAuth Scope: sell.fulfillment.readonly or sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly

Issue a full or partial refund for an eBay order. Use this to refund buyers for orders, including specifying the refund amount and reason.

Required OAuth Scope: sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment

Get summaries of all payment disputes. Use filters to narrow results by dispute status, buyer username, or order ID.

Required OAuth Scope: sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment

Get detailed information about a specific payment dispute.

Required OAuth Scope: sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment

Get activity history for a payment dispute, including all actions taken by buyer, seller, and eBay.

Required OAuth Scope: sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment

Accept a payment dispute and allow eBay to refund the buyer. Use this when you agree with the buyer claim.

Required OAuth Scope: sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment

Contest a payment dispute by providing evidence. Use this when you disagree with the buyer claim and want to provide proof.

Required OAuth Scope: sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment

Add evidence to support your case in a payment dispute. Provide evidence files and supporting information.

Required OAuth Scope: sell.fulfillment Minimum Scope: https://api.ebay.com/oauth/api_scope/sell.fulfillment