Download the PHP package christianjbrown/ebay-browse-api-sdk without Composer

eBay Browse API SDK

A strongly-typed PHP client for the eBay Browse API. It reads eBay's public listing data — a single item, the items in a multi-variation listing, keyword and image searches, and part compatibility — returning plain, typed model objects rather than raw arrays.

The client is read-only and covers the whole public Browse surface. It authenticates with an application (client-credentials) OAuth2 token, so it needs no seller consent and no user token. Two things it does that a thin wrapper would not: it exposes estimatedAvailabilities, which carries the sold and remaining quantities that replaced the retired Shopping API's QuantitySold, and it turns eBay's "item not found" response into its own ItemNotFoundException so a caller can tell an ended listing apart from a failed request.

Supported endpoints

:warning: getItems() (GET /item) is a Limited Release Browse API call, available to select partners only. It needs an extra OAuth2 scope — https://api.ebay.com/oauth/api_scope/buy.item.bulk on top of the application's usual https://api.ebay.com/oauth/api_scope — which the client requests for you automatically for this one call; every other call keeps using the plain scope. Calling getItems() without that scope granted on your application answers with an authorization error.

ItemInterface and ItemSummaryInterface now cover eBay's full published field set: Item gained addonServices, authenticityGuarantee, authenticityVerification, availableCoupons, charityTerms, conditionDescriptors, ecoParticipationFee, gender, hazardousMaterialsLabels, inferredEpid, manufacturer, minimumPriceToBid, pattern, priceDisplayCondition, primaryItemGroup, primaryProductReviewRating, productFicheWebUrl, productSafetyLabels, qualifiedPrograms, quantityLimitPerBuyer, repairScore, reservePriceMet, responsiblePersons, sellerCustomPolicies, size, sizeSystem, sizeType, taxes, tyreLabelImageUrl and watchCount; ItemSummary gained compatibilityMatch, compatibilityProperties, distanceFromPickupLocation, pickupOptions, priceDisplayCondition, qualifiedPrograms and tyreLabelImageUrl. Product, PaymentMethod, Seller and ShippingOption also gained the remaining fields eBay documents for them (product identities and aspect groups; payment/seller instructions; userId and sellerLegalInfo; fulfilledThrough, shipToLocationUsedForEstimate and trademarkSymbol).

:heavy_check_mark: Prerequisites

• Git
• PHP 8.5 or higher (8.x)
• Composer

:bulb: If you're on MacOS and have Homebrew, PHP and Composer will install with brew install composer.

:building_construction: Installation

For your composer-enabled project:

:computer: Usage

The Browse API authenticates every request with an application access token — eBay's OAuth2 client_credentials grant against https://api.ebay.com/identity/v1/oauth2/token, scope https://api.ebay.com/oauth/api_scope. This client fetches and caches that token for you, so you supply only your app's client id and client secret from the eBay developer program.

Every request also carries a marketplace id (X-EBAY-C-MARKETPLACE-ID), which decides the site the data comes from and the currency prices are quoted in. That, plus the optional X-EBAY-C-ENDUSERCTX and Accept-Language headers, lives in a small Marketplace value object.

You supply four things to the Browse entry point, plus an optional fifth:

• your app's client id,
• your app's client secret,
• a MarketplaceInterface naming the marketplace to read,
• a TtlAwareKeyValueStoreInterface to hold the current access token (an in-memory store is fine — tokens last two hours and are re-fetched as needed; a shared store just saves round-trips),
• an ApiHostInterface naming which eBay environment to call: ApiHost::production() or ApiHost::sandbox() (see Overriding the API host).

BrowseFactory takes the API host and builds the Browse facade:

:satellite: Overriding the API host

Every request, including the OAuth2 token exchange, goes to the host you give BrowseFactory. To point the client at eBay's sandbox, pass ApiHost::sandbox() instead of ApiHost::production():

eBay runs the Buy APIs, including Browse, through a different sandbox gateway host than the rest of the platform: ApiHost::sandbox() calls the Browse API on apiz.sandbox.ebay.com and the OAuth2 token endpoint on api.sandbox.ebay.com. ApiHost::production() calls both on api.ebay.com. For any other host (a proxy, a mock server in tests), construct new ApiHost($browseApiBaseUrl, $oauthTokenUrl) directly.

