<!-- Generated by scripts/generate-llms.mjs from docs/connectors/etsy.md. Do not edit. -->

Source: https://qbash.com/docs/connectors/etsy

# 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](https://qbash.com/docs-markdown/mcp-servers/overview.md#package) 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](https://www.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](https://www.etsy.com/developers/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](https://qbash.com/docs-markdown/tasks/task-editor.md#resources).

## Methods

| Resource | Method | Read or write |
| --- | --- | --- |
| Shops | `get_shop` | Read |
| Shop sections | `list_shop_sections` | Read |
| Listings | `list_listings` (active listings only) | Read |
| Listings | `get_listing` | Read |
| Listing images | `list_listing_images` | Read |

See the [SDK Reference](https://qbash.com/docs-markdown/tasks/sdk-reference.md) for parameters and return shapes.

## Task example

```python
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.
