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

eBay Sell Fulfillment API SDK

A strongly-typed PHP client for the eBay Sell Fulfillment API. It reads a seller's orders, shipments and payment disputes — and writes shipping fulfillments, refunds and dispute responses — returning plain, typed model objects rather than raw arrays.

getOrders returns roughly two years of order history, which makes it the practical way to reconstruct lifetime sold counts per listing: every LineItem carries its legacyItemId, lineItemId, sku, quantity, title and lineItemCost, so aggregating quantity by legacyItemId gives a sold count that survives the listing ending.

:warning: Only getOrders has been exercised against live eBay traffic. The rest is built strictly to eBay's published OpenAPI contract (sell_fulfillment v1.20.6). See Live traffic for what has been confirmed and what to smoke-test next.

Supported endpoints

Every response type in the contract is modelled: Order, LineItem, LineItemFulfillmentInstructions, Buyer, PricingSummary, PaymentSummary, Payment, FulfillmentStartInstruction, ShippingStep, Address, Amount, Tax, Refund, ShippingFulfillment, PaymentDispute, DisputeEvidence and the rest, plus eBay's standard Error payload (returned in the warnings array of both paged collections).

: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

Every Sell Fulfillment request carries an OAuth 2.0 user access token (Authorization: Bearer …) and the seller's marketplace (X-EBAY-C-MARKETPLACE-ID). Access tokens are short-lived, so this client refreshes them for you using a long-lived refresh token and the OAuth2 refresh_token grant against https://api.ebay.com/identity/v1/oauth2/token.

You need a user token minted for the https://api.ebay.com/oauth/api_scope/sell.fulfillment.readonly scope (or …/sell.fulfillment for the write endpoints). Both are on SellFulfillmentInterface as OAUTH_SCOPE_SELL_FULFILLMENT_READONLY and OAUTH_SCOPE_SELL_FULFILLMENT. Obtaining the first refresh token needs a one-off browser consent flow, described in eBay's Getting user consent guide.

You supply these to SellFulfillmentFactory, the entry point that builds a client:

• an ApplicationCredentials holding your App ID (client id), your Cert ID (client secret, since eBay's token endpoint authenticates with HTTP Basic) and the marketplace id (EBAY_GB, EBAY_US, ... constants on CredentialsInterface),
• a TtlAwareKeyValueStoreInterface to hold the current access token (an in-memory store is fine, it's re-fetched as needed),
• a KeyValueStoreInterface holding your refresh token. This one must persist, because eBay rotates the refresh token on every refresh and the client writes the new value back.

The fourth argument, a LockInterface, serialises the refresh across processes so a rotating refresh token is never spent by two refreshes at once. Pass oauth2-client's NullLock when you have no lock. To override the hosts every request is built from, use createForHost() with an ApiHostInterface; see Targeting the sandbox below.

The SellFulfillment facade itself only takes a PSR-11 container, so it builds nothing. Everything is wired in SellFulfillmentFactory; to wire it differently, build your own container and pass it to new SellFulfillment($container).

Targeting the sandbox

Every request is built from a host the client resolves through ApiHostInterface: getApiUrl() for order and shipping fulfillment calls (defaults to https://api.ebay.com), getApizUrl() for payment dispute calls (defaults to https://apiz.ebay.com), and getOAuthTokenUrl() for the token endpoint (defaults to https://api.ebay.com/identity/v1/oauth2/token). Pass a custom ApiHost to createForHost() to point the whole client at eBay's sandbox — https://api.sandbox.ebay.com and https://apiz.sandbox.ebay.com:

Upgrading to 2.0

SellFulfillment no longer builds its own wiring. Construct it through SellFulfillmentFactory, and group the App ID, Cert ID and marketplace into an ApplicationCredentials.

The package now requires christianjbrown/api-client 3, oauth2-client 2.1 and key-value-store 3 (MemoryKeyValueStore and FirestoreKeyValueStore now take a PSR-20 clock). OrderServiceRegistrar is gone, replaced by smaller Order*Registrar classes, and CoreServiceRegistrar takes an ApplicationCredentialsInterface, an ApiClientInterface, a RefreshTokenManagerFactoryInterface and a required LockInterface. This only matters if you assembled the container yourself.

Reading orders

getOrders is paginated. The returned collection exposes getTotal(), getLimit(), getOffset(), getNext() and getPrev(), so driving the pages is a plain loop on offset:

A single order, optionally with the tax and fee breakdown:

Shipping fulfillments

Payment disputes

Evidence files are uploaded first and then attached to an evidence set:

Live traffic

getOrders runs against a real seller account: the creationdate:[…..…] filter, limit/offset paging, and lineItems[].legacyItemId and lineItems[].quantity all behave as documented, and eBay accepts the : and , that http_build_query percent-encodes. One thing the documentation does not say: a creationdate lower bound older than eBay's roughly two-year retention is rejected with errorId 30830 rather than quietly clamped, so keep the window inside it.

Nothing else has been run against a real account yet. Smoke-test in this order, since these are the calls whose contract detail is most likely to bite:

1. getOrder — the fieldGroups=TAX_BREAKDOWN variant.
2. createShippingFulfillment — that the 201/empty body is handled and the payload shape is accepted.
3. uploadEvidenceFile: the multipart/form-data body (field name file), which is the only request this SDK does not encode as JSON.
4. fetchEvidenceContent — that the raw application/octet-stream body comes back intact.

Payment dispute calls are served from apiz.ebay.com; order and fulfillment calls from api.ebay.com. Both hosts are baked into the API_URL* constants on the client interfaces.

:rotating_light: Error handling

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

There are two concrete types:

• UnexpectedResponseException (extends RuntimeException) — eBay 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.

Both live in src/Exception/. Request-level failures (network errors, non-2xx responses) surface as the exception interfaces of christianjbrown/api-client — BadResponseExceptionInterface exposes eBay's decoded error payload through getDecodedBody(). Token-refresh failures surface as ChristianBrown\OAuth2Client\Model\Exception\ExceptionInterface from christianjbrown/oauth2-client; in particular InvalidGrantExceptionInterface means the refresh token is dead and the consent flow has to be repeated. None of those are in this library's exception hierarchy.

Under the hood, SellFulfillment wires the clients, their transformer and serializer chains, and the OAuth refresh machinery through a Symfony dependency-injection container. If you don't want the container, you can build the same chains by hand — every class is final, takes its collaborators as constructor arguments, and implements a matching interface.

:memo: Changelog

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

:page_facing_up: License

Released under the MIT License.