Configuration

The SDK ships with a configuration file that allows you to define your eBay OAuth credentials, client settings, webhook behavior, and OAuth scopes. This page describes each section of the configuration.

To publish the configuration file:

php artisan vendor:publish --tag=ebay-sdk-config

The configuration is located at:

config/ebay-sdk.php

OAuth / API Credentials

These values configure the OAuth client used by the SDK to authenticate with eBay. These values must match the settings in the eBay Developer Portal, regarding the used Target environment, of course.

'credentials' => [
    'client_id'     => env('EBAY_CLIENT_ID', null),
    'client_secret' => env('EBAY_CLIENT_SECRET', null),
    'redirect_uri'  => env('EBAY_REDIRECT_URI', null),
    'dev_id'        => env('EBAY_DEV_ID', null),
    'environment'   => env('EBAY_API_ENVIRONMENT', 'sandbox'),
],

Key	Value
client_id	Your eBay App’s Client ID (App ID)
client_secret	Your eBay App’s Client Secret (Cert ID)
redirect_uri	Your configured Redirect URI or RuName
dev_id	Your eBay App’s Dev ID (used for traditional calls only)
environment	Target API environment: sandbox or production

Client / Authentication Options

These options control request behavior, token caching, debugging, and localization.

'options' => [
    'caching' => (bool) env('EBAY_CACHING', true),
    'debug'   => (bool) env('EBAY_DEBUG', false),
    'locale'  => env('EBAY_LOCALE', 'en-US'),
],

Key	Value
caching	Enables automatic token caching
debug	Logs request and response data
locale	Sets the Content-Language header sent to eBay APIs

Traditional API (XML/SOAP) Settings

These settings are only relevant for eBay’s legacy “Traditional” APIs (XML/SOAP). They define the default request parameters and headers used for Trading API calls. All values can be overridden on a per-request basis using the corresponding set<Name>() methods on the individual request classes.

'traditional' => [
    'compatibility_level'   => env('EBAY_COMPATIBILITY_LEVEL', '1395'),
    'error_language'        => str_replace('-', '_', env('EBAY_LOCALE', 'en_US')),
    'error_handling'        => 'BestEffort',
    'site_id'               => env('EBAY_SITE_ID', 0),
    'warning_level'         => 'Low'
],

Key	Value
compatibility_level	eBay API schema version
error_language	Language for XML/SOAP error messages
error_handling	Partial-failure strategy
site_id	eBay marketplace ID
warning_level	Verbosity for warning messages

OAuth Route Configuration

This section controls whether the SDK should register its default OAuth routes and which middleware should be attached to them.

CAUTION

The default OAuth routes are for demonstration only and should not be used in a productive environment. We highly recommend your own setup to match your application’s security and UX requirements.

'oauth' => [
    'routes' => false,
    'middleware' => [
        'web',
        'auth',
        'throttle:30,1',
        //'can:request_token',
    ],
],

Key	Value
routes	Prevents the SDK from automatically registering OAuth routes.
middleware	Middleware stack applied to the built-in OAuth routes.

Marketplace Account Deletion Configuration

This section controls the built-in endpoint used for Marketplace Account Deletion / Closure notifications required by eBay. These notifications are sent when a user requests that their data must be removed from your application.

The SDK can register a reference implementation route that validates the endpoint, verifies signed requests, and dispatches Laravel events.

'marketplace_deletion' => [
    'routes' => false,
    'middleware' => [],
    'token' => env('EBAY_MARKETPLACE_DELETION_VERIFICATION_TOKEN', null),
    'endpoint' => env('EBAY_MARKETPLACE_DELETION_ENDPOINT', null),
    'public_key_cache_ttl' => 3600,
],

Key	Purpose
routes	Enables the built-in Marketplace Account Deletion endpoint
middleware	Middleware applied to the built-in deletion route
token	Verification token used during endpoint validation
endpoint	Absolute URL of the deletion endpoint
public_key_cache_ttl	Cache lifetime for eBay public keys used for signature verification

IMPORTANT

The endpoint value is used when generating the challenge response and must exactly match the endpoint configured in the eBay Developer Portal. If this value is null, the SDK will attempt to generate the URL automatically from the named route:

route('ebay-sdk.marketplace.deletion', absolute: true)

Setting the endpoint explicitly is recommended when using proxies, load balancers, tunnels, or custom domain setups.

Webhook Configuration

Controls the webhook handling for the eBay Platform Notifications (push).

TIP

We strongly recommend enabling the async queue worker if your event listeners perform expensive operations (such as additional HTTP or API calls). Otherwise, eBay may retry and resend the same notification when your endpoint takes too long to return a response.

'webhook' => [
    'routes' => false,
    'token'  => env('EBAY_WEBHOOK_TOKEN', ''),
    'async'  => false,
    'queue'  => 'default',
],

Key	Purpose
routes	Enables the built-in webhook endpoint
token	Optional shared secret for request validation
async	Dispatch notifications via queue instead of synchronous processing
queue	Queue name used when async mode is enabled

Authorization Code Grant Scopes (User Token)

These scopes are requested during the OAuth user authorization flow. Please refer to your eBay Developer Portal for the available scopes.

TIP

The OAuth scopes define which permissions your application requests from the user during authorization. Only request the scopes you actually need. Over-scoping increases the chance of user rejection and review friction.

'authorization_scopes' => [
    'https://api.ebay.com/oauth/api_scope',
    'https://api.ebay.com/oauth/api_scope/sell.account',
    'https://api.ebay.com/oauth/api_scope/sell.inventory',
],

Client Credentials Grant Scopes (Application Token)

These scopes apply to application-based authentication (no user context). Please refer to your eBay Developer Portal for the available scopes.

'credential_scopes' => [
    'https://api.ebay.com/oauth/api_scope',
],