/ 
eBay-Client-OpenAPI3-0.01
/ eBay::Client::OpenAPI3

NAME

eBay::Client::OpenAPI3 - lightweight client for selected eBay REST APIs

VERSION

Version 0.01

SYNOPSIS

use eBay::Client::OpenAPI3;

my $ebay = eBay::Client::OpenAPI3->new(
    config => "$ENV{HOME}/.ebayapi3.conf",
);

my $results = $ebay->oauth2->browse(
    category_ids => 13956,
    q            => 'patch insignia SSI',
    filter       => 'buyingOptions:{AUCTION}',
    limit        => 50,
    offset       => 0,
    sort         => 'newlyListed',
);

DESCRIPTION

eBay::Client::OpenAPI3 is a small client for the parts of eBay's REST API currently needed by its applications. Version 0.01 supports application OAuth2, Browse API search, retrieving a Browse item from a legacy numeric item ID, and Developer Analytics rate-limit information.

The client intentionally remains close to the API. It does not attempt to be a complete generated OpenAPI client, and Browse query parameters are passed through with minimal transformation.

CONFIGURATION

The constructor takes the filename of an INI configuration file. It does not take a token hashref.

[eBay]
client_id            = your-client-id
client_secret        = your-client-secret
affiliateCampaignId  = your-epn-campaign-id
affiliateReferenceId = optional-reference-id

client_id and client_secret are used to obtain an application OAuth token. The existing client behavior uses affiliateCampaignId when building the X-EBAY-C-ENDUSERCTX request header. affiliateReferenceId is retained in the configuration format for compatibility with existing deployments but is not currently added to that header by this module.

The production endpoint and EBAY_US marketplace are currently fixed in the implementation.

METHODS

new

my $ebay = eBay::Client::OpenAPI3->new(
    config => '/path/to/.ebayapi3.conf',
);

Constructs a client and reads the INI configuration file. The file must exist. No network request is made by the constructor.

oauth2

$ebay->oauth2;

Obtains an application OAuth token using the client-credentials flow, stores the decoded token response in $ebay->token, and returns the client object so calls can be chained.

browse

my $results = $ebay->browse(%params);

Calls the Browse API item_summary/search endpoint:

/buy/browse/v1/item_summary/search

Undefined values are omitted from the query string. Common parameters include category_ids, q, filter, limit, offset, and sort. Other supplied parameters are passed through rather than checked against a local copy of the eBay schema.

The decoded response is returned as nested accessor objects. The response's next URL and total value are also stored in $ebay->next and $ebay->total.

getItem

my $item = $ebay->getItem(itemid => 123456789012);

Retrieves one Browse item. The supplied numeric legacy item ID is converted to the REST Browse item-ID form v1|ITEMID|0.

This camel-case spelling is the original public interface and is retained for compatibility.

get_item

my $item = $ebay->get_item(itemid => 123456789012);

A Perl-style alias for getItem. It does not change the behavior of the original method.

rate_limit

my $info = $ebay->rate_limit(api_name => 'browse');

Calls the Developer Analytics rate-limit endpoint:

/developer/analytics/v1_beta/rate_limit

Query parameters are passed through to the endpoint.

get_ua

Builds the authenticated HTTP::Tiny client used for API requests. Normal callers generally use oauth2 first and then call one of the API methods.

ERROR HANDLING

For Browse, item, and rate-limit requests, HTTP error responses cause the method to die. The client attempts to use errors[0].longMessage where available and includes the HTTP status. eBay rate/throttle headers are warned when present on those failures.

Version 0.01 deliberately preserves the pre-CPAN OAuth behavior rather than changing failure semantics during packaging cleanup.

COMPATIBILITY

The initial CPAN release is intended to preserve the behavior of the pre-CPAN client and the ebayapi3 utility used by existing applications. New method names and test seams in 0.01 are additive.

LIMITATIONS

This release implements only a small subset of eBay's REST API surface. It does not validate OpenAPI schemas, normalize responses into separate domain classes, or expose every Browse resource.

BUGS AND SUPPORT

Please report bugs and feature requests at:

https://github.com/oodler577/p5-eBay-Client-OpenAPI3/issues

Source repository:

https://github.com/oodler577/p5-eBay-Client-OpenAPI3

AUTHOR

Oodler 577 <oodler@cpan.org>

LICENSE AND COPYRIGHT

This software is copyright (c) 2026 by Brett Estrade.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.