### GET /buy/v1/deals Example Source: https://developer.ebay.com/develop/guides-v2/index Example of a successful response payload for a GET request to the /buy/v1/deals endpoint, showcasing a list of current eBay Deals items. ```APIDOC ## GET /buy/v1/deals ### Description Retrieves a list of current eBay Deals items for a specified category. ### Method GET ### Endpoint `/buy/v1/deals` ### Response #### Success Response (200) - **deals** (array) - An array of deal items. - **groupId** (string) - Identifier for the deal group. - **title** (object) - Object containing the title of the deal item. - **content** (string) - The actual title of the item. - **imageLink** (string) - URL for the item's image. - **minPrice** (object) - Minimum price for the deal. - **value** (number) - The price value. - **currency** (string) - The currency of the price. - **maxPrice** (object) - Maximum price for the deal. - **value** (number) - The price value. - **currency** (string) - The currency of the price. - **categoryIdentifier** (string) - The category of the item. - **quantitySold** (integer) - Number of items sold. - **discount** (boolean) - Indicates if a discount is applied. - **originalPrice** (object) - The original price of the item. - **value** (number) - The original price value. - **currency** (string) - The currency of the original price. - **quantityLimitPerBuyer** (integer) - Maximum quantity allowed per buyer. - **priceDisplayCondition** (string) - Condition for displaying the price. - **itemGroup** (string) - Link to the item group. - **dealEndtime** (object) - The end time of the deal. - **value** (string) - The deal end time in ISO 8601 format. - **formattedValue** (string) - The formatted deal end time. ### Response Example ```json { "deals": [ { "groupId": "v1|1***********|0", "title": { "content": "Apple iPhone 4S - 32GB - White Smartphone-14485" }, "imageLink": "http://i.ebayimg.ebay.com/0*****/$_35.JPG", "minPrice": { "value": 300, "currency": "USD" }, "maxPrice": { "value": 300, "currency": "USD" }, "categoryIdentifier": "Cell Phones & Smartphones", "quantitySold": 12, "discount": true, "originalPrice": { "value": 401, "currency": "USD" }, "quantityLimitPerBuyer": 5, "priceDisplayCondition": "ALWAYS_SHOW", "itemGroup": "/buy/v1/item_group/v1|1***********|0", "dealEndtime": { "value": "2024-11-27T14:59:00.000Z", "formattedValue": "2024-11-27T14:59:00.000Z" } }, { "groupId": "v1|1***********|0", "title": { "content": "Packing and Shipping boxes - 19273-1445985364525" }, "...": "..." } ] } ``` ``` -------------------------------- ### Request Payload Example Source: https://developer.ebay.com/develop/guides-v2/index An example of a JSON request payload for creating an item discount using the `POST /sell/marketing/v1/item_promotion` endpoint. ```APIDOC ## Request Payload ### Description A request body, often referred to as a "payload," is provided when creating or updating a resource. In eBay REST APIs, request and response payloads are typically formatted in JSON. The API Reference documentation details the fields supported in the request body for each method. ### Example Request Payload **Endpoint**: `POST https://api.ebay.com/sell/marketing/v1/item_promotion` **Purpose**: Creates an item discount. ```json { "marketplaceId": "EBAY_US", "inventoryCriterion": { "listingIds": [ "142250172493", "132073034350" ], "inventoryCriterionType": "INVENTORY_BY_VALUE" }, "endDate": "2027-03-01T20:00:00.000Z", "discountRules": [ { "discountSpecification": { "numberOfDiscountedItems": 1, "forEachQuantity": 1 }, "ruleOrder": 0, "discountBenefit": { "percentageOffItem": "5" } } ], "name": "Buy 1 and get 2nd one 5% off -part 2", "description": "Buy 1 and get 2nd one 5% off -part 2", "startDate": "2025-02-11T19:58:18.918Z", "promotionStatus": "DRAFT" } ``` ``` -------------------------------- ### Consent Request Example (Sandbox) Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization An example of an HTML redirect URL used to request user consent for the Sandbox environment. ```APIDOC ## Consent Request Example (Sandbox) ### Description This example demonstrates how to construct the consent request URL for the eBay Sandbox environment, including required and optional parameters. ### Method GET ### Endpoint `https://auth.sandbox.ebay.com/oauth2/authorize` ### Query Parameters - **`client_id`** (string) - Required - Your application's client ID for the Sandbox environment. - **`locale`** (string) - Optional - Example: `en-US`. - **`prompt`** (string) - Optional - Example: `login`. - **`redirect_uri`** (string) - Required - Your application's RuName for the Sandbox environment. - **`response_type`** (string) - Required - `code`. - **`scope`** (string) - Required - A URL-encoded string of space-separated scopes (e.g., `https://www.googleapis.com/auth/plus.login https://www.googleapis.com/auth/userinfo.email`). - **`state`** (string) - Optional - A custom value for state management. ### Request Example ``` GET https://auth.sandbox.ebay.com/oauth2/authorize?client_id=__&locale=__&prompt=login&redirect_uri=__&response_type=code&scope=__&state=__ ``` ``` -------------------------------- ### Example cURL for Authorization Code Grant Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Demonstrates how to construct a cURL command to perform the authorization code grant request. This example includes the necessary headers and form-urlencoded data for obtaining an access token. ```curl curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic RGF2eURldmUtRG2 ... ZTVjLTIxMjg=' \ -d '**grant_type**=authorization_code&\ **code**=v%5E1.1%23i%5E1%23f% ... 3D%3D&\ **redirect_uri**=Davy_Developer-DavyDeve-DavysT-euiukxwt' ``` -------------------------------- ### Get Auth'n'Auth Tokens for Client/Desktop Applications Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Steps for client/desktop applications to obtain authentication tokens without hosting web pages for user consent. ```APIDOC ## Get Auth'n'Auth Tokens for Client/Desktop Applications ### Description This process is for client/desktop applications that do not have a web component or do not wish to host AcceptURL/RejectURL pages. It involves the application requesting a session ID, redirecting the user to eBay for sign-in and consent, and then fetching the token. ### Process Overview 1. **User Intent**: User indicates a desire to use the application. 2. **GetSessionID Request**: Application makes a `GetSessionID` request to eBay to obtain a `SessionID`. 3. **Construct Sign-in URL**: Application uses the `SessionID` and `RUName` to construct a sign-in URL. - **Production URL**: `https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID` - **Sandbox URL**: `https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=RUName&SessID=SessionID` - **Note**: The `SessionID` must be URL-encoded. 4. **User Sign-in**: User is redirected to the eBay sign-in page and signs in. 5. **Consent Form**: eBay presents the user with the consent form for the application. 6. **User Consent/Rejection**: User consents to or rejects the application's access. 7. **Confirmation Page**: eBay forwards the user to a confirmation page. 8. **FetchToken Request**: Application calls `FetchToken` using the `SessionID` to retrieve the user token. ### Key Endpoints/Methods #### GetSessionID - **Method**: `GetSessionID` (Refer to GetSessionID reference detail for specifics) - **Purpose**: Retrieves a unique session ID required for the authentication flow. #### FetchToken - **Method**: `FetchToken` - **Purpose**: Retrieves the user's authentication token after the user has signed in and consented. ### Request Example (Conceptual - FetchToken) ```json { "SessionID": "YOUR_SESSION_ID" } ``` ### Response Example (Conceptual - FetchToken Success) ```json { "HardExpirationTime": "YYYY-MM-DDTHH:MM:SS.sssZ", "SessionID": "YOUR_SESSION_ID", "Token": "YOUR_USER_TOKEN", "Token này": "PERSISTENT", "Warning": [ { "Code": "1234", "Message": "Some warning message" } ] } ``` ``` -------------------------------- ### FetchToken SOAP API Call Example Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This example demonstrates a FetchToken API call using SOAP. It includes the necessary requester credentials within the SOAP header to retrieve user tokens after the consent process. ```xml YOUR_APP_ID YOUR_DEV_ID YOUR_AUTH_TOKEN YOUR_SESSION_ID ``` -------------------------------- ### Create Item Discount Request Payload Example (JSON) Source: https://developer.ebay.com/develop/guides-v2/index Provides a sample JSON request payload for creating an item discount using the eBay Marketing API. This payload includes details like marketplace, inventory criteria, discount rules, and promotion timing. ```JSON { "marketplaceId": "EBAY_US", "inventoryCriterion": { "listingIds": [ "142250172493", "132073034350" ], "inventoryCriterionType": "INVENTORY_BY_VALUE" }, "endDate": "2027-03-01T20:00:00.000Z", "discountRules": [ { "discountSpecification": { "numberOfDiscountedItems": 1, "forEachQuantity": 1 }, "ruleOrder": 0, "discountBenefit": { "percentageOffItem": "5" } } ], "name": "Buy 1 and get 2nd one 5% off -part 2", "description": "Buy 1 and get 2nd one 5% off -part 2", "startDate": "2025-02-11T19:58:18.918Z", "promotionStatus": "DRAFT" } ``` -------------------------------- ### Example Error Response with Parameter Issue Source: https://developer.ebay.com/develop/guides-v2/index This JSON example demonstrates an error response when a parameter in the API call is invalid. It highlights the 'errorId', 'domain', 'category', 'message', 'inputRefIds', and 'parameters' fields. ```json { "errors": [ { "errorId": 15008, "domain": "API_ORDER", "category": "REQUEST", "message": "Invalid Field : itemId.", "inputRefIds": [ "$.lineItemInputs[0].itemId" ], "parameters": [ { "name": "itemId", "value": "v1|2*********|0" } ] } ] } ``` -------------------------------- ### Fetch eBay Token with SOAP Credentials in HTTP Headers Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This example shows how to fetch an eBay token by passing requester credentials (AppId, DevId, AuthCert) in HTTP headers instead of the SOAP payload. This method is useful for certain integration scenarios where header-based authentication is preferred. ```http X-EBAY-API-APP-NAME:MyAppID X-EBAY-API-DEV-NAME:MyDevID X-EBAY-API-CERT-NAME:MyCertID X-EBAY-API-CALL-NAME:FetchToken X-EBAY-API-SITEID:0 Content-Type:text/xml Request Payload: 1169 MySessionID ``` -------------------------------- ### URL Encode Query Parameter Values Example Source: https://developer.ebay.com/develop/guides-v2/index Demonstrates how to URL encode values for query parameters in eBay REST API requests. This is crucial for parameters that require specific values, such as the 'aspect_filter' example shown, to ensure correct interpretation by the server. ```HTTP /buy/browse/v1/item_summary/search?q=shirt&category_ids=15724&aspect_filter=categoryId%3A15724%2CColor%3A%7BRed%7D ``` -------------------------------- ### Web/Server Applications - Getting a Session ID Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This section outlines the initial step for web/server applications to obtain a SessionID from eBay, which is crucial for initiating the user authentication flow. ```APIDOC ## POST /GetSessionID ### Description Requests a unique SessionID from eBay to initiate the user authentication process for web/server applications. ### Method POST ### Endpoint /GetSessionID ### Parameters #### Query Parameters None #### Request Body None ### Request Example ```json { "example": "This is a placeholder for the actual GetSessionID request structure, which is typically part of a SOAP envelope." } ``` ### Response #### Success Response (200) - **SessionID** (string) - The unique session identifier obtained from eBay. #### Response Example ```json { "SessionID": "YOUR_GENERATED_SESSION_ID" } ``` ``` -------------------------------- ### Example cURL Refresh Token Request for eBay OAuth Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Demonstrates how to execute a refresh token request using cURL. It includes the POST method, sandbox endpoint URL, necessary Content-Type and Authorization headers, and the request body with grant_type, refresh_token, and scope parameters. ```bash curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: **Basic RGF2eURldmUtRG2 ... ZTVjLTIxMjg=**' \ -d '**grant_type**=refresh_token& \ **refresh_token**=v^1.1#i^1#p^3# ... fMSNFXjEyODQ=& \ **scope**=https://api.ebay.com/oauth/api_scope/sell.account%20 \ https://api.ebay.com/oauth/api_scope/sell.inventory' ``` -------------------------------- ### Example cURL Request for eBay Client Credentials Grant Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Demonstrates how to execute a client credentials grant request using cURL to obtain an eBay Application access token. It specifies the POST method, the sandbox token endpoint URL, necessary headers for content type and authorization, and the URL-encoded request body with grant type and scopes. ```curl curl -X POST 'https://api.sandbox.ebay.com/identity/v1/oauth2/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic UkVTVFRlc3...wZi1hOGZhLTI4MmY=' \ -d '**grant_type**=client_credentials&**scope**=https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope %20https%3A%2F%2Fapi.ebay.com%2Foauth%2Fapi_scope%2Fbuy.item.bulk' ``` -------------------------------- ### HTTP Methods Supported by eBay REST APIs Source: https://developer.ebay.com/develop/guides-v2/index This section outlines the standard HTTP methods (POST, PUT, GET, DELETE) supported by eBay's RESTful web services, along with their general purpose. ```APIDOC ## HTTP Methods This section outlines the standard HTTP methods supported by eBay's RESTful web services. ### Description eBay REST APIs support the following HTTP methods, defined by W3C in RFC 9110, Section 9.3: ### Methods - **POST**: Requests the server to accept the enclosed entity as a new subordinate of the web resource identified by the URI. Used for creating new resources or submitting data. - **PUT**: Requests that the enclosed entity be stored under the supplied URI. If the URI refers to an existing resource, it is modified; otherwise, a new resource may be created. - **GET**: Requests a representation of the specified resource. GET requests should only retrieve data and have no other side effects. - **DELETE**: Removes the specified resource(s). ``` -------------------------------- ### eBay OAuth Refresh Token Response Example Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Illustrates the JSON response received from eBay after a successful refresh token request. It contains the newly minted 'access_token', its 'expires_in' duration, and the 'token_type'. ```json { **"access_token": "v^1.1#i ... AjRV4yNjA=",** "expires_in": 7200, "token_type":"User Access Token" } ``` -------------------------------- ### Example Warning Response Structure Source: https://developer.ebay.com/develop/guides-v2/index This JSON structure illustrates a typical warning response from the eBay API. It includes a 'warnings' array containing detailed error information and a 'resource' field. Note that a warning response typically returns an HTTP status code of 200. ```json { "warnings": [ { "errorId": long, "domain": "string", "subDomain": "string", "category": "ErrorCategory", "message": "string", "longMessage": "string", "inputRefIds": ["string"], "outputRefIds": ["string"], "parameters": [ErrorParameter] } ], "resource": "Hello, eBay followers!" } ``` -------------------------------- ### Construct eBay Sign-in URL (Sandbox) Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This snippet demonstrates constructing the eBay sign-in URL for the sandbox environment. Similar to the production URL, it requires a SessionID and RUName, with the SessionID needing URL encoding. ```text https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=_RUName_&SessID=_SessionID_ ``` -------------------------------- ### Common HTTP Response Headers Source: https://developer.ebay.com/develop/guides-v2/index Details on standard HTTP response headers returned by eBay REST operations, including their purpose and examples. ```APIDOC ## Common HTTP Response Headers ### Description These headers provide crucial information about the API response, such as content type, language, resource location, and potential warnings. ### Headers #### `Content-type` * **Description**: Describes the character set and/or MIME type of the response. It should align with the `Accept-Charset` and `Accept-Encoding` request headers. If the server cannot meet the requested values, it may ignore them and return a value specified by `Content-Type` without an error. * **Examples**: * `Content-Type: application/json; charset=utf-8` * `Content-Type: application/jsonl` * `Content-Type: charset=utf-8` #### `Content-Language` * **Description**: Indicates the natural language of the response, ideally matching the `Accept-Language` request header. If the requested language is not supported, eBay may return a default or alternative language code (e.g., `en-US`). * **Example**: * `Accept-Language: en-US` #### `Location` * **Description**: Used with `POST` calls for creating new resources. Instead of a response payload, this header contains a URI to the newly created resource. This URI can be used to retrieve the resource's ID or to make a `GET` request for the resource. #### `Warning` * **Description**: Conveys additional information about the status or transformation of a message that might not be evident from the status code alone. ### Note Refer to the documentation for each specific REST operation for details on headers unique to that call. When seeking support, providing response headers is crucial for diagnosing issues. ``` -------------------------------- ### Launch eBay Auth'n'Auth via HTML Button Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This HTML snippet shows how to create a submit button that, when clicked, opens the eBay sign-in URL in a new window. It dynamically inserts the RUName and SessionID into the URL. ```html ``` -------------------------------- ### Fetching a Token Programmatically with SOAP Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This section demonstrates how to fetch an authentication token programmatically using SOAP. It shows the XML structure for the FetchTokenRequest, including how to pass credentials either in the SOAP header or via HTTP headers. ```APIDOC ## POST /wsapi FetchToken (SOAP) ### Description Fetches an authentication token using the SOAP protocol. Credentials can be provided either within the SOAP header or through custom HTTP headers. ### Method POST ### Endpoint /wsapi ### Parameters #### Request Body - **soap:Envelope** (xml) - Required - The SOAP envelope containing the FetchTokenRequest. - **soap:Header** (xml) - Required - Contains the requester credentials. - **ebl:RequesterCredentials** (xml) - Required - Credentials for the request. - **Credentials** (xml) - Required - Application keyset values. - **AppId** (string) - Required - Your eBay Application ID. - **DevId** (string) - Required - Your eBay Developer ID. - **AuthCert** (string) - Required - Your eBay Authorization Certificate. - **FetchTokenRequest** (xml) - Required - The request payload for fetching a token. - **SessionID** (string) - Required - The session ID obtained from eBay. - **Version** (string) - Required - The API version number. ### Request Example ```xml MyAppID MyDevID MyCertID MySessionID 1169 ``` ### Request Example (HTTP Headers) ```xml X-EBAY-API-APP-NAME: MyAppID X-EBAY-API-DEV-NAME: MyDevID X-EBAY-API-CERT-NAME: MyCertID X-EBAY-API-CALL-NAME: FetchToken X-EBAY-API-SITEID: 0 Content-Type: text/xml 1169 MySessionID ``` ### Response #### Success Response (200) - **FetchTokenResponse** (xml) - Contains the authentication token. - **eBayAuthToken** (string) - The generated user token. - **HardExpirationTime** (dateTime) - The hard expiration time of the token. - **SessionID** (string) - The session ID used for the request. #### Response Example ```xml 2023-10-27T10:00:00.000Z Success 1169 ... USER_TOKEN_GOES_HERE 2024-10-27T10:00:00.000Z MySessionID ``` ``` -------------------------------- ### Constructing the eBay Sign-in URL Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Provides the format for constructing the eBay sign-in URL, which directs users to eBay for authentication and consent, including production and sandbox environments. ```APIDOC ## Constructing eBay Sign-in URL ### Description Builds the URL that redirects users to eBay's sign-in and consent page. This URL includes the SessionID obtained from GetSessionID and the application's RUName. ### Method N/A (URL Construction) ### Endpoint N/A (URL Construction) ### Parameters #### URL Parameters - **RUName** (string) - Required - The name of your application registered with eBay. - **SessionID** (string) - Required - The session ID obtained from the GetSessionID call. Must be URL-encoded. - **ruparams** (string) - Optional - User data to be passed back to your application after consent. Must be URL-encoded. ### Request Example #### Production URL ``` https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=_YOUR_RU_NAME_&SessID=_URL_ENCODED_SESSION_ID_ ``` #### Sandbox URL ``` https://signin.sandbox.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=_YOUR_RU_NAME_&SessID=_URL_ENCODED_SESSION_ID_ ``` #### Example with ruparams ``` https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=_YOUR_RU_NAME_&SessID=_URL_ENCODED_SESSION_ID_&ruparams=VarA%3DB12309%26VarB%3DABC123 ``` ### Response N/A (This is a client-side URL construction) ``` -------------------------------- ### Construct eBay Sign-in URL (Production) Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This snippet shows how to construct the eBay sign-in URL for production environments. It requires a SessionID obtained from a GetSessionID request and the application's RUName. The SessionID must be URL-encoded. ```text https://signin.ebay.com/ws/eBayISAPI.dll?SignIn&RUName=_RUName_&SessID=_SessionID_ ``` -------------------------------- ### Authorization Code Redirect URL Example Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Illustrates the structure of the redirect URL after a user grants consent, including the authorization code and state parameter. The authorization code is a single-use token for retrieving an access token. ```plaintext https://www.example.com/acceptURL.html?state=<_client_supplied_state_value_>&code=v%5E1.1% ... NjA%3D&expires_in=299 ``` -------------------------------- ### Authorization Code Grant Flow (User Access Token) Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This section outlines the process for obtaining a User access token through the authorization code grant flow. It involves getting user consent and then exchanging an authorization code for a token. ```APIDOC ## Authorization Code Grant Flow ### Description This flow is used to create an OAuth User access token, which allows your application to make API calls on behalf of a specific eBay user. It's a multi-step process that requires user consent. ### Steps 1. **Getting User Consent:** Obtain explicit consent from the eBay user for your application to access and update their confidential resources. This typically involves redirecting the user to an eBay authorization page. 2. **Exchanging Authorization Code for User Access Token:** After the user grants consent, eBay provides an authorization code. This code is then exchanged for a User access token and a refresh token. 3. **Using the User Access Token:** The obtained User access token is used to authorize API requests made on behalf of the user. 4. **Refreshing the User Access Token:** If the User access token expires, a refresh token can be used to obtain a new access token without requiring the user to re-authorize. ### Resources - **Getting user consent:** Detailed steps on how to obtain user consent. - **Exchanging the authorization code for a User access token:** Information on the token exchange process. - **Using a refresh token to update a User access token:** Guidance on refreshing expired tokens. ### OAuth Client Libraries eBay provides client libraries for various languages (Android, C#, Java, Node.js, Python) to simplify the process of minting OAuth tokens. ``` -------------------------------- ### Example eBay REST API Response Payload (JSON) Source: https://developer.ebay.com/develop/guides-v2/index This JSON object represents a successful response payload from the eBay REST API, specifically for a call to retrieve deals. It includes details about various deals, such as item titles, prices, and quantities. ```json { "deals": [ { "groupId": "v1|1***********|0", "title": { "content": "Apple iPhone 4S - 32GB - White Smartphone-14485" }, "imageLink": "http://i.ebayimg.ebay.com/0*****/$_35.JPG", "minPrice": { "value": 300, "currency": "USD" }, "maxPrice": { "value": 300, "currency": "USD" }, "categoryIdentifier": "Cell Phones & Smartphones", "quantitySold": 12, "discount": true, "originalPrice": { "value": 401, "currency": "USD" }, "quantityLimitPerBuyer": 5, "priceDisplayCondition": "ALWAYS_SHOW", "itemGroup": "/buy/v1/item_group/v1|1***********|0", "dealEndtime": { "value": "2024-11-27T14:59:00.000Z", "formattedValue": "2024-11-27T14:59:00.000Z" } }, { "groupId": "v1|1***********|0", "title": { "content": "Packing and Shipping boxes - 19273-1445985364525" }, ... } } ] } ``` -------------------------------- ### Configuring Consent Request Query Parameters Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Details the required and optional query parameters for constructing the consent request URL. ```APIDOC ## Configuring Consent Request Query Parameters ### Description These query parameters are essential for customizing the consent request URL, ensuring proper identification, localization, and scope definition for your application's access. ### Query Parameters - **`client_id`** (string) - Required - The client ID for the targeted eBay environment. - **`locale`** (string) - Optional - Localizes the OAuth consent page for a specific marketplace (e.g., `de-DE`). - **`prompt`** (string) - Optional - If set to `login`, forces the user to log in even if they have an existing session. - **`redirect_uri`** (string) - Required - The RuName value for the targeted environment, specifying where the user is redirected after consent. - **`response_type`** (string) - Required - Must be set to `code` to obtain an authorization code. - **`scope`** (string) - Required - A URL-encoded string of space-separated OAuth scopes required by your application. - **`state`** (string) - Optional - An opaque value used to maintain state and prevent cross-site request forgery. ``` -------------------------------- ### Authenticate XML API Call with User Token in Request Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This example shows how to authenticate an XML API call using a user token. The eBayAuthToken is placed within the RequesterCredentials element of the request XML, providing user-specific authorization for the API call. ```xml ** Token goes here ** ``` -------------------------------- ### XML Example of Seven-Day Token Expiration Warning Response Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization This XML response from the GeteBayOfficialTime call includes the HardExpirationWarning element. It specifies the exact date and time (2005-01-14 03:34:00) when the user's token will expire, allowing the application to proactively prompt for re-authorization. ```xml 2005-01-12T18:29:48.312Z Success 00000000-00000000-00000000-00000000-00000000-00000000-0000000000 393 20050110220901 2005-01-14 03:34:00 ``` -------------------------------- ### eBay API Sandbox Environment Source: https://developer.ebay.com/develop/guides-v2/index Information about utilizing the sandbox environment for testing eBay REST APIs before deploying to production. ```APIDOC ## eBay API Sandbox Environment ### Description Most eBay REST APIs offer a sandbox environment for testing purposes. This allows developers to test APIs with various functionalities before moving to the production environment. ### URIs - **Production URI**: Typically `https://api.ebay.com` - **Sandbox URI**: Typically `https://api.sandbox.ebay.com` Note: The base URI paths are generally similar between production and sandbox environments. ### Testing For detailed instructions on testing within the sandbox environment, refer to the "Create a test sandbox user" guide. ``` -------------------------------- ### Auth'n'Auth Token Models Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Explanation of the two application models for Auth'n'Auth tokens: Single User Model and Solutions Provider Model. ```APIDOC ## Auth'n'Auth Token Models ### Description eBay applications can operate under two models concerning user authentication and token management: the Single User Model and the Solutions Provider Model. The choice depends on the number of users the application supports. ### Single User Model - **Description**: This model is suitable for applications that support only a single user. A single Auth'n'Auth token is sufficient. - **Token Generation**: The token can be generated via the 'User Tokens (eBay Sign-In)' page in the developer account. - **Environment Association**: Tokens generated in Production are tied to a Production eBay user ID, while tokens from Sandbox are tied to a Sandbox test user. ### Solutions Provider Model - **Description**: This model is designed for applications that support multiple users. It requires implementing the capability to obtain user tokens directly within the application. - **Implementation**: Involves configuring the application to receive tokens for eBay users, enabling users to grant access, and managing token lifecycles (usage, expiration, replacement). ### Method N/A ### Endpoint N/A ### Parameters N/A ### Request Example N/A ### Response N/A ``` -------------------------------- ### OAuth Token Best Practices Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Best practices for working with access tokens and their rate limits, including token lifespan, refresh token handling, scope management, and secure storage of credentials. ```APIDOC ## OAuth Token Best Practices ### Description This section outlines best practices for managing eBay OAuth access tokens and refresh tokens to ensure security, efficiency, and adherence to rate limits. ### Best Practices * **Access Token Lifespan**: Access tokens are short-lived for security. Use them until they expire, then mint new ones using the appropriate grant type (client credentials for Application access tokens, refresh token for User access tokens). * **Refresh Token Handling**: Refresh tokens are long-lived but can be revoked. Applications must gracefully handle User access token revocations due to user actions (username change, consent revocation) or eBay actions. * **Refresh Token Expiration**: If a refresh token expires, a new permissions grant request is required to mint a new User access token. * **Rate Limits**: eBay enforces daily rate limits on token minting requests. Ensure your application stays within these limits. * **Scope Management**: Create User access tokens with all necessary current and future scopes to avoid repeated user consent requests. Only include scopes your application requires; avoid redundant scopes (e.g., don't specify a read-only scope if a manage scope is also specified). * **Credential Security**: Store OAuth credentials and refresh tokens securely on a server to prevent unauthorized access and misuse. ``` -------------------------------- ### Client Credentials Grant Flow Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Instructions for minting Application access tokens using the client credentials grant flow, including endpoint configuration and request headers. ```APIDOC ## Client Credentials Grant Flow ### Description This section details the process of minting an Application access token using the client credentials grant flow. This token is used for application-level API access. ### Method `POST` ### Endpoints * **Sandbox**: `https://api.sandbox.ebay.com/identity/v1/oauth2/token` * **Production**: `https://api.ebay.com/identity/v1/oauth2/token` ### Request Headers * **Content-Type** (string, required): `application/x-www-form-urlencoded` * **Authorization** (string, required): `Basic ` * Credentials format: `:` * Example: `Basic OWE5NTk1YjEtZGY1NS00ZTYwLWE5YjAtY2M1YmQ1YjQ0YjYxOkVlYmF5QG15Q2xpZW50SUQ=` ### Request Body * **grant_type** (string, required): `client_credentials` * **scope** (string, optional): A space-separated list of scopes required for the access token. If omitted, a default set of scopes may be granted. ### Request Example (cURL) ```bash curl -X POST \ 'https://api.ebay.com/identity/v1/oauth2/token' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -H 'Authorization: Basic OWE5NTk1YjEtZGY1NS00ZTYwLWE5YjAtY2M1YmQ1YjQ0YjYxOkVlYmF5QG15Q2xpZW50SUQ=' \ -d 'grant_type=client_credentials' ``` ### Response #### Success Response (200 OK) * **access_token** (string): The minted application access token. * **expires_in** (integer): The lifetime in seconds of the access token. * **token_type** (string): The type of token, typically `Bearer`. #### Response Example ```json { "access_token": "v^1. ... .Z", "expires_in": 7200, "token_type": "Bearer" } ``` ``` -------------------------------- ### Configure Client Credentials Grant Request for eBay Token Source: https://developer.ebay.com/develop/guides-v2/authorization/authorization Defines the structure for a POST request to mint an Application access token using the client credentials grant. This includes the HTTP method, sandbox URL, required headers (Content-Type and Authorization), and the request body parameters 'grant_type' and 'scope'. ```http POST https://api.sandbox.ebay.com/identity/v1/oauth2/token Headers: Content-Type = application/x-www-form-urlencoded Authorization = Basic <_B64-encoded-oauth-credentials_> Body: grant_type=client_credentials scope= // a URL-encoded string of space-separated scopes ```