Download the PHP package christianjbrown/etsy-open-api-sdk without Composer

Etsy Open API v3 SDK

A strongly-typed PHP client for the Etsy Open API v3. It reads and writes your shop's data — receipts, listings, shipping profiles, and more — returning plain, typed model objects rather than raw arrays, and taking plain, typed request objects for anything you create or update.

Every operation in Etsy's published OpenAPI spec is covered: all GET endpoints, and every POST, PUT, PATCH and DELETE write. A write beyond the shop the client is configured for needs the matching OAuth scope granted to your access token (see "Prerequisites" below) — the read side currently supports:

• Reading shop receipts — a page of the shop's receipts (getMultiple), a page plus the shop's total receipt count so you can walk the whole set (getPage), or a single receipt by id (getOneById). Each receipt carries the full order: buyer and address fields, the money totals (grandtotal, subtotal, shipping, tax, VAT, discount, gift wrap), and its nested transactions, refunds, and shipments.

Supported read endpoints

Supported write endpoints

Every write takes a Model\XRequest object (constructed directly, or via its fluent setters for the optional fields) and returns the same typed model a read would. DELETE operations return void. See "Prerequisites" below for how OAuth scopes work.

:heavy_check_mark: Prerequisites

• Git
• PHP 8.5 or higher (8.x)
• Composer
• An Etsy OAuth access token carrying the scope(s) your calls need. Every read endpoint needs the matching _r scope (listings_r, transactions_r, shops_r, …); every write additionally needs the matching _w scope (listings_w, listings_d for deleteListing, transactions_w, shops_w), and deleteUserAddress needs address_r. See the "Supported write endpoints" table above for the exact scope each write call needs, and Etsy's own scopes documentation for how scopes are requested during the OAuth authorization flow. A token missing a scope gets a 403 from Etsy, not a client-side error — this library does not validate scopes locally.

: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

Etsy's Open API v3 authenticates every request with two pieces: your app's keystring (sent as the x-api-key header) and an OAuth 2.0 access token (sent as Authorization: Bearer …). Access tokens are short-lived, so this client refreshes them for you using a long-lived refresh token and the OAuth2 refresh_token grant.

You supply four things to EtsyFactory::create():

• your numeric shop id,
• your app keystring (which Etsy also uses as the OAuth client_id),
• 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 (a database, secret store, etc.), because Etsy rotates the refresh token on every refresh and the client writes the new value back. Seed it once with a refresh token obtained from Etsy's OAuth authorization flow.

Reading receipts then looks like this:

getMultiple() hands back just the receipts on the page, which is enough when you only want the most recent orders. To walk every receipt, use getPage() instead: it returns a ReceiptPageInterface carrying the shop's total receipt count alongside the page, so the loop knows when to stop without having to guess from a short page.

Writing data follows the same shape: build a Model\XRequest, and call the matching client method. Optional fields are set through fluent setters, exactly like a model's getters mirror the response:

See "Supported write endpoints" above for the full list of write calls and their required OAuth scopes.

Pointing at a different host

EtsyFactory::create() uses Etsy's production hosts. EtsyFactory::createForHost() takes the same arguments plus an EtsyHostInterface. Pass a differently configured EtsyHost to point every request, and the OAuth token refresh, somewhere else — a test double, a proxy, or a sandbox once Etsy publishes one:

Etsy's Open API v3 has no published sandbox at the time of writing (unlike, say, eBay's api.sandbox.ebay.com/apiz.sandbox.ebay.com), so the only two hosts this library knows about are the production ones above. EtsyHost exists so a test double or a future sandbox host can be swapped in without editing any Api/ class.

Upgrading to 2.0

Etsy no longer builds its own services, so it is no longer constructed with the shop id, keys and stores. Build it with EtsyFactory instead:

new Etsy($container) now takes a PSR-11 container and is meant for code that wires its own graph. If you construct ListingWithAssociationsTransformer yourself, it now takes an array of ListingWithAssociationsFieldsTransformerInterface implementations.

This release also moves to christianjbrown/api-client 3, christianjbrown/oauth2-client 2.1 and christianjbrown/key-value-store 3. The key-value stores now need a PSR-20 clock, so build the in-memory stores as new MemoryKeyValueStore(new NativeClock()) (symfony/clock) and give FirestoreKeyValueStore a clock as its second argument. In-memory stores now enforce TTLs. If you wire clients by hand, ApiClient is built with (new ApiClientFactory(new ClientOptions()))->create() and RefreshTokenManager with (new RefreshTokenManagerFactory(new NativeClock()))->create(...), which takes a client authentication (PublicClientAuthentication for Etsy) and a lock (NullLock for none).

:rotating_light: Error handling

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

There are two concrete types:

• UnexpectedResponseException (extends RuntimeException) — the Etsy API returned a body the client or a transformer couldn't parse (a missing/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 RequestExceptionInterface from christianjbrown/api-client; token-refresh failures surface as RequestExceptionInterface from christianjbrown/oauth2-client. Both are outside this library's exception hierarchy.

Under the hood, Etsy wires the clients, their transformer chains, and the OAuth refresh 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.

:memo: Changelog

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

:page_facing_up: License

Released under the MIT License.