:package: Reading one item

getOneById() takes a Browse item id (v1|123456789012|0); getOneByLegacyId() takes the plain numeric id you see in an eBay URL and optionally a variation id or SKU.

fieldgroups is passed straight through, so getOneById($itemId, 'PRODUCT') adds the catalogue product block, and the multi-variation parent of a listing is read with:

:package: Reading several items at once

getItems() (GET /item) reads up to 20 items or up to 10 item groups in a single call, given one of itemIds or itemGroupIds (never both). It is a Limited Release call — see the warning above — and returns only a reduced field set per item (no title, description or seller, for example), so treat every field on the returned items as optional even where a single-item read would guarantee it.

Reading by item group instead:

quantityForShippingEstimate is accepted here and by getOneById(), getOneByLegacyId() and getMultipleByItemGroupId(), and is passed straight through as the quantity_for_shipping_estimate query parameter.

:mag: Searching

search() exposes the full parameter set — keyword, GTIN, EPID, charity ids, category ids, aspect and compatibility filters, the general filter expression, sort, fieldgroups, auto_correct, and limit/offset pagination.

:bulb: eBay only returns itemSummaries alongside refinements when MATCHING_ITEMS is one of the fieldgroups. Ask for ASPECT_REFINEMENTS on its own and you get the refinements and nothing else.

searchByImage() takes a base64-encoded image and the same refinement parameters:

:wrench: Part compatibility

check() takes a Browse item id and a map of compatibility aspect names to values. The accepted names vary by marketplace and category — eBay answers 11507 listing the ones it does not recognise.

:rotating_light: Error handling

Everything this library throws implements ChristianBrown\EBay\Browse\Exception\ExceptionInterface, so a single catch covers it all:

There are three concrete types:

• ItemNotFoundException (extends RuntimeException) — eBay answered 404: the listing has ended, was deleted, or never existed. Catch this on its own to tell "this listing is gone" apart from "the request failed"; the original response is kept as the exception's previous throwable.
• UnexpectedResponseException (extends RuntimeException) — the Browse API returned a body the client or a transformer couldn't parse (a missing or mis-typed field, an empty response).
• MissingInputException (extends InvalidArgumentException) — bad caller input, e.g. check() with no compatibility properties or searchByImage() with an empty image.

All three live in src/Exception/. Other request-level failures (network errors, 400s, throttling) surface as RequestExceptionInterface from christianjbrown/api-client, and token failures as RequestExceptionInterface from christianjbrown/oauth2-client. Both are outside this library's exception hierarchy. A BadResponseExceptionInterface carries getDecodedBody(), which is where eBay's errors payload (its errorId, domain, category, message and longMessage) can be read.

Under the hood, Browse wires the clients, their transformer chains, and the OAuth machinery through a Symfony dependency-injection container. If you don't want the container, you can build the same chain by hand — as shown below.

:arrow_up: Upgrading to 2.0

Browse no longer builds anything itself: its constructor takes a PSR-11 container. The default wiring moved into BrowseFactory, and the API host is now a required argument rather than an optional fifth constructor argument.

If you construct clients by hand, ItemApi now requires its ItemsResponseTransformerInterface and getItems() cache, and ApiClientServiceRegistrar requires its getItems() cache, instead of building defaults. CoreServiceRegistrar now takes the ApiClientInterface, a ClientCredentialsTokenManagerFactoryInterface and a LockInterface; BrowseFactory supplies them. ItemTransformer takes eight part transformers instead of 29 nested ones.

This release also moves to christianjbrown/api-client 3, christianjbrown/oauth2-client 2.1 and christianjbrown/key-value-store 3. The access-token store you pass to create() must be built for key-value-store 3: new MemoryKeyValueStore(new NativeClock()) (it now needs a PSR-20 clock and enforces TTLs), and FirestoreKeyValueStore takes a clock too. The package now requires psr/clock and symfony/clock.

:memo: Changelog

Notable changes in each release are listed in CHANGELOG.md.

:page_facing_up: License

Released under the MIT License.