{"id":46993447,"url":"https://github.com/rhysnhall/etsy-php-sdk","last_synced_at":"2026-03-11T14:38:15.619Z","repository":{"id":45210757,"uuid":"250961216","full_name":"rhysnhall/etsy-php-sdk","owner":"rhysnhall","description":"PHP SDK for Etsy API v3.","archived":false,"fork":false,"pushed_at":"2025-12-05T09:28:38.000Z","size":108,"stargazers_count":51,"open_issues_count":2,"forks_count":41,"subscribers_count":14,"default_branch":"1.0","last_synced_at":"2025-12-08T18:26:22.006Z","etag":null,"topics":["etsy","etsy-api","etsy-api-v3","php","sdk","sdk-php"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhysnhall.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-03-29T05:32:19.000Z","updated_at":"2025-12-05T09:27:20.000Z","dependencies_parsed_at":"2025-02-25T23:23:37.048Z","dependency_job_id":"79092ebf-fb48-4c8e-ab89-8f81927ee434","html_url":"https://github.com/rhysnhall/etsy-php-sdk","commit_stats":null,"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/rhysnhall/etsy-php-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysnhall%2Fetsy-php-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysnhall%2Fetsy-php-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysnhall%2Fetsy-php-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysnhall%2Fetsy-php-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhysnhall","download_url":"https://codeload.github.com/rhysnhall/etsy-php-sdk/tar.gz/refs/heads/1.0","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysnhall%2Fetsy-php-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30384111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T14:10:17.325Z","status":"ssl_error","status_checked_at":"2026-03-11T14:09:37.934Z","response_time":84,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["etsy","etsy-api","etsy-api-v3","php","sdk","sdk-php"],"created_at":"2026-03-11T14:38:13.780Z","updated_at":"2026-03-11T14:38:15.596Z","avatar_url":"https://github.com/rhysnhall.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Etsy PHP SDK\nA PHP SDK for the Etsy API v3.\n\nProper documentation still to come. Want to write it for me? I'll buy you an iced latte.\n\n## Requirements\nPHP 8 or greater.\n\n## Install\nInstall the package using composer.\n```php\ncomposer require rhysnhall/etsy-php-sdk\n```\n\nInclude the Etsy class.\n```php\nuse Etsy\\Etsy;\n\n$etsy = new Etsy(\n  $client_id,\n  $shared_secret,\n  $access_token\n);\n\n// Do the Etsy things.\n```\n\n## Usage\n\n### Authorizing your app\nThe Etsy API uses OAuth 2.0 authentication. You can read more about authenticating with Etsy on their [documentation](https://developers.etsy.com/documentation/essentials/authentication).\n\nThe first step in OAuth2 is to request an OAuth token. You will need an existing App API key and shared secret which you can obtain by registering an app [here](https://www.etsy.com/developers/register).\n```php\n$client = new Etsy\\OAuth\\Client(\n  $client_id,\n  $shared_secret\n);\n```\n\nGenerate a URL to redirect the user to authorize access to your app.\n```php\n$url = $client-\u003egetAuthorizationUrl(\n  $redirect_uri,\n  $scopes,\n  $code_challenge,\n  $nonce\n);\n```\n\n###### Redirect URI\nYou must set an authorized callback URL. Check out the [Etsy documentation](https://developers.etsy.com/documentation/essentials/authentication#redirect-uris) for further information.\n\n###### Scope\nDepending on your apps requirements, you will need to specify the [permission scopes](https://developers.etsy.com/documentation/essentials/authentication#scopes) you want to authorize access for.\n```php\n$scopes = [\"listings_d\", \"listings_r\", \"listings_w\", \"profile_r\"];\n```\n\nYou can get all scopes, but it is generally recommended to only get what you need.\n```php\n$scopes = \\Etsy\\Utils\\PermissionScopes::ALL_SCOPES;\n```\n\n###### Code challenge\nYou'll need to generate a [PKCE code challenge](https://developers.etsy.com/documentation/essentials/authentication#proof-key-for-code-exchange-pkce) and save this along with the verifier used to generate the challenge. You are welcome to generate your own, or let the SDK do this for you.\n```php\n[$verifier, $code_challenge] = $client-\u003egenerateChallengeCode();\n```\n\n###### Nonce\nThe nonce is a single use token used for CSRF protection. You can use any token you like but it is recommended to let the SDK generate one for you each time you authorize a user. Save this for verifying the response later on.\n```php\n$nonce = $client-\u003ecreateNonce();\n```\n\n\nThe URL will redirect your user to the Etsy authorization page. If the user grants access, Etsy will send back a request with an authorization code and the nonce (state).\n```curl\nhttps://www.example.com/some/location?\n      code=bftcubu-wownsvftz5kowdmxnqtsuoikwqkha7_4na3igu1uy-ztu1bsken68xnw4spzum8larqbry6zsxnea4or9etuicpra5zi\n      \u0026state=superstate\n```\n\nIt is up to you to validate the nonce. If they do not match you should discard the response.\n\nFor more information on Etsy's response, check out the [documentation here](https://developers.etsy.com/documentation/essentials/authentication#step-2-grant-access).\n\nThe final step is to get the access token for the user. To do this you will need to make a request using the code that was just returned by Etsy. You will also need to pass in the same callback URL as the first request and the verifier used to generate the PKCE code challenge.\n```php\n[$access_token, $refresh_token] = $client-\u003erequestAccessToken(\n  $redirect_uri,\n  $code,\n  $verifier\n);\n```\n\nYou'll be provided with both an access token and a refresh token. The access token has a valid duration of 3600 seconds (1 hour). Save both of these for late use.\n\n#### Refreshing your token\n\nYou can refresh your authorization token (even after it has expired) using the refresh token that was previously provided. This will provide you with a new valid access token and another refresh token.\n\n```php\n[$access_token, $refresh_token] = $client-\u003erefreshAccessToken($refresh_token);\n```\n\nThe [Etsy documentation](https://developers.etsy.com/documentation/essentials/authentication#requesting-a-refresh-oauth-token) states that refreshed access tokens have a duration of 86400 seconds (24 hours) but on testing they appear to only remain valid for up 3600 seconds (1 hour).\n\n#### Exchanging legacy OAuth 1.0 token for OAuth 2.0 token\nIf you previously used v2 of the Etsy API and still have valid authorization tokens for your users, you may swap these over for valid OAuth2 tokens.\n```php\n[$access_token, $refresh_token] = $client-\u003eexchangeLegacyToken($legacy_token);\n```\n\nThis will provide you with a brand new set of OAuth2 access and refresh tokens.\n\n### Basic use\n\nCreate a new instance of the Etsy class using your App API key, app shared secret and a user's access token. **You must always initialize the Etsy resource before calling any resources**.\n\n```php\nuse Etsy\\Etsy;\nuse Etsy\\Resources\\User;\n\n$etsy = new Etsy($apiKey, $sharedSecret, $accessToken);\n\n// Get the authenticated user.\n$user = User::me();\n\n// Get the users shop.\n$shop = $user-\u003eshop();\n```\n\n#### Resources\nMost calls will return a `Resource`. Resources contain a number of methods that streamline your interaction with the Etsy API.\n```php\n// Get a Listing Resource\n$listing = \\Etsy\\Resources\\Listing::get($shopId);\n```\n\nResources contain the API response from Etsy as properties.\n```php\n$listingTitle = $listing-\u003etitle;\n```\n\n##### Associations\nResources will return associations as their respective Resource when appropriate. For example the bellow call will return the `shop` property as an instance of `Etsy\\Resources\\Shop`.\n```php\n$shop = $listing-\u003eshop;\n```\n\n##### `toJson`\nThe `toJson` method will return the Resource as a JSON encoded object.\n```php\n$json = $listing-\u003etoJson();\n```\n\n##### `toArray`\nThe `toArray` method will return the Resource as an array.\n```php\n$array = $listing-\u003etoArray();\n```\n\n#### Collections\nWhen there is more than one result a collection will be returned.\n```php\n$reviews = Review::all();\n```\n\nResults are stored as an array of `Resource` on the `data` property of the collection.\n```php\n$firstReview = $reviews-\u003edata[0];\n```\n\nCollections contain a handful of useful methods.\n\n##### `first`\nGet the first item in the collection.\n```php\n$firstReview = $reviews-\u003efirst();\n```\n\n##### `count`\nGet the number of results in the collection. Not be confused with the `count` property which displays the number of results in a full Etsy resource.\n```php\n$count = $reviews-\u003ecount();\n```\n\n##### `append`\nAppend a property to each item in the collection.\n```php\n$reviews-\u003eappend(['shop_id' =\u003e $shopId]);\n```\n\n##### `paginate`\nMost Etsy methods are capped at 100 results per call. You can use the `paginate` method to get more results than this (up to 500 results).\n```php\n// Get 100 results using pagination.\nforeach($reviews-\u003epaginate(200) as $review) {\n  ...\n}\n```\n\n##### `toJson`\nReturns the items in the collection as an array of JSON strings.\n```php\n$jsonArray = $reviews-\u003etoJson();\n```\n\n#### Direct Requests\nYou can make direct requests to the Etsy API using the static `$client` property of the Etsy class.\n\n```php\n$response = Etsy::$client-\u003eget(\n  \"/application/listings/active\",\n  [\n    \"limit\" =\u003e 25\n  ]\n);\n```\n\nIf you still want to use the Resources classes you can convert the response into a `Resource`. Pass the response from the client as the first parameter and the name of the resource as the second. If the response is an array then a `Collection` will be returned.\n\n```php\n$listings = Etsy::getResource(\n  Etsy::$client-\u003eget(\"/application/listings/active\"),\n  'Listing'\n);\n```\n\n### File Uploads\n\nEtsy listings support uploads for files, images and videos depending on the Listing type. The SDK includes ***basic*** support for uploading files.\n\n#### Images\nTo upload an image you need to pass the image data under the `image` parameter on your request as if it was prepared for multipart form-data.\n\n```php\n$data = [\n  'image' =\u003e [\n    'content' =\u003e fopen('./path-to-image.jpg')\n  ]\n];\n$image = ListingImage::create(\n  $shopId,\n  $listingId,\n  $data\n);\n```\n\nFor convenience you can just include a path or an external URL and the SDK will handle ***basic*** reading of the file.\n\n```php\n$data = [\n  'image' =\u003e './path-to-image.jpg'\n];\n```\n\n#### Other files\nVideo and file uploads work the same way but these also require a `name` parameter on the upload request. This name just represents the name of the file to upload.\n\n```php\nListingVideo::create(\n  $shopId,\n  $listingId,\n  [\n    'video' =\u003e './path-to-video.mp4',\n    'name' =\u003e $fileName\n  ]\n);\n\nListingFile::create(\n  $shopId,\n  $listingId,\n  [\n    'file' =\u003e './downloadable-template.pdf',\n    'name' =\u003e $fileName\n  ]\n);\n```\n\n### Instance Methods\nMost of the SDK is built around calling static methods on the different Etsy resources. For convenience some resources contain instance methods. These are designed to streamline interaction with the SDK.\n\n#### Save method\nMany resources contain a `save()` method which is a convenient shortcut for a patch request. In most cases the current data will be compared against the values of the `_originalState` property on the Resource and if no data has been changed the patch request will be skipped.\n\n```php\n$listing = \\Etsy\\Resources\\Listing::get($listingId);\n\n# Update listing title.\n$listing-\u003etitle = 'Updated title';\n$listing-\u003esave();\n```\n\n#### Other methods\nReview each Resource to better understand the methods available. There are some examples below of methods available to the ***Listing*** resource.\n\n```php\n$listing-\u003eimages(); // Get all images for the listing.\n$listing-\u003euploadImage($imageData); // Upload a new image.\n$listing-\u003einventory(); // Get the listing inventory.\n$listing-\u003etranslation('en'); // Get the English translation for the listing.\n```\n\n---\n\nFull documentation will be available soon (or so I keep saying). Email [hello@rhyshall.com](mailto:hello@rhyshall.com) for any assistance.\n\n## Contributing\nHelp improve this SDK by contributing.\n\nBefore opening a pull request, please first discuss the proposed changes via Github issue or \u003ca href=\"mailto:hello@rhyshall.com\"\u003eemail\u003c/a\u003e.\n\n## License\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/rhysnhall/etsy-php-sdk/blob/master/LICENSE.md) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysnhall%2Fetsy-php-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhysnhall%2Fetsy-php-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysnhall%2Fetsy-php-sdk/lists"}