> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Etsy rules, fees and updates

> MCP tools for Etsy's listing rules and fee schedule (dated and sourced) and for what changed on Etsy for sellers

These tools answer questions about Etsy itself rather than about a shop or a product. They're free, only read, and need the **Search and read Etsy market research** permission (`research:read`).

## Try these prompts

| Ask your assistant | Tools it uses |
| - | - |
| What does Etsy charge me on a 25 EUR sale? I'm based in France. | `get_etsy_fees` |
| Which Etsy fees changed for UK sellers this year? | `get_etsy_fees` |
| What changed on Etsy for sellers since September 1? | `get_etsy_updates` |
| Which Etsy fee changes affect a seller based in the UK this year? | `get_etsy_updates` |
| What has Etsy announced that isn't in effect yet? | `get_etsy_updates` |

## Good to know

* **Every rule and fee cites one Etsy page.** Etsy's Open API documentation doesn't state every limit, so each value links to the most authoritative Etsy page that does: the Open API documentation when it states it, else the Help Center article that says it most directly, else the Fees & Payments Policy or an Etsy staff post. A second page appears only for what the first doesn't say, such as the day a change started. Each source carries the date Alura read it.
* **Unknown isn't zero.** When Etsy doesn't publish a limit or a fee (a minimum listing price, VAT rates on fees, most set-up fees), the value is `null` with a `value_unknown` or `fee_unknown` notice. The assistant should say it's unknown, never that there is none.
* **Rules and fees are dated.** Ask for another day with `as_of`: a past day explains an older listing or charge, and a future day shows changes Etsy has announced for that day. Alura's record starts on `recorded_from` (2025-10-22). An earlier day still gets an answer, with a `before_recorded_history` notice, because Etsy may have changed a value then without Alura knowing.
* **Fees depend on where the seller is.** Payment processing, the Regulatory Operating fee and VAT on fees differ by country. Without a country, `get_etsy_fees` returns only the fees that are the same everywhere.
* **There's no estimate tool.** The `get_etsy_fees` description gives the assistant the formula to estimate what Etsy takes from an order.
* **Updates cite Etsy too.** Every update cites the Etsy pages it comes from: Etsy's news, help center, investor relations, blog or staff posts on the community forums. Ask the assistant to link them.
* **Dates and status.** `announced` means Etsy has said it will happen but it isn't in effect yet. `effective_at` is null when Etsy gave no day.
* **Countries.** An update with no countries applies to sellers everywhere. A country filter includes those.

## Tools

### `get_listing_rules`

**Get Etsy listing rules.** Get Etsy's limits for a listing, so a draft is one Etsy accepts: title length, tag count and length, photos, videos, variations, quantity, price, materials, custom options, digital files, shop sections and more, each with its unit, the listings it covers (`applies_to`) and the Etsy pages that state it. A null `value` means Etsy doesn't state that limit (see `notices`); never read it as 0. Pass `as_of` (YYYY-MM-DD) for the rules on another day: a past day explains an older listing, a future day shows changes Etsy has announced. Use it before drafting or checking a listing, or when a seller asks what Etsy allows.

* **Cost of `get_listing_rules`:** Free (0 API credits).
* **Behavior:** Read-only: changes nothing. Works on Alura's own data only.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/etsy/listing-rules`](https://docs.alura.io/api-reference/etsy/listingrules/get).

| Argument | Type | Required | Description |
| - | - | - | - |
| `as_of` | string | No | The day to answer for (YYYY-MM-DD, UTC). Default: today. A future day includes changes Etsy has announced for that day. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

### `get_etsy_fees`

