From c0b8adbbaae439c702787f65b33711b36a1dfbaf Mon Sep 17 00:00:00 2001 From: Alexej Date: Thu, 25 Jun 2026 02:10:05 +0200 Subject: [PATCH] feat: feedback API v1 Add the Commerce Feedback API (commerce/feedback/v1): - getItemsAwaitingFeedback, getFeedback, leaveFeedback, getFeedbackRatingSummary, respondToFeedback - OpenAPI spec + generated types (redocly + openapi-typescript) - Wired into ApiFactory and the Commerce group - Contract test added; README implementation status updated --- README.md | 2 +- redocly.yaml | 4 + specs/commerce_feedback_v1_beta_oas3.json | 1548 +++++++++++++++++ src/api/apiFactory.ts | 4 +- src/api/restful/commerce/feedback/index.ts | 140 ++ src/api/restful/commerce/index.ts | 5 +- .../specs/commerce_feedback_v1_beta_oas3.ts | 754 ++++++++ src/types/restfulTypes.ts | 4 + test/api/restful/commerce/index.ts | 4 +- 9 files changed, 2461 insertions(+), 4 deletions(-) create mode 100644 specs/commerce_feedback_v1_beta_oas3.json create mode 100644 src/api/restful/commerce/feedback/index.ts create mode 100644 src/types/restful/specs/commerce_feedback_v1_beta_oas3.ts diff --git a/README.md b/README.md index dcc16ad2..957065a9 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ For more examples, check out the [examples directory](./examples). | API | Implemented | |:-------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Buy API** | ✔ Browse API `v1.10.0`
✔ Deal API `v1.3.0`
✔ Feed API `v1.3.1`
✔ Marketing API `v1_beta.1.0`
✔ Offer API `v1_beta.0.0`
✔ Order API `v1_beta.20.0`
✔ Marketplace Insights API `v1_beta.2.2` | -| **Commerce API** | ✔ Catalog API `v1_beta.3.1`
✔ Charity API `v1.2.0`
✔ Identity API `v1.0.0`
✔ Notification API `v1.2.0`
✔ Taxonomy API `v1.0.0`
✔ Translation API `v1_beta.1.4`
✔ Media API `v1_beta.1.0`
✔ Message API `v1.0.0` | +| **Commerce API** | ✔ Catalog API `v1_beta.3.1`
✔ Charity API `v1.2.0`
✔ Identity API `v1.0.0`
✔ Notification API `v1.2.0`
✔ Taxonomy API `v1.0.0`
✔ Translation API `v1_beta.1.4`
✔ Media API `v1_beta.1.0`
✔ Message API `v1.0.0`
✔ Feedback API `v1_beta.1.0.0` | | **Developer API** | ✔ Analytics API | | **Post Order API** | ✔ Cancellation API
✔ Case Management API
✔ Inquiry API
✔ Return API | | **Sell API** | ✔ Account API `v1.9.0`
✔ Analytics API `v1.3.0`
✔ Compliance API `v1.4.1`
✔ Feed API `v1.3.1`
✔ Finance API `v1.9.0`
✔ Fulfillment API `v1.19.10`
✔ Inventory API `v1.18.0`
✔ Listing API `v1_beta.2.1`
✔ Logistics API `v1_beta.0.0`
✔ Marketing API `v1.17.0`
✔ Metadata API `v1.7.1`
✔ Negotiation API `v1.1.0`
✔ Recommendation API `v1.1.0` | diff --git a/redocly.yaml b/redocly.yaml index b554f252..7bf27c61 100644 --- a/redocly.yaml +++ b/redocly.yaml @@ -55,6 +55,10 @@ apis: root: specs/commerce_message_v1_oas3.json x-openapi-ts: output: src/types/restful/specs/commerce_message_v1_oas3.ts + commerce_feedback_v1_beta: + root: specs/commerce_feedback_v1_beta_oas3.json + x-openapi-ts: + output: src/types/restful/specs/commerce_feedback_v1_beta_oas3.ts commerce_notification_v1: root: specs/commerce_notification_v1_oas3.json x-openapi-ts: diff --git a/specs/commerce_feedback_v1_beta_oas3.json b/specs/commerce_feedback_v1_beta_oas3.json new file mode 100644 index 00000000..cc918ccc --- /dev/null +++ b/specs/commerce_feedback_v1_beta_oas3.json @@ -0,0 +1,1548 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "Feedback API", + "description": "The Feedback API includes resources for retrieving items awaiting feedback, retrieving and submitting feedback entries, providing feedback rating summaries, and responding to feedback. These methods allow users to manage feedback across buying and selling activities.

Note: Feedback is tracked at the line item level within an order, not for the whole order. Each line item can have its own feedback record.

", + "contact": { + "name": "eBay Inc," + }, + "license": { + "name": "eBay API License Agreement", + "url": "https://developer.ebay.com/join/api-license-agreement" + }, + "version": "v1.0.0" + }, + "servers": [ + { + "url": "https://api.ebay.com{basePath}", + "description": "Production", + "variables": { + "basePath": { + "default": "/commerce/feedback/v1" + } + } + } + ], + "paths": { + "/awaiting_feedback": { + "get": { + "tags": [ + "awaiting_feedback" + ], + "description": "This method retrieves line items awaiting feedback from the user's order partner. You can refine the results using optional filter query parameters, such as item ID, user name, or user role in the transaction. Sorting and pagination features help organize and navigate returned items efficiently.

For sellers, only sold items that have not yet received feedback are included. For buyers, only purchased items for which feedback is still pending are included. If the user is both a buyer and a seller, this API returns items awaiting feedback for transactions where the user acted as either. Applying filters can limit results to either buyer-only or seller-only transactions.

The response provides an overview of feedback yet to be left for completed transactions (as filtered), with counts for both the buyer and seller roles. It includes an array of line items, each containing the listing ID, title, price (with currency and value). For each line item, the response offers feedback templates specifying which ratings are available.

Note: Detailed seller ratings are for sellers only, and are created from buyer feedback.

", + "operationId": "getItemsAwaitingFeedback", + "parameters": [ + { + "name": "filter", + "in": "query", + "description": "Use this parameter to limit the response based on the specified filter parameters. Supported filter parameters include:

Send the filter as a query parameter in a comma-separated name:value list. For example:
filter=listingId:123,receiverName:user,userRole:BUYER

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "This parameter sets the maximum number of line items to return per page of data.

Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, with offset set to 20 and limit set to 10, the call retrieves entries 21 through 30 from the result set.

Although this field is optional, if omitted the default value of 25 is used.

Default: 25

Minimum: 25

Maximum: 200

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "offset", + "in": "query", + "description": "Use this parameter to specify the number of items to skip in the result set. This is used with the limit field to control the pagination of the output. For example:

Note: This feature employs a zero-based list, where the first line item in the list has an offset of 0.

If this parameter is not set, its value defaults to 0 which returns the first page of records.

Default: 0

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "sort", + "in": "query", + "description": "Use this parameter to configure the order of the returned listings. The time is based on when the buyer paid for the line item. Acceptable values:

If this parameter is omitted, its value defaults to END_TIME_DESC.

Default: END_TIME_DESC

", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/AwaitingFeedbackResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "x-response-codes": { + "errors": { + "501024": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Input sort value is invalid." + }, + "501025": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Input user role value is invalid." + } + } + } + }, + "401": { + "description": "Not Authorized", + "x-response-codes": { + "errors": { + "1001": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "Invalid access token. Check the value of the Authorization HTTP request header." + } + } + } + }, + "500": { + "description": "Internal Server Error", + "x-response-codes": { + "errors": { + "2003": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." + } + } + } + } + }, + "security": [ + { + "api_auth": [ + "https://api.ebay.com/oauth/api_scope/commerce.feedback" + ] + } + ] + } + }, + "/feedback": { + "get": { + "tags": [ + "feedback" + ], + "description": "This method enables users to retrieve feedback for any specified user ID and feedback type (sent or received). You can refine the results using optional query parameters such as its feedback ID, listing ID, or order line item ID, or applying one or more filters.

Applying filters can narrow results using criteria such as comment type, photos, or topics identified through AI-based analysis. When filtering for feedback with photos (filterImage:true), only entries with images (entries that include image URLs) are returned. Additionally, feedback can be refined for the number of days to look back, the role of the user providing the feedback, and whether to include automated feedback entries left by eBay.

Sorting and pagination features help organize and navigate returned items efficiently.

Returned data includes feedback details (such as comment text and type), feedback ratings (covering criteria like overall experience, and for sellers item description, shipping time, and communication), role and attributes of the feedback giver, line item and transaction summaries, images, and any available topics. See filter for additional information. Privacy is safeguarded by restricting the amount of detail visible to users, depending on their context. When accessing another user's feedback without logging in, buyer names are masked and seller names are shown. Logged-in users viewing their own feedback see all names, while those viewing other users' feedback will encounter some masking.

", + "operationId": "getFeedback", + "parameters": [ + { + "name": "feedback_id", + "in": "query", + "description": "Use this field to only return a specific feedback record by its feedback ID.

Note: If this query parameter is used, no other filters will be applicable.

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "feedback_type", + "in": "query", + "description": "Use this field to specify the type of feedback records to return. Acceptable values:

If not specified, both feedback received and feedback left for the user shall be retrieved.

Note: When using FEEDBACK_SENT, it is recommended to also filter feedback_id to target results accurately.

", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "filter", + "in": "query", + "description": "Use this parameter to limit the response based on the specified filter parameters as follows:
Send the filter as a query parameter in a comma-separated name:value list. For example:

filter=commentType:POSITIVE,filterImage:true,topics:fit,period:30,role:SELLER,showAutomatedFeedback:true

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "limit", + "in": "query", + "description": "Use this parameter to set the maximum number of items to return per page of data.

Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, with offset set to 20 and limit set to 10, the call retrieves entries 21 through 30 from the result set.

Although this field is optional, if omitted the default value of 25 is used.

Default: 25

Minimum: 25

Maximum: 200

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "listing_id", + "in": "query", + "description": "Use this field to limit feedback entries to those associated with a specified listing.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "offset", + "in": "query", + "description": "Use this field to specify the number of line items to skip in the result set. This is used with the limit field to control the pagination of the output. For example:

Note: This feature employs a zero-based list, where the first line item in the list has an offset of 0.

If this parameter is not set, its value defaults to 0 which returns the first page of records.

Default: 0

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "order_line_item_id", + "in": "query", + "description": "Use this field to retrieve specific feedback entries related to an order line item ID. A maximum of two entries may be retrieved: feedback left by the buyer and feedback left by the seller.

Note: If this query parameter is set, no other filters will be applicable.

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "sort", + "in": "query", + "description": "Use this parameter to configure the order of the returned items. The time is based on when the buyer paid for the line item. Acceptable values:

If this parameter is omitted, its value defaults to RELEVANCE.

Default: RELEVANCE

", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "transaction_id", + "in": "query", + "description": "Use this field to limit feedback entries to those associated with the specified transaction ID.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "query", + "description": "Use this field to specify the unique identifier user ID (eBay username of the user) of the account for which feedback is being retrieved.

Note: Both usernames and public user IDs will be accepted in this field. For more information, please refer to Data Handling Compliance.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetFeedbackResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "x-response-codes": { + "errors": { + "501000": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Username request parameter is required or is invalid." + }, + "501001": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Feedback type request parameter is required or invalid. Must be FEEDBACK_RECEIVED or FEEDBACK_SENT." + }, + "501002": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Unsupported request parameter combination." + }, + "501003": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Listing id request parameter is invalid." + }, + "501025": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Input user role value is invalid." + }, + "501035": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Invalid sort type value. Must be RELEVANCE or TIME." + }, + "501036": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Invalid overall rating value. Must be POSITIVE, NEUTRAL, or NEGATIVE." + }, + "501037": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Invalid period value. Must be 30, 60, or 365." + }, + "501038": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Invalid topics value. Must be from the allowed topics list." + }, + "501039": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Feedback not found for the given request parameters." + } + } + } + }, + "401": { + "description": "Not Authorized", + "x-response-codes": { + "errors": { + "1001": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "Invalid access token. Check the value of the Authorization HTTP request header." + } + } + } + }, + "500": { + "description": "Internal Server Error", + "x-response-codes": { + "errors": { + "2003": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." + } + } + } + } + }, + "security": [ + { + "api_auth": [ + "https://api.ebay.com/oauth/api_scope/commerce.feedback", + "https://api.ebay.com/oauth/api_scope/commerce.feedback.readonly" + ] + } + ] + }, + "post": { + "tags": [ + "feedback" + ], + "description": "This method creates and submits feedback to the user's order partner for a line item in the order. For each order, the order partner is the other participant in the transaction, either the buyer or seller, depending on the eBay user associated with the user token. This method allows users to provide detailed information about the transaction, including the feedback rating, comments, and seller delivery. You can also add images to your feedback.

Note: A seller can only provide a comment for a buyer, but a buyer can provide a comment plus provides ratings on a number of metrics for a seller.

Note: The feedback must adhere to community guidelines and be relevant to the transaction.

When leaving feedback, keep the following in mind:

For additional information on leaving feedback, see the following:

A successful call to this method returns a feedback ID, which is a unique identifier for the newly created feedback and allows for reference and tracking.

", + "operationId": "leaveFeedback", + "parameters": [ + { + "name": "Content-Type", + "in": "header", + "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Request body for leaving feedback. Required fields: commentText (the text of the feedback comment), commentType (acceptable values - [POSITIVE, NEUTRAL, NEGATIVE]), listingId (the listingId of the item the feedback is being left for), transactionId (the transactionId for the order), orderLineItemId (Search by order line item ID. order line item id is a concatenation of listing ID and transaction ID, joined by `-`. Ex `listing_id-transaction_id`), sellerRatings (array of ratings with keys - [ON_TIME_DELIVERY, ITEM_AS_DESCRIBED, COMMUNICATION, SHIPPING_CHARGES, SHIPPING_TIME]), images (array of images with url field, can add upto 5 images)", + "content": { + "application/json": { + "schema": { + "description": "Request body for leaving feedback. Required fields: commentText (the text of the feedback comment), commentType (acceptable values - [POSITIVE, NEUTRAL, NEGATIVE]), listingId (the listingId of the item the feedback is being left for), transactionId (the transactionId for the order), orderLineItemId (Search by order line item ID. order line item id is a concatenation of listing ID and transaction ID, joined by `-`. Ex `listing_id-transaction_id`), sellerRatings (array of ratings with keys - [ON_TIME_DELIVERY, ITEM_AS_DESCRIBED, COMMUNICATION, SHIPPING_CHARGES, SHIPPING_TIME]), images (array of images with url field, can add upto 5 images)", + "$ref": "#/components/schemas/LeaveFeedbackRequest" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/LeaveFeedbackResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "x-response-codes": { + "errors": { + "501003": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Listing id request parameter is invalid." + }, + "501004": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Transaction id request parameter is invalid." + }, + "501005": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Comment text request parameter is invalid." + }, + "501006": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Comment type request parameter is invalid." + }, + "501007": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Seller ratings are not valid type." + }, + "501013": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Comment text is too long, maximum length is 500 characters." + }, + "501014": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Comment text value is invalid." + }, + "501015": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Comment text contains profanity." + }, + "501016": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Seller ratings value is invalid." + }, + "501017": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Seller ratings type is not supported for this provider role." + }, + "501018": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Item rating type is invalid." + }, + "501019": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "On time delivery rating value is invalid." + }, + "501034": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Only 5 images can be attached to a feedback." + } + } + } + }, + "401": { + "description": "Not Authorized", + "x-response-codes": { + "errors": { + "1001": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "Invalid access token. Check the value of the Authorization HTTP request header." + } + } + } + }, + "409": { + "description": "Conflict", + "x-response-codes": { + "errors": { + "501008": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Feedback already left for this listing." + }, + "501009": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Leaving feedback for this listing is blocked due to policy, please contact eBay support." + }, + "501010": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Feedback receiver is not eligible to receive feedback." + }, + "501011": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Feedback provider is not eligible to leave feedback." + }, + "501012": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Feedback provider is relatively new to eBay. Provider should be at least 5 days on ebay." + }, + "501020": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Seller cannot leave negative or neutral feedback." + }, + "501021": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Seller cannot receive negative or neutral feedback." + } + } + } + }, + "500": { + "description": "Internal Server Error", + "x-response-codes": { + "errors": { + "2003": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." + } + } + } + } + }, + "security": [ + { + "api_auth": [ + "https://api.ebay.com/oauth/api_scope/commerce.feedback" + ] + } + ] + } + }, + "/feedback_rating_summary": { + "get": { + "tags": [ + "feedback_rating_summary" + ], + "description": "This method provides a detailed overview of feedback ratings associated with a user in the eBay marketplace. Specify a user ID and apply filters to retrieve summarized feedback data categorized by rating types and user roles. These returned metrics are aggregated, which offers insight into user experiences and performance.

Tip: You can use this method to help sellers and buyers understand their marketplace reputation and identify areas for improvement.

Returned data provides a summary of feedback ratings for a user by rating type (such as overall experience, communication, or delivery timeliness) for both buyer and seller roles. Each type of rating includes aggregated metrics like averages, counts, unique feedback givers, and the percentage of positive ratings (excluding neutrals). The response also details the distribution of specific rating values, their frequency, and time period (with period units like days or months) over which these metrics were calculated.

", + "operationId": "getFeedbackRatingSummary", + "parameters": [ + { + "name": "filter", + "in": "query", + "description": "Use this parameter to limit the response based on specified filter values:

You can send the filter as a query parameter, either with the required ratingType only, or combining the filter values with a comma-separated name:value list. For example:

filter=ratingType:OVERALL_EXPERIENCE,excludeRepeatFeedback:true,period:365

", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "user_id", + "in": "query", + "description": "Use this parameter to specify the unique identifier (the eBay username associated with the account) for the eBay user whose feedback summary is being retrieved.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/GetFeedbackRatingSummaryResponse" + } + } + } + }, + "400": { + "description": "Bad Request", + "x-response-codes": { + "errors": { + "501002": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Unsupported request parameter combination." + }, + "501007": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Seller ratings are not valid type." + }, + "501022": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Rating type request parameter is invalid." + }, + "501037": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Invalid period value. Must be 30, 60, or 365." + } + } + } + }, + "401": { + "description": "Not Authorized", + "x-response-codes": { + "errors": { + "1001": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "Invalid access token. Check the value of the Authorization HTTP request header." + } + } + } + }, + "404": { + "description": "Not Found", + "x-response-codes": { + "errors": { + "501023": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "Feedback rating summary user not found." + } + } + } + }, + "500": { + "description": "Internal Server Error", + "x-response-codes": { + "errors": { + "2003": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." + } + } + } + } + }, + "security": [ + { + "api_auth": [ + "https://api.ebay.com/oauth/api_scope/commerce.feedback", + "https://api.ebay.com/oauth/api_scope/commerce.feedback.readonly" + ] + } + ] + } + }, + "/respond_to_feedback": { + "post": { + "tags": [ + "respond_to_feedback" + ], + "description": "This method allows users to respond to feedback provided by the order partner for a specific line item in an order. For each order, the order partner is the other participant in the transaction, either the buyer or seller, depending on the eBay user associated with the user token. This method allows the user to provide additional context or address the order partner's feedback.

Note: The feedback response must adhere to community guidelines and be relevant to the transaction.

You can only use this method if feedback has been provided by the order partner and you have not yet responded to it.

When responding to feedback, your feedback score is not affected when you respond to feedback.

For additional information on leaving feedback, see the following:

A successful call returns an HTTP status of 200 Success.

", + "operationId": "respondToFeedback", + "parameters": [ + { + "name": "Content-Type", + "in": "header", + "description": "This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "This provides the request body for responding to feedback.", + "content": { + "application/json": { + "schema": { + "description": "This provides the request body for responding to feedback.", + "$ref": "#/components/schemas/RespondToFeedbackRequest" + } + } + }, + "required": false + }, + "responses": { + "200": { + "description": "Success", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + }, + "400": { + "description": "Bad Request", + "x-response-codes": { + "errors": { + "501013": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Comment text is too long, maximum length is 500 characters." + }, + "501014": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Comment text value is invalid." + }, + "501015": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Comment text contains profanity." + }, + "501026": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Feedback ID request parameter is required or is invalid." + }, + "501027": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Response type request parameter is required or is invalid. Must be REPLY or FOLLOW_UP." + }, + "501028": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Response text request parameter is required." + }, + "501029": { + "domain": "API_FEEDBACK", + "category": "REQUEST", + "description": "Recipient user ID request parameter is required." + } + } + } + }, + "401": { + "description": "Not Authorized", + "x-response-codes": { + "errors": { + "1001": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "Invalid access token. Check the value of the Authorization HTTP request header." + } + } + } + }, + "403": { + "description": "Forbidden", + "x-response-codes": { + "errors": { + "501031": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Reply not allowed for automated feedback." + } + } + } + }, + "409": { + "description": "Conflict", + "x-response-codes": { + "errors": { + "501011": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Feedback provider is not eligible to leave feedback." + }, + "501032": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Reply already left for feedback." + }, + "501033": { + "domain": "API_FEEDBACK", + "category": "BUSINESS", + "description": "Follow up comment already left for feedback." + } + } + } + }, + "500": { + "description": "Internal Server Error", + "x-response-codes": { + "errors": { + "2003": { + "domain": "API_FEEDBACK", + "category": "APPLICATION", + "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." + } + } + } + } + }, + "security": [ + { + "api_auth": [ + "https://api.ebay.com/oauth/api_scope/commerce.feedback" + ] + } + ] + } + } + }, + "components": { + "schemas": { + "AwaitingFeedback": { + "type": "object", + "properties": { + "listingId": { + "type": "string", + "description": "This is the unique identifier for the listing associated with the line item. It is used to reference the specific listing for which feedback is being awaited." + }, + "listingPrice": { + "description": "This container shows the sales price of the listing.", + "$ref": "#/components/schemas/ListingPrice" + }, + "listingTitle": { + "type": "string", + "description": "The title of the listing." + }, + "orderLineItemId": { + "type": "string", + "description": "The unique identifier for the eBay order line item associated with the listing. It is used to pinpoint the exact line item for which feedback is being awaited." + }, + "ratingTemplates": { + "type": "array", + "description": "This array contains a list of available values for use in a particular rating, and whether the value is enabled. This is dependent on what seller ratings the buyer's order partner qualifies.

Note: Rating templates should only be returned to the user in their role as a buyer; only sellers have Detailed Seller Ratings (DSRs).

Use the metadata returned here when leaving DSR ratings through the leaveFeedback method. The key field in this container is the ratingKey field. See FeedbackRatingTypeEnum for its values. The other metadata returned in this container apply to each ratingKey value that is returned.

", + "items": { + "$ref": "#/components/schemas/FeedbackRatingTemplateType" + } + }, + "transactionId": { + "type": "string", + "description": "The unique identifier of the sales transaction." + } + }, + "description": "This type contains the details for each line item awaiting feedback." + }, + "AwaitingFeedbackResponse": { + "type": "object", + "properties": { + "itemsAwaitingFeedbackCount": { + "description": "This container returns the number of line items awaiting feedback. The asSeller and asBuyer fields return the total count of items awaiting feedback as seller and buyer and are not affected by the userRole filter.", + "$ref": "#/components/schemas/ItemsAwaitingFeedbackCount" + }, + "lineItems": { + "type": "array", + "description": "This array contains the details for each line item awaiting feedback. An empty array is returned if no line items are awaiting feedback or that match the filter criteria.", + "items": { + "$ref": "#/components/schemas/AwaitingFeedback" + } + }, + "pagination": { + "description": "This container provides pagination information for the returned line items awaiting feedback (as filtered).", + "$ref": "#/components/schemas/Pagination" + } + }, + "description": "This type defines the fields for the getItemsAwaitingFeedback response." + }, + "Comment": { + "type": "object", + "properties": { + "commentPeriod": { + "description": "This container indicates the timing of a feedback comment based on when it was left. It is only returned if a comment was provided. Possible values are 30 days, 90 days, 180 days, 365 days, or 5 years:
", + "$ref": "#/components/schemas/CommentCommentPeriod" + }, + "commentText": { + "type": "string", + "description": "The text of the feedback comment, follow-up, or reply. HTML formatting and personal information (for example, phone numbers) are not allowed. This field is returned if a comment was provided for the feedback entry. If the comment was removed due to eBay policy, this field will contain '--' and the commentTextRemovedPerPolicy field will return true." + }, + "commentTextRemovedPerPolicy": { + "type": "boolean", + "description": "If true, this boolean indicates the feedback follow-up or reply comment text was removed per eBay policy. This field is only returned when a followupComment container is returned." + }, + "state": { + "type": "string", + "description": "This enumerated value indicates the state of the feedback (for example, ENTERED). This can be the state of the feedback comment, the follow-up comment, or the reply comment. For implementation help, refer to eBay API documentation" + } + }, + "description": "This type provides the details of the feedback comment left by the user." + }, + "CommentCommentPeriod": { + "type": "object", + "properties": { + "unit": { + "type": "string", + "description": "Unit of time for the value. Supported values: DAY, or YEAR." + }, + "value": { + "type": "integer", + "description": "Value of the time period expressed in the period contained in the unit. Supported values: 30, 60, or 365.

See the commentPeriod container for more information.

", + "format": "int32" + } + }, + "description": "This type provides fields that descrbes timing associated with the comment." + }, + "Error": { + "type": "object", + "properties": { + "category": { + "type": "string", + "description": "Identifies the type of erro." + }, + "domain": { + "type": "string", + "description": "Name for the primary system where the error occurred. This is relevant for application errors." + }, + "errorId": { + "type": "integer", + "description": "A unique number to identify the error.", + "format": "int32" + }, + "inputRefIds": { + "type": "array", + "description": "An array of request elements most closely associated to the error.", + "items": { + "type": "string" + } + }, + "longMessage": { + "type": "string", + "description": "A more detailed explanation of the error." + }, + "message": { + "type": "string", + "description": "Information on how to correct the problem, in the end user's terms and language where applicable." + }, + "outputRefIds": { + "type": "array", + "description": "An array of request elements most closely associated to the error.", + "items": { + "type": "string" + } + }, + "parameters": { + "type": "array", + "description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.", + "items": { + "$ref": "#/components/schemas/ErrorParameter" + } + }, + "subdomain": { + "type": "string", + "description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc." + } + }, + "description": "This type defines the fields that can be returned in an error." + }, + "ErrorParameter": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The object of the error." + }, + "value": { + "type": "string", + "description": "The value of the object." + } + } + }, + "FeedbackDetail": { + "type": "object", + "properties": { + "automatedFeedback": { + "type": "boolean", + "description": "If the returned value is true, feedback was generated and added automatically by eBay. If a seller has a feedback score 10 or less, eBay automatically leaves feedback. The buyer can choose to override the eBay feedback and leave feedback normally.

Note: Detailed Seller Ratings (DSRs) are not provided by ebay, only a predefined comment and a positive rating.

" + }, + "commentType": { + "type": "string", + "description": "This enumerated value indicates the type of feedback: POSITIVE, NEUTRAL, NEGATIVE.

Note: Sellers can only leave positive feedback for buyers.

For implementation help, refer to eBay API documentation" + }, + "eligibleForRevision": { + "type": "boolean", + "description": "This boolean indicates whether the feedback is eligible for revision. If returned as true, it means the feedback can be modified. Feedback that is older than 30 days or has already been revised once cannot be erased or further revised." + }, + "feedbackComment": { + "description": "This container provides the feedback comment left by a user when submitting feedback for a seller or buyer.", + "$ref": "#/components/schemas/Comment" + }, + "feedbackEnteredDate": { + "type": "string", + "description": "The timestamp when the feedback was submitted." + }, + "feedbackEnteredPeriod": { + "description": "This container represents the duration since feedback was entered, expressed as a numeric value and a unit of time in days.", + "$ref": "#/components/schemas/FeedbackEnteredPeriod" + }, + "feedbackId": { + "type": "string", + "description": "The unique identifier of the feedback entry." + }, + "feedbackRatings": { + "type": "array", + "description": "This array contains a list of ratings attached to feedback.

Note: This array only applies to buyers feedback for sellers (sellers can only give positive feedback to buyers).

", + "items": { + "$ref": "#/components/schemas/FeedbackRating" + } + }, + "feedbackScore": { + "type": "integer", + "description": "The feedback receiver's feedback score after receiving this specific feedback.", + "format": "int32" + }, + "feedbackState": { + "type": "string", + "description": "This enumerated value indicates the current state of the feedback entry (for example, ENTERED). For implementation help, refer to eBay API documentation" + }, + "followupComment": { + "description": "This container provides the details of any follow-up comment left.

Note: A buyer leaves followup comments, and a seller leaves reply comments.

", + "$ref": "#/components/schemas/Comment" + }, + "hasImages": { + "type": "boolean", + "description": "If returned as true, this boolean indicates that the feedback entry has one or more images attached. If false, there are no images attached." + }, + "images": { + "type": "array", + "description": "This array contains the list of attached images.", + "items": { + "$ref": "#/components/schemas/Image" + } + }, + "orderLineItemSummary": { + "description": "This container provides a summary of the line item associated with the feedback entry.

Note: Certain fields within this container are returned only when the request uses the Authorization code grant flow (user access token) and the user_id matches the authenticated user. These fields are not returned when accessing a different user_id or when using the Client credentials grant flow (application access token). See OAuth scope for for details on the flows and required permissions.

", + "$ref": "#/components/schemas/OrderLineItemSummary" + }, + "providerUserDetail": { + "description": "This container details the attributes of the user who provided the feedback.", + "$ref": "#/components/schemas/ProviderUserDetail" + }, + "repliedBeforeFollowup": { + "type": "boolean", + "description": "If returned as true, this boolean indicates the feedback reply was given by the seller before the follow-up comment was given buy the buyer." + }, + "replyComment": { + "description": "This container provides the details of any reply to the feedback.

Note: A buyer leaves followup comments, and a seller leaves reply comments.

", + "$ref": "#/components/schemas/Comment" + }, + "topics": { + "type": "array", + "description": "This array provides descriptions of AI-generated insights related to a feedback entry for the specified filter topic. The feedback provided is considered relevant to the requested topic. For example, when using the request parameter filter of topics:product-satisfaction, the returned array might be: 

{
  \"coarseTopic\" : \"product-satisfaction\",
  \"highlightedTexts\" : [
    \"This machine is amazing\",
    \"Very happy with this purchase\"
    ],
  \"sentiment\" : \"Positive\"
}

If no topics exist for that feedback, an empty array is returned.

", + "items": { + "$ref": "#/components/schemas/Topic" + } + } + }, + "description": "This type provides attributes for returned feedback entries." + }, + "FeedbackEnteredPeriod": { + "type": "object", + "properties": { + "unit": { + "type": "string", + "description": "The unit for the feedback entry period's value. Supported value: DAY." + }, + "value": { + "type": "integer", + "description": "The value for the feedback entry period, specified in units of unit. Supported values: 7, 30, 90, 180, or 365.", + "format": "int32" + } + }, + "description": "This type specifies the amount of time elapsed associated with a feedback entry." + }, + "FeedbackMetrics": { + "type": "object", + "properties": { + "metricName": { + "type": "string", + "description": "This enumerated value specifies the type of feedback aggregation. For example, AVG would indicate the feedback returned represents the average value of the feedback. See metricValue for the value of the returned feedback. For implementation help, refer to eBay API documentation" + }, + "metricValue": { + "type": "number", + "description": "The decimal value of the specified metric. For example, 55.8 would represent a value associated with the metricName (see metricName for interpretation and units)." + } + }, + "description": "This type provides fields for the array of metrics associated with feedback aggregation." + }, + "FeedbackRating": { + "type": "object", + "properties": { + "ratingType": { + "type": "string", + "description": "This enumerated value indicates the type of rating (for example, OVERALL_EXPERIENCE, DSR_ITEM_AS_DESCRIBED). For implementation help, refer to eBay API documentation" + }, + "value": { + "type": "string", + "description": "The value assigned to the rating, specified as a string representing a number from 1 to 5, with 1 representing the lowest rating and 5 representing the highest rating." + } + }, + "description": "This type provides for fields in ratings attached to feedback." + }, + "FeedbackRatingAcceptableValue": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "If true, this boolean indicates that this value is enabled and selectable." + }, + "value": { + "type": "string", + "description": "The value that can be selected for feedback. For most ratingType values, this is 1 through 5, with 1 representing the lowest rating and 5 representing the highest rating. For ratingType of OVERALL_EXPERIENCE, this can be POSITIVE, NEGATIVE, and NEUTRAL. These are the same values as used with the leaveFeedback methods." + }, + "valueLabel": { + "type": "string", + "description": "This field provides information about the corresponding value." + } + }, + "description": "This type provides fields for available values for use in a particular rating, and whether the value is enabled." + }, + "FeedbackRatingSummary": { + "type": "object", + "properties": { + "ratingSummaryByRatingType": { + "type": "array", + "description": "An array that includes metrics and distributions for each rating type.", + "items": { + "$ref": "#/components/schemas/RatingSummaryByRatingType" + } + }, + "ratingType": { + "type": "string", + "description": "This enumerated value indicates the type of rating being summarized. For example, OVERALL_EXPERIENCE indicates the rating applies to the overall transaction experience. For implementation help, refer to eBay API documentation" + } + }, + "description": "This type provides fields for an array containing a summary of feedback ratings. Each element provides detailed metrics and distributions for specific rating types." + }, + "FeedbackRatingTemplateType": { + "type": "object", + "properties": { + "acceptableValues": { + "type": "array", + "description": "This array contains a list of available values for use in a particular rating, and whether the value is enabled. Provided if ratingValueType is RANGE or PREDEFINED.

The following is an example of a predefined list:

[
  {
    \"value\": \"POSITIVE\",
    \"valueLabel\": \"Positive\",
    \"enabled\": true
  },
  {
    \"value\": \"NEUTRAL\",
    \"valueLabel\": \"Neutral\",
    \"enabled\": true
  },
  {
    \"value\": \"NEGATIVE\",
    \"valueLabel\": \"Negative\",
    \"enabled\": true
  }
]
For other examples, see the Using rating templates.", + "items": { + "$ref": "#/components/schemas/FeedbackRatingAcceptableValue" + } + }, + "defaultValue": { + "type": "string", + "description": "The default value preselected for the rating, if set." + }, + "earlyFeedbackMessage": { + "type": "string", + "description": "For eligible sellers, a message may be shown requiring a wait period before you can leave neutral or negative feedback." + }, + "enabled": { + "type": "boolean", + "description": "If returned as true, this boolean indicates that the corresponding feedback rating template is enabled for the user to provide feedback for this line item. This value will generally be true when the user role is a buyer, but false when the user role is a seller because buyers do not have Detailed Seller Ratings (DSRs)." + }, + "maximumCharactersAllowed": { + "type": "integer", + "description": "The maximum number of characters allowed to be used for a rating that uses free text. It is only applicable for a rating whose ratingValueType is FREETEXT.

Maximum: 500

", + "format": "int32" + }, + "multiValueRating": { + "type": "boolean", + "description": "If returned as true, multiple values can be specified for the rating." + }, + "ratingKey": { + "type": "string", + "description": "This enumerated value indicates the type of rating that is tracked for the seller. All of the metadata returned under each node for the ratingTemplates array will apply to this rating type. For example, the value OVERALL_EXPERIENCE indicates the rating is for the overall transaction experience. For implementation help, refer to eBay API documentation" + }, + "ratingLabel": { + "type": "string", + "description": "This field provides more details about and/or provides guidance on the corresponding rating type. For example, the rating label of Rate this transaction describes the feedback for the user to enter for an OVERALL_EXPERIENCE ratingKey." + }, + "ratingValueType": { + "type": "string", + "description": "This enumerated value indicates the type of data used to provide the specific feedback rating.

If set to PREDEFINED or RANGE, is returned here, more information on the supported values will be returned under the acceptableValues array. If FREETEXT is returned here, the maximum number of characters supported can be seen in the maximumCharactersAllowed field.

For implementation help, refer to eBay API documentation" + }, + "required": { + "type": "boolean", + "description": "If returned as true, this rating type is required when leaving feedback." + } + }, + "description": "This type defines fields for user feedback collection, including acceptable values, a default preselection value, and an early feedback message. It also provides fields to enable the template, and limits and options for freetext character, multi-value rating, and other similar features." + }, + "FeedbackRatingValueDistribution": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "description": "An integer representing the number of occurrences for a specific feedback rating value. For example, for the POSITIVE value, a 3 returned as the count represents three positive ratings were returned.", + "format": "int32" + }, + "value": { + "type": "string", + "description": "A string indicating the specific feedback rating value. Supported values include: POSITIVE, NEUTRAL, NEGATIVE, 1, 2, 3, 4, and 5." + } + }, + "description": "This type provides field for an array listing the distribution values of the feedback ratings." + }, + "GetFeedbackRatingSummaryResponse": { + "type": "object", + "properties": { + "feedbackRatingSummary": { + "type": "array", + "description": "An array containing a summary of feedback ratings. Each element provides detailed metrics and distributions for specific rating types.", + "items": { + "$ref": "#/components/schemas/FeedbackRatingSummary" + } + } + }, + "description": "This type defines the fields for the getFeedbackRatingSummary response." + }, + "GetFeedbackResponse": { + "type": "object", + "properties": { + "feedbackEntries": { + "type": "array", + "description": "This array contains a list of feedback entries that meet the specified criteria.", + "items": { + "$ref": "#/components/schemas/FeedbackDetail" + } + }, + "pagination": { + "description": "This container provides pagination information for the returned feedback response (as filtered).", + "$ref": "#/components/schemas/Pagination" + } + }, + "description": "This type defines the fields for the getFeedback response." + }, + "Image": { + "type": "object", + "properties": { + "url": { + "type": "string", + "description": "This field provides the URL of an attached image and is included in the response whenever an image is attached." + } + }, + "description": "This type provides a field for image URLs." + }, + "ItemsAwaitingFeedbackCount": { + "type": "object", + "properties": { + "asBuyer": { + "type": "integer", + "description": "The number of line items for which feedback is pending from the user in the buyer role.", + "format": "int32" + }, + "asSeller": { + "type": "integer", + "description": "The number of line items for which feedback is pending from the user in the seller role.", + "format": "int32" + } + }, + "description": "This type returns the number of line items awaiting feedback." + }, + "LeaveFeedbackRequest": { + "type": "object", + "properties": { + "commentText": { + "type": "string", + "description": "Use this field to provide the feedback left by the user, describing their experience with the line item of the transaction. No HTML formatting or personal information (such as phone numbers) is permitted.

Maximum length: 500 characters

" + }, + "commentType": { + "type": "string", + "description": "Set this enumerated value to indicate the overall rating of the transaction: POSITIVE, NEUTRAL, or NEGATIVE.

Note: Sellers can only provide positive feedback.

For implementation help, refer to eBay API documentation" + }, + "images": { + "type": "array", + "description": "Use this array to optionally list up to 5 images attached to the feedback.", + "items": { + "$ref": "#/components/schemas/Image" + } + }, + "listingId": { + "type": "string", + "description": "Use this field to provide the listing ID related to the transaction." + }, + "orderLineItemId": { + "type": "string", + "description": "Use this field to provide the unique identifier of the line item for this feedback." + }, + "sellerRatings": { + "type": "array", + "description": "Use this array to list ratings for specific aspects of the seller's performance.", + "items": { + "$ref": "#/components/schemas/SellerRating" + } + }, + "transactionId": { + "type": "string", + "description": "Use this field to provide the unique identifier of the transaction for this feedback." + } + }, + "description": "This type provides fields available to leave feedback in the leaveFeedback request." + }, + "LeaveFeedbackResponse": { + "type": "object", + "properties": { + "feedbackId": { + "type": "string", + "description": "The unique ID assigned to the submitted feedback." + } + }, + "description": "This type defines the fields for the leaveFeedback response for feedback that has been left." + }, + "ListingPrice": { + "type": "object", + "properties": { + "currency": { + "type": "string", + "description": "This field provides the three-letter ISO 4217 code that represents the currency of the amount in the value field. Both the value and currency fields are always returned when expressing prices." + }, + "value": { + "type": "number", + "description": "This field contains the numerical value of the listing price in the currency specified in the currency field. Both the value and currency fields are always returned when expressing prices." + } + }, + "description": "This type provides details about the price of the listing awaiting feedback." + }, + "OrderLineItemAttribute": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "This enumerated value indicates an attribute of the line item. The value field indicates if the attribute applies. For implementation help, refer to eBay API documentation" + }, + "value": { + "type": "string", + "description": "If returned as true, the line item attribute name applies; if returned as false, the attribute does not apply." + } + }, + "description": "This type describes line item attributes." + }, + "OrderLineItemSummary": { + "type": "object", + "properties": { + "listingId": { + "type": "string", + "description": "This field provides the unique identifier for the listing associated with the feedback entry. Conditionally returned based on the authorization flow and user context. See orderLineItemSummary for details on when this field is included." + }, + "listingPrice": { + "description": "This container provides the sale price of the listing. Conditionally returned based on the authorization flow and user context. See orderLineItemSummary for details on when this field is included.", + "$ref": "#/components/schemas/ListingPrice" + }, + "listingTitle": { + "type": "string", + "description": "This field contains the title of the listing. Conditionally returned based on the authorization flow and user context. See orderLineItemSummary for details on when this field is included." + }, + "orderLineItemAttributes": { + "type": "array", + "description": "This array describes order line attributes including names and values of a transaction.", + "items": { + "$ref": "#/components/schemas/OrderLineItemAttribute" + } + }, + "orderLineItemId": { + "type": "string", + "description": "The unique identifier of the line item for this feedback. Conditionally returned based on the authorization flow and user context. See orderLineItemSummary for details on when this field is included." + }, + "transactionPeriod": { + "description": "This container indicates if the time since the item was bought on ebay is less than, more than, or equal to 90 days", + "$ref": "#/components/schemas/TransactionPeriod" + } + }, + "description": "This type provides fields for a summary of the line item related to feedback." + }, + "Pagination": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "description": "This value indicates the number of feedback entries on the current response page.", + "format": "int32" + }, + "limit": { + "type": "integer", + "description": "The value of the limit parameter submitted in the request. This is the maximum number of line items, as filtered, awaiting feedback to return per page from the result set. This field indicates the number of line items returned per page of data.

Note: If this is the last or only page of the result set, the page may contain fewer line items than the limit value.

If a limit parameter was not included in the request, this value will default to 25, returning up to 25 line items on each page.

Default: 25

", + "format": "int32" + }, + "next": { + "type": "string", + "description": "The relative URI for the next page of results starting with the resource name. This URI is returned if there is an additional page of results in the result set." + }, + "offset": { + "type": "integer", + "description": "The value of the offset parameter submitted in the request. This field indicates how many results were skipped in the response. If an offset parameter was not included in the request, this value will default to 0, returning the first page of results.

Default: 0

", + "format": "int32" + }, + "prev": { + "type": "string", + "description": "The relative URI for the previous page of results starting with the resource name. This URI is returned if there is a previous page of results in the result set.

" + }, + "total": { + "type": "integer", + "description": "The total number of line items available that match the filter criteria.

Note: If the total value exceeds the limit value, there are multiple pages of results.

", + "format": "int32" + } + }, + "description": "This type provides pagination information for the returned line items." + }, + "Period": { + "type": "object", + "properties": { + "unit": { + "type": "string", + "description": "The unit of the period's value. Supported value: DAY." + }, + "value": { + "type": "integer", + "description": "The value for the feedback period, specified in units of unit. Supported value: 90.", + "format": "int32" + } + }, + "description": "This type provides fields for the time period on which the feedback summary is calculated." + }, + "ProviderUserDetail": { + "type": "object", + "properties": { + "feedbackScore": { + "type": "integer", + "description": "This integer indicates the feedback score of the feedback provider at the time of providing this specific feedback.", + "format": "int32" + }, + "feedbackStar": { + "type": "string", + "description": "This enumerated value provides the visual star representation of the feedback score (for example, YELLOW_STAR). For implementation help, refer to eBay API documentation" + }, + "role": { + "type": "string", + "description": "This enumerated value indicates the user's role in the transaction (BUYER or SELLER). For implementation help, refer to eBay API documentation" + }, + "userAttributes": { + "type": "array", + "description": "This array lists additional attributes that relate to the user (such as verification status).", + "items": { + "$ref": "#/components/schemas/ProviderUserDetailUserAttributes" + } + }, + "userId": { + "type": "string", + "description": "This field indicates the unique identifier of the user who gave the feedback.

Note: Select developers will not receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to Data Handling Compliance." + } + }, + "description": "This type provides the details of the user who provided the feedback of a getFeedback response." + }, + "ProviderUserDetailUserAttributes": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "This enumerated value indicates an attribute of the user (for example, USER_VERIFIED). The value field indicates if the attribute applies. For implementation help, refer to eBay API documentation" + }, + "value": { + "type": "string", + "description": "If returned as true, the user attribute name applies; if returned as false, the attribute does not apply." + } + }, + "description": "This type defines the attributes of the user who provided the feedback of a getFeedback response." + }, + "RatingSummaryByRatingType": { + "type": "object", + "properties": { + "feedbackMetrics": { + "type": "array", + "description": "An array of metrics associated with feedback aggregation.", + "items": { + "$ref": "#/components/schemas/FeedbackMetrics" + } + }, + "feedbackRatingValueDistribution": { + "type": "array", + "description": "An array listing the distribution values of the feedback ratings.", + "items": { + "$ref": "#/components/schemas/FeedbackRatingValueDistribution" + } + }, + "period": { + "description": "The time period on which the feedback summary is calculated.", + "$ref": "#/components/schemas/Period" + }, + "userRoleType": { + "type": "string", + "description": "This enumerated value indicates the user's role in the feedback (BUYER or SELLER). For implementation help, refer to eBay API documentation" + } + }, + "description": "This type provides fields for an array that includes metrics and distributions for each rating type." + }, + "RespondToFeedbackRequest": { + "type": "object", + "properties": { + "feedbackId": { + "type": "string", + "description": "Use this field to provide the unique identifier for the feedback being responded to, used to specify the feedback entry associated with the feedback response. This value can be returned using the getFeedback method (feedbackId field)." + }, + "recipientUserId": { + "type": "string", + "description": "Use this field to provide the identifier of the user who provided the original feedback. This value can be returned using the getFeedback method (userId field).

Note: Both usernames and public user IDs will be accepted in this field. For more information, please refer to Data Handling Compliance." + }, + "responseText": { + "type": "string", + "description": "Use this field to provide the text content of the response. This field is used to provide additional context or address the feedback given by the order partner. No HTML formatting or personal information (such as phone numbers) is permitted.

Maximum length: 500 characters." + }, + "responseType": { + "type": "string", + "description": "Set this enumerated value to describe the type of response being submitted (for example, a REPLY or a FOLLOW_UP). For implementation help, refer to eBay API documentation" + } + }, + "description": "The type that defines the fields for the respondToFeedback request." + }, + "SellerRating": { + "type": "object", + "properties": { + "key": { + "type": "string", + "description": "The enumerated value of the category being rated, such as delivery timeliness (ON_TIME_DELIVERY). For implementation help, refer to eBay API documentation" + }, + "value": { + "type": "string", + "description": "The value assigned for the selected category. Use a value of 1 through 5, with the 1 being the lowest rating and 5 being the highest." + } + }, + "description": "This type provides fields for specific aspects of the seller's performance." + }, + "Topic": { + "type": "object", + "properties": { + "coarseTopic": { + "type": "string", + "description": "The main topic (or category) detected in the comment. See the available topics in filter." + }, + "fineTopic": { + "type": "string", + "description": "

Note: Fine topics are not currently supported.

A more specific detail or subtopic related to the coarse topic. " + }, + "highlightedTexts": { + "type": "array", + "description": "This array lists any text snippets, phrases, or examples, from the feedback that supports the detected topic.", + "items": { + "type": "string" + } + }, + "sentiment": { + "type": "string", + "description": "This field indicates a classification of the feedback, whether the feedback is Positive, Negative, or Neutral." + } + }, + "description": "This type provides subject-based fields derived from feedback." + }, + "TransactionPeriod": { + "type": "object", + "properties": { + "period": { + "description": "This container indicates if the time since the item was bought on ebay is less than, more than, or equal to 90 days.", + "$ref": "#/components/schemas/Period" + }, + "thresholdType": { + "type": "string", + "description": "This enumerated value indicates whether a transaction period exceeds, falls short, or matches the threshold. You can use this field to trigger specific logic or actions based on whether a transaction period exceeds, falls short, or matches the threshold. For implementation help, refer to eBay API documentation" + } + }, + "description": "This type specifies the amount of time elapsed and the threshold associated with a transaction." + } + }, + "securitySchemes": { + "api_auth": { + "type": "oauth2", + "description": "The security definitions for this API. Please check individual operations for applicable scopes.", + "flows": {} + } + } + } +} \ No newline at end of file diff --git a/src/api/apiFactory.ts b/src/api/apiFactory.ts index 67677d2e..66315e55 100644 --- a/src/api/apiFactory.ts +++ b/src/api/apiFactory.ts @@ -14,6 +14,7 @@ import { Catalog, Charity, Commerce, + Feedback, Identity, Media, Message, @@ -71,7 +72,8 @@ export default class ApiFactory extends Api { media: this.createRestfulApi(Media), translation: this.createRestfulApi(Translation), taxonomy: this.createRestfulApi(Taxonomy), - message: this.createRestfulApi(Message) + message: this.createRestfulApi(Message), + feedback: this.createRestfulApi(Feedback) }; } diff --git a/src/api/restful/commerce/feedback/index.ts b/src/api/restful/commerce/feedback/index.ts new file mode 100644 index 00000000..cb34e6c0 --- /dev/null +++ b/src/api/restful/commerce/feedback/index.ts @@ -0,0 +1,140 @@ +import { operations } from '../../../../types/restful/specs/commerce_feedback_v1_beta_oas3.js'; +import { LeaveFeedbackRequest, RespondToFeedbackRequest } from '../../../../types/restfulTypes.js'; +import Restful, { OpenApi } from '../../index.js'; + +/** + * The eBay Feedback API includes resources for retrieving items awaiting feedback, retrieving and + * submitting feedback entries, providing feedback rating summaries, and responding to feedback. + * These methods allow users to manage feedback across buying and selling activities. + * + * https://api.ebay.com/oauth/api_scope/commerce.feedback + */ +export default class Feedback extends Restful implements OpenApi { + + static id = 'Feedback'; + + get basePath(): string { + return '/commerce/feedback/v1'; + } + + /** + * This method retrieves the order line items that are awaiting feedback from the user. + * + * @param filter This query parameter limits the response using one or more comma-separated filters. + * @param limit The maximum number of entries to return on each page of the paginated response. + * @param offset The number of entries to skip in the result set before returning the first entry. + * @param sort This query parameter configures the order of the returned items. + */ + public getItemsAwaitingFeedback({ + filter, + limit, + offset, + sort + }: { + filter?: string, + limit?: number, + offset?: number, + sort?: string, + } = {}) { + return this.get('/awaiting_feedback', { + params: { + filter, + limit, + offset, + sort + } + }); + } + + /** + * This method retrieves feedback for the specified user ID and feedback type (received or left). + * + * @param userId The eBay username of the user for which feedback is being retrieved. + * @param feedbackType The type of feedback records to return (e.g. FEEDBACK_RECEIVED or FEEDBACK_LEFT). + * @param feedbackId Returns only the specific feedback record identified by this feedback ID. + * @param filter Limits the response using one or more comma-separated filters (e.g. commentType). + * @param limit The maximum number of entries to return on each page of the paginated response. + * @param listingId Limits feedback entries to those associated with the specified listing. + * @param offset The number of entries to skip in the result set before returning the first entry. + * @param orderLineItemId Retrieves feedback entries related to the specified order line item ID. + * @param sort Configures the order of the returned items. + * @param transactionId Limits feedback entries to those associated with the specified transaction ID. + */ + public getFeedback({ + userId, + feedbackType, + feedbackId, + filter, + limit, + listingId, + offset, + orderLineItemId, + sort, + transactionId + }: { + userId: string, + feedbackType: string, + feedbackId?: string, + filter?: string, + limit?: number, + listingId?: string, + offset?: number, + orderLineItemId?: string, + sort?: string, + transactionId?: string, + }) { + return this.get('/feedback', { + params: { + user_id: userId, + feedback_type: feedbackType, + feedback_id: feedbackId, + filter, + limit, + listing_id: listingId, + offset, + order_line_item_id: orderLineItemId, + sort, + transaction_id: transactionId + } + }); + } + + /** + * This method submits a feedback entry for an order line item. + * + * @param body LeaveFeedbackRequest + */ + public leaveFeedback(body: LeaveFeedbackRequest) { + return this.post('/feedback', body); + } + + /** + * This method retrieves a summary of the feedback ratings for the specified user. + * + * @param userId The eBay username of the user for which the rating summary is being retrieved. + * @param filter Limits the response based on the specified filter values (e.g. ratingType). + */ + public getFeedbackRatingSummary({ + userId, + filter + }: { + userId: string, + filter: string, + }) { + return this.get('/feedback_rating_summary', { + params: { + user_id: userId, + filter + } + }); + } + + /** + * This method submits a response (a public reply or a follow-up) to a feedback entry. + * + * @param body RespondToFeedbackRequest + */ + public respondToFeedback(body: RespondToFeedbackRequest) { + return this.post('/respond_to_feedback', body); + } +} diff --git a/src/api/restful/commerce/index.ts b/src/api/restful/commerce/index.ts index ec251776..72513a34 100644 --- a/src/api/restful/commerce/index.ts +++ b/src/api/restful/commerce/index.ts @@ -6,6 +6,7 @@ import Notification from './notification/index.js'; import Taxonomy from './taxonomy/index.js'; import Translation from './translation/index.js'; import Message from './message/index.js'; +import Feedback from './feedback/index.js'; export type Commerce = { catalog: Catalog; @@ -16,6 +17,7 @@ export type Commerce = { translation: Translation; media: Media; message: Message; + feedback: Feedback; }; export { @@ -26,5 +28,6 @@ export { Taxonomy, Translation, Media, - Message + Message, + Feedback }; diff --git a/src/types/restful/specs/commerce_feedback_v1_beta_oas3.ts b/src/types/restful/specs/commerce_feedback_v1_beta_oas3.ts new file mode 100644 index 00000000..6e3ce6ac --- /dev/null +++ b/src/types/restful/specs/commerce_feedback_v1_beta_oas3.ts @@ -0,0 +1,754 @@ +/** + * This file was auto-generated by openapi-typescript. + * Do not make direct changes to the file. + */ + +export interface paths { + "/awaiting_feedback": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description This method retrieves line items awaiting feedback from the user's order partner. You can refine the results using optional filter query parameters, such as item ID, user name, or user role in the transaction. Sorting and pagination features help organize and navigate returned items efficiently.

For sellers, only sold items that have not yet received feedback are included. For buyers, only purchased items for which feedback is still pending are included. If the user is both a buyer and a seller, this API returns items awaiting feedback for transactions where the user acted as either. Applying filters can limit results to either buyer-only or seller-only transactions.

The response provides an overview of feedback yet to be left for completed transactions (as filtered), with counts for both the buyer and seller roles. It includes an array of line items, each containing the listing ID, title, price (with currency and value). For each line item, the response offers feedback templates specifying which ratings are available.

Note: Detailed seller ratings are for sellers only, and are created from buyer feedback.

*/ + get: operations["getItemsAwaitingFeedback"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/feedback": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description This method enables users to retrieve feedback for any specified user ID and feedback type (sent or received). You can refine the results using optional query parameters such as its feedback ID, listing ID, or order line item ID, or applying one or more filters.

Applying filters can narrow results using criteria such as comment type, photos, or topics identified through AI-based analysis. When filtering for feedback with photos (filterImage:true), only entries with images (entries that include image URLs) are returned. Additionally, feedback can be refined for the number of days to look back, the role of the user providing the feedback, and whether to include automated feedback entries left by eBay.

Sorting and pagination features help organize and navigate returned items efficiently.

Returned data includes feedback details (such as comment text and type), feedback ratings (covering criteria like overall experience, and for sellers item description, shipping time, and communication), role and attributes of the feedback giver, line item and transaction summaries, images, and any available topics. See filter for additional information. Privacy is safeguarded by restricting the amount of detail visible to users, depending on their context. When accessing another user's feedback without logging in, buyer names are masked and seller names are shown. Logged-in users viewing their own feedback see all names, while those viewing other users' feedback will encounter some masking.

*/ + get: operations["getFeedback"]; + put?: never; + /** @description This method creates and submits feedback to the user's order partner for a line item in the order. For each order, the order partner is the other participant in the transaction, either the buyer or seller, depending on the eBay user associated with the user token. This method allows users to provide detailed information about the transaction, including the feedback rating, comments, and seller delivery. You can also add images to your feedback.

Note: A seller can only provide a comment for a buyer, but a buyer can provide a comment plus provides ratings on a number of metrics for a seller.

Note: The feedback must adhere to community guidelines and be relevant to the transaction.

When leaving feedback, keep the following in mind:

For additional information on leaving feedback, see the following:

A successful call to this method returns a feedback ID, which is a unique identifier for the newly created feedback and allows for reference and tracking.

*/ + post: operations["leaveFeedback"]; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/feedback_rating_summary": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + /** @description This method provides a detailed overview of feedback ratings associated with a user in the eBay marketplace. Specify a user ID and apply filters to retrieve summarized feedback data categorized by rating types and user roles. These returned metrics are aggregated, which offers insight into user experiences and performance.

Tip: You can use this method to help sellers and buyers understand their marketplace reputation and identify areas for improvement.

Returned data provides a summary of feedback ratings for a user by rating type (such as overall experience, communication, or delivery timeliness) for both buyer and seller roles. Each type of rating includes aggregated metrics like averages, counts, unique feedback givers, and the percentage of positive ratings (excluding neutrals). The response also details the distribution of specific rating values, their frequency, and time period (with period units like days or months) over which these metrics were calculated.

*/ + get: operations["getFeedbackRatingSummary"]; + put?: never; + post?: never; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; + "/respond_to_feedback": { + parameters: { + query?: never; + header?: never; + path?: never; + cookie?: never; + }; + get?: never; + put?: never; + /** @description This method allows users to respond to feedback provided by the order partner for a specific line item in an order. For each order, the order partner is the other participant in the transaction, either the buyer or seller, depending on the eBay user associated with the user token. This method allows the user to provide additional context or address the order partner's feedback.

Note: The feedback response must adhere to community guidelines and be relevant to the transaction.

You can only use this method if feedback has been provided by the order partner and you have not yet responded to it.

When responding to feedback, your feedback score is not affected when you respond to feedback.

For additional information on leaving feedback, see the following:

A successful call returns an HTTP status of 200 Success.

*/ + post: operations["respondToFeedback"]; + delete?: never; + options?: never; + head?: never; + patch?: never; + trace?: never; + }; +} +export type webhooks = Record; +export interface components { + schemas: { + /** @description This type contains the details for each line item awaiting feedback. */ + AwaitingFeedback: { + /** @description This is the unique identifier for the listing associated with the line item. It is used to reference the specific listing for which feedback is being awaited. */ + listingId?: string; + /** @description This container shows the sales price of the listing. */ + listingPrice?: components["schemas"]["ListingPrice"]; + /** @description The title of the listing. */ + listingTitle?: string; + /** @description The unique identifier for the eBay order line item associated with the listing. It is used to pinpoint the exact line item for which feedback is being awaited. */ + orderLineItemId?: string; + /** @description This array contains a list of available values for use in a particular rating, and whether the value is enabled. This is dependent on what seller ratings the buyer's order partner qualifies.

Note: Rating templates should only be returned to the user in their role as a buyer; only sellers have Detailed Seller Ratings (DSRs).

Use the metadata returned here when leaving DSR ratings through the leaveFeedback method. The key field in this container is the ratingKey field. See FeedbackRatingTypeEnum for its values. The other metadata returned in this container apply to each ratingKey value that is returned.

*/ + ratingTemplates?: components["schemas"]["FeedbackRatingTemplateType"][]; + /** @description The unique identifier of the sales transaction. */ + transactionId?: string; + }; + /** @description This type defines the fields for the getItemsAwaitingFeedback response. */ + AwaitingFeedbackResponse: { + /** @description This container returns the number of line items awaiting feedback. The asSeller and asBuyer fields return the total count of items awaiting feedback as seller and buyer and are not affected by the userRole filter. */ + itemsAwaitingFeedbackCount?: components["schemas"]["ItemsAwaitingFeedbackCount"]; + /** @description This array contains the details for each line item awaiting feedback. An empty array is returned if no line items are awaiting feedback or that match the filter criteria. */ + lineItems?: components["schemas"]["AwaitingFeedback"][]; + /** @description This container provides pagination information for the returned line items awaiting feedback (as filtered). */ + pagination?: components["schemas"]["Pagination"]; + }; + /** @description This type provides the details of the feedback comment left by the user. */ + Comment: { + /** @description This container indicates the timing of a feedback comment based on when it was left. It is only returned if a comment was provided. Possible values are 30 days, 90 days, 180 days, 365 days, or 5 years:
  • Less than 30 days: 30 DAY
  • Over 30 but less than 90 days: 90 DAY
  • Over 90 but less than 180 days: 180 DAY
  • Over 180 but less than 365 days: 365 DAY
  • More than 365 days: 5 YEAR
*/ + commentPeriod?: components["schemas"]["CommentCommentPeriod"]; + /** @description The text of the feedback comment, follow-up, or reply. HTML formatting and personal information (for example, phone numbers) are not allowed. This field is returned if a comment was provided for the feedback entry. If the comment was removed due to eBay policy, this field will contain '--' and the commentTextRemovedPerPolicy field will return true. */ + commentText?: string; + /** @description If true, this boolean indicates the feedback follow-up or reply comment text was removed per eBay policy. This field is only returned when a followupComment container is returned. */ + commentTextRemovedPerPolicy?: boolean; + /** @description This enumerated value indicates the state of the feedback (for example, ENTERED). This can be the state of the feedback comment, the follow-up comment, or the reply comment. For implementation help, refer to eBay API documentation */ + state?: string; + }; + /** @description This type provides fields that descrbes timing associated with the comment. */ + CommentCommentPeriod: { + /** @description Unit of time for the value. Supported values: DAY, or YEAR. */ + unit?: string; + /** + * Format: int32 + * @description Value of the time period expressed in the period contained in the unit. Supported values: 30, 60, or 365.

See the commentPeriod container for more information.

+ */ + value?: number; + }; + /** @description This type defines the fields that can be returned in an error. */ + Error: { + /** @description Identifies the type of erro. */ + category?: string; + /** @description Name for the primary system where the error occurred. This is relevant for application errors. */ + domain?: string; + /** + * Format: int32 + * @description A unique number to identify the error. + */ + errorId?: number; + /** @description An array of request elements most closely associated to the error. */ + inputRefIds?: string[]; + /** @description A more detailed explanation of the error. */ + longMessage?: string; + /** @description Information on how to correct the problem, in the end user's terms and language where applicable. */ + message?: string; + /** @description An array of request elements most closely associated to the error. */ + outputRefIds?: string[]; + /** @description An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned. */ + parameters?: components["schemas"]["ErrorParameter"][]; + /** @description Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc. */ + subdomain?: string; + }; + ErrorParameter: { + /** @description The object of the error. */ + name?: string; + /** @description The value of the object. */ + value?: string; + }; + /** @description This type provides attributes for returned feedback entries. */ + FeedbackDetail: { + /** @description If the returned value is true, feedback was generated and added automatically by eBay. If a seller has a feedback score 10 or less, eBay automatically leaves feedback. The buyer can choose to override the eBay feedback and leave feedback normally.

Note: Detailed Seller Ratings (DSRs) are not provided by ebay, only a predefined comment and a positive rating.

*/ + automatedFeedback?: boolean; + /** @description This enumerated value indicates the type of feedback: POSITIVE, NEUTRAL, NEGATIVE.

Note: Sellers can only leave positive feedback for buyers.

For implementation help, refer to eBay API documentation */ + commentType?: string; + /** @description This boolean indicates whether the feedback is eligible for revision. If returned as true, it means the feedback can be modified. Feedback that is older than 30 days or has already been revised once cannot be erased or further revised. */ + eligibleForRevision?: boolean; + /** @description This container provides the feedback comment left by a user when submitting feedback for a seller or buyer. */ + feedbackComment?: components["schemas"]["Comment"]; + /** @description The timestamp when the feedback was submitted. */ + feedbackEnteredDate?: string; + /** @description This container represents the duration since feedback was entered, expressed as a numeric value and a unit of time in days. */ + feedbackEnteredPeriod?: components["schemas"]["FeedbackEnteredPeriod"]; + /** @description The unique identifier of the feedback entry. */ + feedbackId?: string; + /** @description This array contains a list of ratings attached to feedback.

Note: This array only applies to buyers feedback for sellers (sellers can only give positive feedback to buyers).

*/ + feedbackRatings?: components["schemas"]["FeedbackRating"][]; + /** + * Format: int32 + * @description The feedback receiver's feedback score after receiving this specific feedback. + */ + feedbackScore?: number; + /** @description This enumerated value indicates the current state of the feedback entry (for example, ENTERED). For implementation help, refer to eBay API documentation */ + feedbackState?: string; + /** @description This container provides the details of any follow-up comment left.

Note: A buyer leaves followup comments, and a seller leaves reply comments.

*/ + followupComment?: components["schemas"]["Comment"]; + /** @description If returned as true, this boolean indicates that the feedback entry has one or more images attached. If false, there are no images attached. */ + hasImages?: boolean; + /** @description This array contains the list of attached images. */ + images?: components["schemas"]["Image"][]; + /** @description This container provides a summary of the line item associated with the feedback entry.

Note: Certain fields within this container are returned only when the request uses the Authorization code grant flow (user access token) and the user_id matches the authenticated user. These fields are not returned when accessing a different user_id or when using the Client credentials grant flow (application access token). See OAuth scope for for details on the flows and required permissions.

*/ + orderLineItemSummary?: components["schemas"]["OrderLineItemSummary"]; + /** @description This container details the attributes of the user who provided the feedback. */ + providerUserDetail?: components["schemas"]["ProviderUserDetail"]; + /** @description If returned as true, this boolean indicates the feedback reply was given by the seller before the follow-up comment was given buy the buyer. */ + repliedBeforeFollowup?: boolean; + /** @description This container provides the details of any reply to the feedback.

Note: A buyer leaves followup comments, and a seller leaves reply comments.

*/ + replyComment?: components["schemas"]["Comment"]; + /** @description This array provides descriptions of AI-generated insights related to a feedback entry for the specified filter topic. The feedback provided is considered relevant to the requested topic. For example, when using the request parameter filter of topics:product-satisfaction, the returned array might be: 

{
  "coarseTopic" : "product-satisfaction",
  "highlightedTexts" : [
    "This machine is amazing",
    "Very happy with this purchase"
    ],
  "sentiment" : "Positive"
}

If no topics exist for that feedback, an empty array is returned.

*/ + topics?: components["schemas"]["Topic"][]; + }; + /** @description This type specifies the amount of time elapsed associated with a feedback entry. */ + FeedbackEnteredPeriod: { + /** @description The unit for the feedback entry period's value. Supported value: DAY. */ + unit?: string; + /** + * Format: int32 + * @description The value for the feedback entry period, specified in units of unit. Supported values: 7, 30, 90, 180, or 365. + */ + value?: number; + }; + /** @description This type provides fields for the array of metrics associated with feedback aggregation. */ + FeedbackMetrics: { + /** @description This enumerated value specifies the type of feedback aggregation. For example, AVG would indicate the feedback returned represents the average value of the feedback. See metricValue for the value of the returned feedback. For implementation help, refer to eBay API documentation */ + metricName?: string; + /** @description The decimal value of the specified metric. For example, 55.8 would represent a value associated with the metricName (see metricName for interpretation and units). */ + metricValue?: number; + }; + /** @description This type provides for fields in ratings attached to feedback. */ + FeedbackRating: { + /** @description This enumerated value indicates the type of rating (for example, OVERALL_EXPERIENCE, DSR_ITEM_AS_DESCRIBED). For implementation help, refer to eBay API documentation */ + ratingType?: string; + /** @description The value assigned to the rating, specified as a string representing a number from 1 to 5, with 1 representing the lowest rating and 5 representing the highest rating. */ + value?: string; + }; + /** @description This type provides fields for available values for use in a particular rating, and whether the value is enabled. */ + FeedbackRatingAcceptableValue: { + /** @description If true, this boolean indicates that this value is enabled and selectable. */ + enabled?: boolean; + /** @description The value that can be selected for feedback. For most ratingType values, this is 1 through 5, with 1 representing the lowest rating and 5 representing the highest rating. For ratingType of OVERALL_EXPERIENCE, this can be POSITIVE, NEGATIVE, and NEUTRAL. These are the same values as used with the leaveFeedback methods. */ + value?: string; + /** @description This field provides information about the corresponding value. */ + valueLabel?: string; + }; + /** @description This type provides fields for an array containing a summary of feedback ratings. Each element provides detailed metrics and distributions for specific rating types. */ + FeedbackRatingSummary: { + /** @description An array that includes metrics and distributions for each rating type. */ + ratingSummaryByRatingType?: components["schemas"]["RatingSummaryByRatingType"][]; + /** @description This enumerated value indicates the type of rating being summarized. For example, OVERALL_EXPERIENCE indicates the rating applies to the overall transaction experience. For implementation help, refer to eBay API documentation */ + ratingType?: string; + }; + /** @description This type defines fields for user feedback collection, including acceptable values, a default preselection value, and an early feedback message. It also provides fields to enable the template, and limits and options for freetext character, multi-value rating, and other similar features. */ + FeedbackRatingTemplateType: { + /** @description This array contains a list of available values for use in a particular rating, and whether the value is enabled. Provided if ratingValueType is RANGE or PREDEFINED.

The following is an example of a predefined list:

[
  {
    "value": "POSITIVE",
    "valueLabel": "Positive",
    "enabled": true
  },
  {
    "value": "NEUTRAL",
    "valueLabel": "Neutral",
    "enabled": true
  },
  {
    "value": "NEGATIVE",
    "valueLabel": "Negative",
    "enabled": true
  }
]
For other examples, see the Using rating templates. */ + acceptableValues?: components["schemas"]["FeedbackRatingAcceptableValue"][]; + /** @description The default value preselected for the rating, if set. */ + defaultValue?: string; + /** @description For eligible sellers, a message may be shown requiring a wait period before you can leave neutral or negative feedback. */ + earlyFeedbackMessage?: string; + /** @description If returned as true, this boolean indicates that the corresponding feedback rating template is enabled for the user to provide feedback for this line item. This value will generally be true when the user role is a buyer, but false when the user role is a seller because buyers do not have Detailed Seller Ratings (DSRs). */ + enabled?: boolean; + /** + * Format: int32 + * @description The maximum number of characters allowed to be used for a rating that uses free text. It is only applicable for a rating whose ratingValueType is FREETEXT.

Maximum: 500

+ */ + maximumCharactersAllowed?: number; + /** @description If returned as true, multiple values can be specified for the rating. */ + multiValueRating?: boolean; + /** @description This enumerated value indicates the type of rating that is tracked for the seller. All of the metadata returned under each node for the ratingTemplates array will apply to this rating type. For example, the value OVERALL_EXPERIENCE indicates the rating is for the overall transaction experience. For implementation help, refer to eBay API documentation */ + ratingKey?: string; + /** @description This field provides more details about and/or provides guidance on the corresponding rating type. For example, the rating label of Rate this transaction describes the feedback for the user to enter for an OVERALL_EXPERIENCE ratingKey. */ + ratingLabel?: string; + /** @description This enumerated value indicates the type of data used to provide the specific feedback rating.

If set to PREDEFINED or RANGE, is returned here, more information on the supported values will be returned under the acceptableValues array. If FREETEXT is returned here, the maximum number of characters supported can be seen in the maximumCharactersAllowed field.

For implementation help, refer to eBay API documentation */ + ratingValueType?: string; + /** @description If returned as true, this rating type is required when leaving feedback. */ + required?: boolean; + }; + /** @description This type provides field for an array listing the distribution values of the feedback ratings. */ + FeedbackRatingValueDistribution: { + /** + * Format: int32 + * @description An integer representing the number of occurrences for a specific feedback rating value. For example, for the POSITIVE value, a 3 returned as the count represents three positive ratings were returned. + */ + count?: number; + /** @description A string indicating the specific feedback rating value. Supported values include: POSITIVE, NEUTRAL, NEGATIVE, 1, 2, 3, 4, and 5. */ + value?: string; + }; + /** @description This type defines the fields for the getFeedbackRatingSummary response. */ + GetFeedbackRatingSummaryResponse: { + /** @description An array containing a summary of feedback ratings. Each element provides detailed metrics and distributions for specific rating types. */ + feedbackRatingSummary?: components["schemas"]["FeedbackRatingSummary"][]; + }; + /** @description This type defines the fields for the getFeedback response. */ + GetFeedbackResponse: { + /** @description This array contains a list of feedback entries that meet the specified criteria. */ + feedbackEntries?: components["schemas"]["FeedbackDetail"][]; + /** @description This container provides pagination information for the returned feedback response (as filtered). */ + pagination?: components["schemas"]["Pagination"]; + }; + /** @description This type provides a field for image URLs. */ + Image: { + /** @description This field provides the URL of an attached image and is included in the response whenever an image is attached. */ + url?: string; + }; + /** @description This type returns the number of line items awaiting feedback. */ + ItemsAwaitingFeedbackCount: { + /** + * Format: int32 + * @description The number of line items for which feedback is pending from the user in the buyer role. + */ + asBuyer?: number; + /** + * Format: int32 + * @description The number of line items for which feedback is pending from the user in the seller role. + */ + asSeller?: number; + }; + /** @description This type provides fields available to leave feedback in the leaveFeedback request. */ + LeaveFeedbackRequest: { + /** @description Use this field to provide the feedback left by the user, describing their experience with the line item of the transaction. No HTML formatting or personal information (such as phone numbers) is permitted.

Maximum length: 500 characters

*/ + commentText?: string; + /** @description Set this enumerated value to indicate the overall rating of the transaction: POSITIVE, NEUTRAL, or NEGATIVE.

Note: Sellers can only provide positive feedback.

For implementation help, refer to eBay API documentation */ + commentType?: string; + /** @description Use this array to optionally list up to 5 images attached to the feedback. */ + images?: components["schemas"]["Image"][]; + /** @description Use this field to provide the listing ID related to the transaction. */ + listingId?: string; + /** @description Use this field to provide the unique identifier of the line item for this feedback. */ + orderLineItemId?: string; + /** @description Use this array to list ratings for specific aspects of the seller's performance. */ + sellerRatings?: components["schemas"]["SellerRating"][]; + /** @description Use this field to provide the unique identifier of the transaction for this feedback. */ + transactionId?: string; + }; + /** @description This type defines the fields for the leaveFeedback response for feedback that has been left. */ + LeaveFeedbackResponse: { + /** @description The unique ID assigned to the submitted feedback. */ + feedbackId?: string; + }; + /** @description This type provides details about the price of the listing awaiting feedback. */ + ListingPrice: { + /** @description This field provides the three-letter ISO 4217 code that represents the currency of the amount in the value field. Both the value and currency fields are always returned when expressing prices. */ + currency?: string; + /** @description This field contains the numerical value of the listing price in the currency specified in the currency field. Both the value and currency fields are always returned when expressing prices. */ + value?: number; + }; + /** @description This type describes line item attributes. */ + OrderLineItemAttribute: { + /** @description This enumerated value indicates an attribute of the line item. The value field indicates if the attribute applies. For implementation help, refer to eBay API documentation */ + name?: string; + /** @description If returned as true, the line item attribute name applies; if returned as false, the attribute does not apply. */ + value?: string; + }; + /** @description This type provides fields for a summary of the line item related to feedback. */ + OrderLineItemSummary: { + /** @description This field provides the unique identifier for the listing associated with the feedback entry. Conditionally returned based on the authorization flow and user context. See orderLineItemSummary for details on when this field is included. */ + listingId?: string; + /** @description This container provides the sale price of the listing. Conditionally returned based on the authorization flow and user context. See orderLineItemSummary for details on when this field is included. */ + listingPrice?: components["schemas"]["ListingPrice"]; + /** @description This field contains the title of the listing. Conditionally returned based on the authorization flow and user context. See orderLineItemSummary for details on when this field is included. */ + listingTitle?: string; + /** @description This array describes order line attributes including names and values of a transaction. */ + orderLineItemAttributes?: components["schemas"]["OrderLineItemAttribute"][]; + /** @description The unique identifier of the line item for this feedback. Conditionally returned based on the authorization flow and user context. See orderLineItemSummary for details on when this field is included. */ + orderLineItemId?: string; + /** @description This container indicates if the time since the item was bought on ebay is less than, more than, or equal to 90 days */ + transactionPeriod?: components["schemas"]["TransactionPeriod"]; + }; + /** @description This type provides pagination information for the returned line items. */ + Pagination: { + /** + * Format: int32 + * @description This value indicates the number of feedback entries on the current response page. + */ + count?: number; + /** + * Format: int32 + * @description The value of the limit parameter submitted in the request. This is the maximum number of line items, as filtered, awaiting feedback to return per page from the result set. This field indicates the number of line items returned per page of data.

Note: If this is the last or only page of the result set, the page may contain fewer line items than the limit value.

If a limit parameter was not included in the request, this value will default to 25, returning up to 25 line items on each page.

Default: 25

+ */ + limit?: number; + /** @description The relative URI for the next page of results starting with the resource name. This URI is returned if there is an additional page of results in the result set. */ + next?: string; + /** + * Format: int32 + * @description The value of the offset parameter submitted in the request. This field indicates how many results were skipped in the response. If an offset parameter was not included in the request, this value will default to 0, returning the first page of results.

Default: 0

+ */ + offset?: number; + /** @description The relative URI for the previous page of results starting with the resource name. This URI is returned if there is a previous page of results in the result set.

*/ + prev?: string; + /** + * Format: int32 + * @description The total number of line items available that match the filter criteria.

Note: If the total value exceeds the limit value, there are multiple pages of results.

+ */ + total?: number; + }; + /** @description This type provides fields for the time period on which the feedback summary is calculated. */ + Period: { + /** @description The unit of the period's value. Supported value: DAY. */ + unit?: string; + /** + * Format: int32 + * @description The value for the feedback period, specified in units of unit. Supported value: 90. + */ + value?: number; + }; + /** @description This type provides the details of the user who provided the feedback of a getFeedback response. */ + ProviderUserDetail: { + /** + * Format: int32 + * @description This integer indicates the feedback score of the feedback provider at the time of providing this specific feedback. + */ + feedbackScore?: number; + /** @description This enumerated value provides the visual star representation of the feedback score (for example, YELLOW_STAR). For implementation help, refer to eBay API documentation */ + feedbackStar?: string; + /** @description This enumerated value indicates the user's role in the transaction (BUYER or SELLER). For implementation help, refer to eBay API documentation */ + role?: string; + /** @description This array lists additional attributes that relate to the user (such as verification status). */ + userAttributes?: components["schemas"]["ProviderUserDetailUserAttributes"][]; + /** @description This field indicates the unique identifier of the user who gave the feedback.

Note: Select developers will not receive username data for U.S. users through this field. Instead, an immutable user ID will be returned in its place. For more information, please refer to Data Handling Compliance. */ + userId?: string; + }; + /** @description This type defines the attributes of the user who provided the feedback of a getFeedback response. */ + ProviderUserDetailUserAttributes: { + /** @description This enumerated value indicates an attribute of the user (for example, USER_VERIFIED). The value field indicates if the attribute applies. For implementation help, refer to eBay API documentation */ + name?: string; + /** @description If returned as true, the user attribute name applies; if returned as false, the attribute does not apply. */ + value?: string; + }; + /** @description This type provides fields for an array that includes metrics and distributions for each rating type. */ + RatingSummaryByRatingType: { + /** @description An array of metrics associated with feedback aggregation. */ + feedbackMetrics?: components["schemas"]["FeedbackMetrics"][]; + /** @description An array listing the distribution values of the feedback ratings. */ + feedbackRatingValueDistribution?: components["schemas"]["FeedbackRatingValueDistribution"][]; + /** @description The time period on which the feedback summary is calculated. */ + period?: components["schemas"]["Period"]; + /** @description This enumerated value indicates the user's role in the feedback (BUYER or SELLER). For implementation help, refer to eBay API documentation */ + userRoleType?: string; + }; + /** @description The type that defines the fields for the respondToFeedback request. */ + RespondToFeedbackRequest: { + /** @description Use this field to provide the unique identifier for the feedback being responded to, used to specify the feedback entry associated with the feedback response. This value can be returned using the getFeedback method (feedbackId field). */ + feedbackId?: string; + /** @description Use this field to provide the identifier of the user who provided the original feedback. This value can be returned using the getFeedback method (userId field).

Note: Both usernames and public user IDs will be accepted in this field. For more information, please refer to Data Handling Compliance. */ + recipientUserId?: string; + /** @description Use this field to provide the text content of the response. This field is used to provide additional context or address the feedback given by the order partner. No HTML formatting or personal information (such as phone numbers) is permitted.

Maximum length: 500 characters. */ + responseText?: string; + /** @description Set this enumerated value to describe the type of response being submitted (for example, a REPLY or a FOLLOW_UP). For implementation help, refer to eBay API documentation */ + responseType?: string; + }; + /** @description This type provides fields for specific aspects of the seller's performance. */ + SellerRating: { + /** @description The enumerated value of the category being rated, such as delivery timeliness (ON_TIME_DELIVERY). For implementation help, refer to eBay API documentation */ + key?: string; + /** @description The value assigned for the selected category. Use a value of 1 through 5, with the 1 being the lowest rating and 5 being the highest. */ + value?: string; + }; + /** @description This type provides subject-based fields derived from feedback. */ + Topic: { + /** @description The main topic (or category) detected in the comment. See the available topics in filter. */ + coarseTopic?: string; + /** @description

Note: Fine topics are not currently supported.

A more specific detail or subtopic related to the coarse topic. */ + fineTopic?: string; + /** @description This array lists any text snippets, phrases, or examples, from the feedback that supports the detected topic. */ + highlightedTexts?: string[]; + /** @description This field indicates a classification of the feedback, whether the feedback is Positive, Negative, or Neutral. */ + sentiment?: string; + }; + /** @description This type specifies the amount of time elapsed and the threshold associated with a transaction. */ + TransactionPeriod: { + /** @description This container indicates if the time since the item was bought on ebay is less than, more than, or equal to 90 days. */ + period?: components["schemas"]["Period"]; + /** @description This enumerated value indicates whether a transaction period exceeds, falls short, or matches the threshold. You can use this field to trigger specific logic or actions based on whether a transaction period exceeds, falls short, or matches the threshold. For implementation help, refer to eBay API documentation */ + thresholdType?: string; + }; + }; + responses: never; + parameters: never; + requestBodies: never; + headers: never; + pathItems: never; +} +export type $defs = Record; +export interface operations { + getItemsAwaitingFeedback: { + parameters: { + query?: { + /** @description Use this parameter to limit the response based on the specified filter parameters. Supported filter parameters include:

  • listingId: Filter results by the specific listing ID
  • receiverName: Filter results by the user's order partner name involved in the transaction
  • userRole: Use this filter to only retrieve feedback due from the user in role as a seller or a buyer. If this filter is not used, all feedback due in both user roles is retrieved (BUYER or SELLER)

Send the filter as a query parameter in a comma-separated name:value list. For example:
filter=listingId:123,receiverName:user,userRole:BUYER

*/ + filter?: string; + /** @description This parameter sets the maximum number of line items to return per page of data.

Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, with offset set to 20 and limit set to 10, the call retrieves entries 21 through 30 from the result set.

Although this field is optional, if omitted the default value of 25 is used.

Default: 25

Minimum: 25

Maximum: 200

*/ + limit?: string; + /** @description Use this parameter to specify the number of items to skip in the result set. This is used with the limit field to control the pagination of the output. For example:
  • If offset is 0 and limit is 10, the method will retrieve items 1-10 from the list of line items returned
  • If offset is 10 and limit is 10, the method will retrieve items 11-20 from the list of line items returned.

Note: This feature employs a zero-based list, where the first line item in the list has an offset of 0.

If this parameter is not set, its value defaults to 0 which returns the first page of records.

Default: 0

*/ + offset?: string; + /** @description Use this parameter to configure the order of the returned listings. The time is based on when the buyer paid for the line item. Acceptable values:
  • END_TIME_ASC: Sorts listings by end time from oldest to newest
  • END_TIME_DESC: Sorts listings by end time from newest to oldest (default)

If this parameter is omitted, its value defaults to END_TIME_DESC.

Default: END_TIME_DESC

*/ + sort?: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Success */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["AwaitingFeedbackResponse"]; + }; + }; + /** @description Bad Request */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Not Authorized */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Internal Server Error */ + 500: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + getFeedback: { + parameters: { + query: { + /** @description Use this field to only return a specific feedback record by its feedback ID.

Note: If this query parameter is used, no other filters will be applicable.

*/ + feedback_id?: string; + /** @description Use this field to specify the type of feedback records to return. Acceptable values:
  • FEEDBACK_RECEIVED: Retrieve feedback received by the specified user.
  • FEEDBACK_SENT: Retrieve feedback sent by the specified user.

If not specified, both feedback received and feedback left for the user shall be retrieved.

Note: When using FEEDBACK_SENT, it is recommended to also filter feedback_id to target results accurately.

*/ + feedback_type: string; + /** @description Use this parameter to limit the response based on the specified filter parameters as follows:
  • commentType: Return only feedback with the set type of comments. Comment types available: POSITIVE, NEUTRAL, or NEGATIVE

    Note: Sellers can only provide positive feedback.

  • filterImage: Return feedback dependent on if images are included. Filter values available:
    • true: Return only feedback with images
    • false: Return feedback with or without images
  • topics: Use AI to generate items returned that are associated to the set topic. For example, if you set topics:shipping, only feedback comments about shipping are returned. Topics available: shipping, service, packaging, description, seller-satisfaction, overall-satisfaction, refund, inventory, customer loyalty, seller-other, quality, price, condition, fit, appearance, dimensions, usage, product-satisfaction, product-other, extras

    See Retrieve AI-filtered feedback for an example.
  • period: Filter results by the number of days to look back for feedback. If not set, lifetime results are returned. Supported values available: 7, 30, 90, 180, or 365
  • role: Filter results by the role of the user providing feedback. Roles available: BUYER or SELLER
  • showAutomatedFeedback: Filter results to include automated feedback left by eBay entries. For sellers with less than a 10 feedback score, an automated feedback message on behalf of eBay is returned.
    • true: Return automated feedback including both user and eBay generated feedback
    • false: Do not return eBay's automatic feedback for seller in response (default)
Send the filter as a query parameter in a comma-separated name:value list. For example:

filter=commentType:POSITIVE,filterImage:true,topics:fit,period:30,role:SELLER,showAutomatedFeedback:true

*/ + filter?: string; + /** @description Use this parameter to set the maximum number of items to return per page of data.

Use this parameter in conjunction with the offset parameter to control the pagination of the output. For example, with offset set to 20 and limit set to 10, the call retrieves entries 21 through 30 from the result set.

Although this field is optional, if omitted the default value of 25 is used.

Default: 25

Minimum: 25

Maximum: 200

*/ + limit?: string; + /** @description Use this field to limit feedback entries to those associated with a specified listing. */ + listing_id?: string; + /** @description Use this field to specify the number of line items to skip in the result set. This is used with the limit field to control the pagination of the output. For example:
  • If offset is 0 and limit is 10, the method will retrieve items 1-10 from the list of line items returned
  • If offset is 10 and limit is 10, the method will retrieve items 11-20 from the list of line items returned.

Note: This feature employs a zero-based list, where the first line item in the list has an offset of 0.

If this parameter is not set, its value defaults to 0 which returns the first page of records.

Default: 0

*/ + offset?: string; + /** @description Use this field to retrieve specific feedback entries related to an order line item ID. A maximum of two entries may be retrieved: feedback left by the buyer and feedback left by the seller.

Note: If this query parameter is set, no other filters will be applicable.

*/ + order_line_item_id?: string; + /** @description Use this parameter to configure the order of the returned items. The time is based on when the buyer paid for the line item. Acceptable values:
  • RELEVANCE: Sorts items by relevance (default). This sort takes into account any available factors such as a comment score, comment type (positive, negative, neutral), how long ago the comment was left, or the length of the comment
  • TIME: Sorts items by end time from newest to oldest.

If this parameter is omitted, its value defaults to RELEVANCE.

Default: RELEVANCE

*/ + sort?: string; + /** @description Use this field to limit feedback entries to those associated with the specified transaction ID. */ + transaction_id?: string; + /** @description Use this field to specify the unique identifier user ID (eBay username of the user) of the account for which feedback is being retrieved.

Note: Both usernames and public user IDs will be accepted in this field. For more information, please refer to Data Handling Compliance. */ + user_id: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Success */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["GetFeedbackResponse"]; + }; + }; + /** @description Bad Request */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Not Authorized */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Internal Server Error */ + 500: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + leaveFeedback: { + parameters: { + query?: never; + header: { + /** @description This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. */ + "Content-Type": string; + }; + path?: never; + cookie?: never; + }; + /** @description Request body for leaving feedback. Required fields: commentText (the text of the feedback comment), commentType (acceptable values - [POSITIVE, NEUTRAL, NEGATIVE]), listingId (the listingId of the item the feedback is being left for), transactionId (the transactionId for the order), orderLineItemId (Search by order line item ID. order line item id is a concatenation of listing ID and transaction ID, joined by `-`. Ex `listing_id-transaction_id`), sellerRatings (array of ratings with keys - [ON_TIME_DELIVERY, ITEM_AS_DESCRIBED, COMMUNICATION, SHIPPING_CHARGES, SHIPPING_TIME]), images (array of images with url field, can add upto 5 images) */ + requestBody?: { + content: { + "application/json": components["schemas"]["LeaveFeedbackRequest"]; + }; + }; + responses: { + /** @description Success */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["LeaveFeedbackResponse"]; + }; + }; + /** @description Bad Request */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Not Authorized */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Conflict */ + 409: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Internal Server Error */ + 500: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + getFeedbackRatingSummary: { + parameters: { + query: { + /** @description Use this parameter to limit the response based on specified filter values:
  • ratingType: Specifies the type of rating being summarized and returned (Required). Available values: OVERALL_EXPERIENCE, OVERALL_EXPERIENCE_COMMENT, ON_TIME_DELIVERY, DSR_ITEM_AS_DESCRIBED, DSR_COMMUNICATION, DSR_SHIPPING_CHARGES, DSR_SHIPPING_TIME, ITEM_RATING
    See FeedbackRatingTypeEnum for descriptions of values.
  • excludeRepeatFeedback: Set to true to exclude repeat feedback.
  • lookbackPeriodInDays: Limit the response to a previous period of days. Available values: 7, 30, 90, 180, or 365

You can send the filter as a query parameter, either with the required ratingType only, or combining the filter values with a comma-separated name:value list. For example:

filter=ratingType:OVERALL_EXPERIENCE,excludeRepeatFeedback:true,period:365

*/ + filter: string; + /** @description Use this parameter to specify the unique identifier (the eBay username associated with the account) for the eBay user whose feedback summary is being retrieved. */ + user_id: string; + }; + header?: never; + path?: never; + cookie?: never; + }; + requestBody?: never; + responses: { + /** @description Success */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": components["schemas"]["GetFeedbackRatingSummaryResponse"]; + }; + }; + /** @description Bad Request */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Not Authorized */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Not Found */ + 404: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Internal Server Error */ + 500: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; + respondToFeedback: { + parameters: { + query?: never; + header: { + /** @description This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers. */ + "Content-Type": string; + }; + path?: never; + cookie?: never; + }; + /** @description This provides the request body for responding to feedback. */ + requestBody?: { + content: { + "application/json": components["schemas"]["RespondToFeedbackRequest"]; + }; + }; + responses: { + /** @description Success */ + 200: { + headers: { + [name: string]: unknown; + }; + content: { + "application/json": Record; + }; + }; + /** @description Bad Request */ + 400: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Not Authorized */ + 401: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Forbidden */ + 403: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Conflict */ + 409: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + /** @description Internal Server Error */ + 500: { + headers: { + [name: string]: unknown; + }; + content?: never; + }; + }; + }; +} diff --git a/src/types/restfulTypes.ts b/src/types/restfulTypes.ts index dcf859ca..4d7b9859 100644 --- a/src/types/restfulTypes.ts +++ b/src/types/restfulTypes.ts @@ -27,6 +27,7 @@ import {components as commerceMedia} from './restful/specs/commerce_media_v1_bet import {components as commerceNotification} from './restful/specs/commerce_notification_v1_oas3.js'; import {components as commerceTranslation} from './restful/specs/commerce_translation_v1_beta_oas3.js'; import {components as commerceMessage} from './restful/specs/commerce_message_v1_oas3.js'; +import {components as commerceFeedback} from './restful/specs/commerce_feedback_v1_beta_oas3.js'; import {components as sellAccountV1} from './restful/specs/sell_account_v1_oas3.js'; import {components as sellAccountV2} from './restful/specs/sell_account_v2_oas3.js'; @@ -446,6 +447,9 @@ export type UpdateConversationRequest = commerceMessage['schemas']['UpdateConver export type BulkUpdateConversationRequest = commerceMessage['schemas']['BulkUpdateConversationsRequest']; export type CommerceMessageSendMessageRequest = commerceMessage['schemas']['SendMessageRequest']; +export type LeaveFeedbackRequest = commerceFeedback['schemas']['LeaveFeedbackRequest']; +export type RespondToFeedbackRequest = commerceFeedback['schemas']['RespondToFeedbackRequest']; + export type AttributeNameValue = buyBrowse['schemas']['AttributeNameValue'] export type CompatibilityPayload = buyBrowse['schemas']['CompatibilityPayload'] export type AddCartItemInput = buyBrowse['schemas']['AddCartItemInput'] diff --git a/test/api/restful/commerce/index.ts b/test/api/restful/commerce/index.ts index e07be6a3..93d9005b 100644 --- a/test/api/restful/commerce/index.ts +++ b/test/api/restful/commerce/index.ts @@ -6,7 +6,8 @@ import { Message, Notification, Taxonomy, - Translation + Translation, + Feedback } from '../../../../src/api/restful/commerce/index.js'; import {readSpecs} from '../../jsonfile.js'; @@ -19,5 +20,6 @@ tests.set(Charity, readSpecs('commerce_charity_v1_oas3.json', import.meta.url)); tests.set(Notification, readSpecs('commerce_notification_v1_oas3.json', import.meta.url)); tests.set(Media, readSpecs('commerce_media_v1_beta_oas3.json', import.meta.url)); tests.set(Message, readSpecs('commerce_message_v1_oas3.json', import.meta.url)); +tests.set(Feedback, readSpecs('commerce_feedback_v1_beta_oas3.json', import.meta.url)); export default tests;