Module ebay.recommendation
ballerinax/ebay.recommendation Ballerina library
Overview
This is a generated connector for Ebay Recommendation API v1.1.0 OpenAPI specification. The Ebay Recommendation API returns information that sellers can use to configure Promoted Listings ad campaigns. The Recommendation API currently has a single recommendation type, AD, that returns information pertaining to Promoted Listings ad campaigns. Seller can use the recommendations returned as guidelines for setting up campaigns. In the eBay marketplace, where an increased visibility directly correlates to the buyer conversion rate, information returned with the AD recommendation type can help you know which listings to promote and how to configure ad campaigns. API documentation
Prerequisites
Before using this connector in your Ballerina application, complete the following:
- Create eBay developer account
- Obtain tokens - Follow this link
Quickstart
To use the ballerinax/ebay.recommendation connector in your Ballerina application, update the .bal file as follows:
- Import the module
import ballerinax/ebay.recommendation;
Step 2: Create a new connector instance
Create a recommendation:ClientConfig with the OAuth2 tokens obtained, and initialize the connector with it.
configurable http:BearerTokenConfig & readonly auth = ?; recommendation:ClientConfig clientConfig = {auth: auth}; recommendation:Client baseClient = check new Client(clientConfig);
Step 3 : Invoke connector operation
- Now you can use the operations available within the connector. Note that they are in the form of remote operations.
Following is an example on how to get information that can help sellers optimize listing configurations.
public function main() { recommendation:PagedListingRecommendationCollection response = check baseClient->findListingRecommendations(xEbayCMarketplaceId, listingIds); }
- Use
bal runcommand to compile and run the Ballerina program.
Clients
ebay.recommendation: Client
This is a generated connector for Ebay Recommendation API v1.1.0 OpenAPI specification.
'The Recommendation API returns information that sellers can use to optimize the configuration of their listings on eBay.
Currently, the API contains a single method, findListingRecommendations.
This method provides information that sellers can use to configure Promoted Listings ad campaigns to maximize the visibility of their items in the eBay marketplace.'
Constructor
Gets invoked to initialize the connector.
The connector initialization requires setting the API credentials.
Create eBay developer account and obtain tokens by following this guide.
init (ConnectionConfig config, string serviceUrl)- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.ebay.com/sell/recommendation/v1" - URL of the target service
findListingRecommendations
function findListingRecommendations(string xEbayCMarketplaceId, FindListingRecommendationRequest payload, string? filter, string? 'limit, string? offset) returns PagedListingRecommendationCollection|error?The find method currently returns information for a single recommendation type (AD) which contains information that sellers can use to configure Promoted Listings ad campaigns. The response from this method includes an array of the seller's listing IDs, where each element in the array contains recommendations related to the associated listing ID. For details on how to use this method, see Using the Recommendation API to help configure campaigns. The AD recommendation type The AD type contains two sets of information: The promoteWithAd indicator The promoteWithAd response field indicates whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. The returned value is set to either RECOMMENDED or UNDETERMINED, where RECOMMENDED identifies the listings that will benefit the most from having them included in an ad campaign. The bid percentage Also known as the "ad rate," the bidPercentage field provides the current trending bid percentage of similarly promoted items in the marketplace. The ad rate is a user-specified value that indicates the level of promotion that eBay applies to the campaign across the marketplace. The value is also used to calculate the Promotion Listings fee, which is assessed to the seller if a Promoted Listings action results in the sale of an item. Configuring the request You can configure a request to review all of a seller's currently active listings, or just a subset of them. All active listings – If you leave the request body empty, the request targets all the items currently listed by the seller. Here, the response is filtered to contain only the items where promoteWithAd equals RECOMMENDED. In this case, eBay recommends that all the returned listings should be included in a Promoted Listings ad campaign. Selected listing IDs – If you populate the request body with a set of listingIds, the response contains data for all the specified listing IDs. In this scenario, the response provides you with information on listings where the promoteWithAd can be either RECOMMENDED or UNDETERMINED. The paginated response Because the response can contain many listing IDs, the findListingRecommendations method paginates the response set. You can control size of the returned pages, as well as an offset that dictates where to start the pagination, using query parameters in the request.
Parameters
- xEbayCMarketplaceId string - Use this header to specify the eBay marketplace where you list the items for which you want to get recommendations.
- payload FindListingRecommendationRequest -
- filter string? (default ()) - Provide a list of key-value pairs to specify the criteria you want to use to filter the response. In the list, separate each filter key from its associated value with a colon (":"). Currently, the only supported filter value is recommendationTypes and it supports only the ("AD") type. Follow the recommendationTypes specifier with the filter type(s) enclosed in curly braces ("{ }"), and separate multiple types with commas. Example: filter=recommendationTypes:{AD} Default: recommendationTypes:{AD}
- 'limit string? (default ()) - Use this query parameter to set the maximum number of ads to return on a page from the paginated response. Default: 10 Maximum: 500
- offset string? (default ()) - Specifies the number of ads to skip in the result set before returning the first ad in the paginated response. Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set. Default: 0
Return Type
- PagedListingRecommendationCollection|error? - Success
Records
ebay.recommendation: Ad
A complex type that contains recommendations and information on how to configure Promoted Listings ad campaigns.
Fields
- bidPercentages BidPercentages[]? - This field returns information that you can use to configure the bidPercentage field in a Promoted Listings campaign. Note: Currently, ITEM and TRENDING are the only supported bid percentage types. The ITEM suggested bid percentages are tailored to each of your items and are designed to help you stay competitive while finding an optimal balance between performance and cost. The recommendations are calculated based on a variety of factors that may include item attributes, seasonality, past performance, and current competition for each of your listings. The TRENDING suggested bid percentages are calculated by reviewing the category level average ad rates in the marketplace. Setting the bidPercentage of your ad campaign based on these rate recommendations will help the items in the campaign be competitive with other items in the marketplace by improving their chances of being displayed more often in the marketplace.
- promoteWithAd string? - An enum whose values describe whether or not eBay recommends you place the associated listing in a Promoted Listings ad campaign. IDs deemed RECOMMENDED by eBay are the listings with the highest potential of benefiting from being promoted. The recommendation calculation is based on marketplace trends, like buyer demand and the competition in the item’s category. Note: A promoteWithAd value cannot be calculated for listings that are part of Promoted Listings campaigns. Because of this, if you call findListingRecommendations with a specific set of listing IDs, the promoteWithAd field is not returned for any of the listings that are involved in a promotion. However, as long as they are eligible, the trending bidPercentage is returned for all specified listings, even if they are part of an ad campaign. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/recommendation/types/api:PromoteWithAd'>eBay API documentation</a>
ebay.recommendation: BidPercentages
A complex type that returns data related to Promoted Listings bid percentages.
Fields
- basis string? - The basis by which the ad rate is calculated. Valid Values: ITEM and TRENDING For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/recommendation/types/api:Basis'>eBay API documentation</a>
- value string? - The bid percentage data is a single precision value, as calculated by the associated basis. In Promoted listings ad campaigns, the bid percentage (also known as the ad rate) is a user-defined value that sets the level that eBay raises the visibility of the listing in the marketplace. It is also the rate that is used to calculate the Promoted Listings fee. Minimum value: 1.0 Maximum value: 100.0
ebay.recommendation: ClientHttp1Settings
Provides settings related to HTTP/1.x protocol.
Fields
- keepAlive KeepAlive(default http:KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
- chunking Chunking(default http:CHUNKING_AUTO) - The chunking behaviour of the request
- proxy ProxyConfig? - Proxy server related options
ebay.recommendation: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth BearerTokenConfig|OAuth2RefreshTokenGrantConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings? - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings? - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- poolConfig PoolConfiguration? - Configurations associated with request pooling
- cache CacheConfig? - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker CircuitBreakerConfig? - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig RetryConfig? - Configurations associated with retrying
- responseLimits ResponseLimitConfigs? - Configurations associated with inbound response size limits
- secureSocket ClientSecureSocket? - SSL/TLS-related options
- proxy ProxyConfig? - Proxy server related options
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
ebay.recommendation: Error
This type defines the fields that can be returned in an error.
Fields
- category string? - Identifies the type of erro.
- domain string? - Name for the primary system where the error occurred. This is relevant for application errors.
- errorId int? - A unique number to identify the error.
- inputRefIds string[]? - An array of request elements most closely associated to the error.
- longMessage string? - A more detailed explanation of the error.
- message string? - Information on how to correct the problem, in the end user's terms and language where applicable.
- outputRefIds string[]? - An array of request elements most closely associated to the error.
- parameters ErrorParameter[]? - An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.
- subdomain string? - Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc.
ebay.recommendation: ErrorParameter
Fields
- name string? - The object of the error.
- value string? - The value of the object.
ebay.recommendation: FindListingRecommendationRequest
An list of listing ID values for which you want Promoted Listings ad configuration information.
Fields
- listingIds string[]? - A comma-separated list of listing IDs for which you want Promoted Listings ad configuration information. Currently, this method accepts only listingId values from the Trading API. Max: 500 listing IDs
ebay.recommendation: ListingRecommendation
A complex type that contains the ID of an actively listed item and a set of related listing recommendations. The recommendations contain information the seller can use to optimize their listing configurations.
Fields
- listingId string? - An ID that identifies the active listing associated with the eBay recommendations.
- marketing MarketingRecommendation? - A complex type that contains information about how a seller can improve their listing configurations. The AD object contains Promoted Listings recommendations and information, which the seller can use to improve buyer conversions. The response can also contain an optional message about the returned data.
ebay.recommendation: MarketingRecommendation
A complex type that contains information about how a seller can improve their listing configurations. The AD object contains Promoted Listings recommendations and information, which the seller can use to improve buyer conversions. The response can also contain an optional message about the returned data.
Fields
- ad Ad? - A complex type that contains recommendations and information on how to configure Promoted Listings ad campaigns.
- message string? - A message that can conditionally accompany the listing information.
ebay.recommendation: OAuth2RefreshTokenGrantConfig
OAuth2 Refresh Token Grant Configs
Fields
- Fields Included from *OAuth2RefreshTokenGrantConfig
- refreshUrl string(default "https://api.ebay.com/identity/v1/oauth2/token") - Refresh URL
ebay.recommendation: PagedListingRecommendationCollection
The high-level object used to return a set of Promoted Listings ad recommendations.
Fields
- href string? - The URI of the current page of results from the result set.
- 'limit int? - The number of items returned on a single page from the result set. This value can be set in the request with the limit query parameter.
- listingRecommendations ListingRecommendation[]? - Returns a list of listingRecommendations, where each element in the list offers recommendations for the associated listingId. Which elements are returned depend on how you structure the request. For example, if you request recommendations for all of a sellers listings (by leaving the request payload empty), ad recommendations are returned only for those listings where promoteWithAd is set to RECOMMENDED.
- next string? - The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set. Max length: 2048
- offset int? - The number of results skipped in the result set before listing the first returned result. This value can be set in the request with the offset query parameter. Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.
- prev string? - The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set. Max length: 2048
- total int? - The total number of items retrieved in the result set. If no items are found, this field is returned with a value of 0.
ebay.recommendation: ProxyConfig
Proxy server configurations to be used with the HTTP client endpoint.
Fields
- host string(default "") - Host name of the proxy server
- port int(default 0) - Proxy server port
- userName string(default "") - Proxy server username
- password string(default "") - Proxy server password