**Get Etsy fees.** Get Etsy's fee schedule for a seller country on a date: every fee with its rate or amount, what it is charged on, who it is for, its dates and its Etsy sources. Pass `seller_country` (ISO code such as FR, where the seller's bank account is); without it you get only the fees that are the same everywhere, and `requires_seller_country` names the rest. Pass `as_of` (YYYY-MM-DD) for another day, including announced future changes. A fee that is null with a `fee_unknown` notice is unknown: say so, never treat it as 0. Use it when the user asks what Etsy charges or takes from a sale, or how a fee changed or will change. To estimate what Etsy takes from one order (there is no estimate tool), read the rows for the seller country and order date, and let T = item price + shipping + gift wrap in the listing currency. Add: `transaction` (`rate`% of T); `regulatory_operating` (`rate`% of T; 0 outside its countries); `payment_processing` (`rate`% of the order total including any sales tax or VAT the buyer pays, plus `amount` in `currency`, the seller country's currency; pick the row whose `audience` fits the order: `domestic` (Canada: `domestic_and_us`), `international` or `all`); `offsite_ads` only for an order from an Offsite Ad (the `under_threshold` or `over_threshold` row by the shop's sales, `rate`% of T, at most `max_amount`); `currency_conversion` (`rate`% of the sale) when the listing currency differs from the payment account currency; the `listing` fee `amount` (and `listing.multi_quantity` per extra unit sold); VAT or sales tax on these fees where a `vat_on_seller_fees` or `sales_tax_on_seller_fees` row applies (its `basis` and `note` say on what; a null rate is unknown: say so, never assume 0). Subtract `share_and_save_refund` (`rate`% of T) for an order from the seller's own Share & Save link. Convert every amount in another currency (USD caps and listing fees, the processing fee's fixed part) to one currency at the market rate before adding; Etsy converts its USD fees at the market rate too.

* **Cost of `get_etsy_fees`:** Free (0 API credits).
* **Behavior:** Read-only: changes nothing. Works on Alura's own data only.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/etsy/fees`](https://docs.alura.io/api-reference/etsy/fees/get).

| Argument | Type | Required | Description |
| - | - | - | - |
| `seller_country` | string | No | Where the seller is based, ISO 3166-1 alpha-2 such as "FR" or "US" (GB for the United Kingdom). |
| `as_of` | string | No | The day to answer for, YYYY-MM-DD. Default: today (UTC). |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "seller_country": "FR"
}
```

### `get_etsy_updates`

**Get Etsy updates.** What changed on Etsy for sellers: fee changes, listing rule changes, policies, announced search changes, programs, payments and shipping, newest first, plus Etsy News articles, written by Alura, that explain the biggest ones. An update has its dates (`announced_at`, `effective_at`), a status (`announced` means not in effect yet), the fee, listing rule, policy and program keys it changes (`affects`) and Etsy's own pages as `sources`; cite them when you tell the seller. `include`: `updates` (the default), `news` (articles: title, dek and url, no body) or `both` (one list, each entry's `object` says which). Filter with `since` (YYYY-MM-DD), `country` (the seller's country, ISO code such as GB; what applies everywhere is included) and `kind` (an article by its topics); `status` filters updates only. Pass an entry's `id` for the whole update or article (an article in markdown, with its corrections). Use `next_cursor` as `cursor` for older entries. Use it when the seller asks what changed on Etsy or what is coming, and before you quote a fee or rule that may have changed.

* **Cost of `get_etsy_updates`:** Free (0 API credits).
* **Behavior:** Read-only: changes nothing. Works on Alura's own data only.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/etsy/updates`](https://docs.alura.io/api-reference/etsy/updates/list), [`GET /v1/etsy/updates/{id}`](https://docs.alura.io/api-reference/etsy/updates/get), [`GET /v1/etsy/news`](https://docs.alura.io/api-reference/etsy/news/list), [`GET /v1/etsy/news/{slug}`](https://docs.alura.io/api-reference/etsy/news/get), [`GET /v1/etsy/feed`](https://docs.alura.io/api-reference/etsy/feed/list).

| Argument | Type | Required | Description |
| - | - | - | - |
| `include` | `updates`, `news`, `both` | No | `updates` (the default), `news` for Etsy News articles, or `both` in one list. |
| `id` | string | No | An entry's id from an earlier result (an update's, or an article's), for that whole entry. |
| `since` | string | No | Only updates announced or taking effect, and articles dated or published, on or after this day, YYYY-MM-DD. |
| `kind` | `fees`, `listing_rules`, `policies`, `search`, `programs`, `payments`, `shipping` | No | Only updates of this kind, and articles with this topic. |
| `country` | string | No | The seller's country, ISO 3166-1 alpha-2 (for example GB). What applies to every country is included. |
| `status` | `announced`, `in_effect`, `withdrawn` | No | Only `announced` (not in effect yet), `in_effect` or `withdrawn` updates (not for `include: news`). |
| `cursor` | string | No | next\_cursor from the previous page of the same arguments. |
| `limit` | integer | No | How many entries per page, at most 10 (the default). |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "since": "2026-09-01",
  "country": "GB"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.