Skip to main content

Connect Etsy

Tasks call Etsy through qbash.integrations.etsy with the keystring and shared secret of an Etsy app that you store on the Connectors page. The connector reads public data for shops, shop sections, listings and listing images. Etsy does not charge for API access.

Private shop data, orders and every write are unavailable because Etsy requires an OAuth token for them, and this connector sends the key alone. That rules out receipts, transactions, shipping profiles, tracking, draft and inactive listings, and any change to a listing, section or shop.

Etsy limits each key to a single app. Each team registers its own app and uses its own key.

After you connect Etsy, you can add its tools to a qbash MCP server for ChatGPT, Claude and other MCP clients, or call it from a Python task.

Create the key​

  1. Sign in to Etsy, then open etsy.com/developers/register.
  2. Create a Seller App, which covers your own shop, and fill in the form.
  3. Wait for Etsy to approve the app. The key does not work until Etsy approves it, and the status shows under Your Apps.
  4. Open Your Apps, pick the app, and copy the keystring. Click the visibility icon beside the shared secret and copy that too. Do not publish the shared secret.
  5. Get your numeric shop ID. Tasks pass it as shop_id, and it is not the shop's name. Etsy's findShops endpoint returns it for a shop name, and this connector does not call that endpoint, so look the ID up outside qbash.

Add the key in qbash​

  1. Open Connectors, then Etsy, and click Connect.
  2. Fill in Credential Name, such as "My Etsy shop", then paste the keystring into Keystring and the shared secret into Shared Secret.
  3. Save. qbash stores both values encrypted. Saving does not call Etsy, so a call from a task is the first test of the key.
  4. In the task editor, choose Add connector from the Package + menu and select the credential. See Task resources.

Methods​

ResourceMethodRead or write
Shopsget_shopRead
Shop sectionslist_shop_sectionsRead
Listingslist_listings (active listings only)Read
Listingsget_listingRead
Listing imageslist_listing_imagesRead

See the SDK Reference for parameters and return shapes.

Task example​

page = qbash.integrations.etsy.list_listings(shop_id=12345678, limit=100, keywords="mug", sort_on="updated")
for listing in page["listings"]:
images = qbash.integrations.etsy.list_listing_images(listing_id=listing["listing_id"])
qbash.output({"title": listing["title"], "tags": len(listing["tags"]), "images": images["count"]})

Details that change results​

  • list_listings returns 25 listings by default and up to 100. Pass next_cursor back as cursor until it is None. Etsy serves at most 12000 listings by offset. Past that, next_cursor is None and truncated is True, so narrow the search with keywords.
  • sort_on and sort_order only work together with keywords. Without it the call is rejected. Etsy returns score results best match first, so sort_on="score" with an ascending sort_order is rejected.
  • price on a listing is a dict with amount, divisor and currency_code. Divide amount by divisor for the price in major units.
  • Inactive, draft, expired and sold out listings do not appear in list_listings, and get_listing answers 404 for a listing that is not public.
  • A 401 means Etsy rejected the keystring or shared secret. A 403 means Etsy refused the call, which can happen while the app is still waiting for approval. Only a 401 marks the credential as needing re-authentication.
  • Etsy applies per-second and per-day limits to each key. A 429 reply says how many seconds to wait.