> ## 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. # List updates > List Etsy's changes that affect sellers, such as fees, listing rules and policies, newest first. Each is dated, says whether it's announced, in effect or withdrawn, and cites Etsy's pages. **Cost:** Free. ```bash curl -G "https://api.alura.io/v1/etsy/updates" \ -H "Authorization: Bearer $ALURA_API_KEY" \ --data-urlencode "since=2026-10-01" \ --data-urlencode "country=GB" ``` Updates are the structured record of what Etsy changed. Newest announced first. | Endpoint | What you get | Use it for | | - | - | - | | [List updates](https://docs.alura.io/api-reference/etsy/updates/list.md) | Etsy's changes as dated records: status, the fee and rule keys they change, Etsy's own pages | Code that tracks or reacts to changes | | [List news](https://docs.alura.io/api-reference/etsy/news/list.md) | Articles Alura writes for sellers, one per major change, each explaining one or more updates | Showing people what changed and what it means | | [List feed](https://docs.alura.io/api-reference/etsy/feed/list.md) | Updates and articles in one list, newest first | One timeline of both | ## Filter updates | To find | Use | | - | - | | Changes announced or taking effect on or after a day | `since`, such as `2026-10-01`. A change announced earlier that starts later is included. | | Changes in one area | `kind`: `fees`, `listing_rules`, `policies`, `search`, `programs`, `payments` or `shipping` | | Changes for sellers in one country | `country`, such as `GB`. Changes that apply everywhere are included. | | Upcoming, current or called-off changes | `status`: `announced`, `in_effect` or `withdrawn` | ## Read an update * `affects` names what the update changes. A `fee` key is a `key` of [Get fees](https://docs.alura.io/api-reference/etsy/fees/get.md), such as `regulatory_operating`. A `listing_rule` key is a key of [Get listing rules](https://docs.alura.io/api-reference/etsy/listingRules/get.md), such as `photos.max_count`. It's empty when the update changes nothing Alura tracks. * `effective_at` is `null` when Etsy gave no day. `countries` is `null` when the change applies everywhere. * `news_slug` names the [Etsy News article](https://docs.alura.io/api-reference/etsy/news/get.md) about it, when there is one. Pages hold 10 updates, the most `limit` allows. See [Pagination](https://docs.alura.io/api-reference/introduction.md#pagination). ## OpenAPI ````yaml /openapi.json get /v1/etsy/updates openapi: 3.1.0 info: title: Alura API version: 1.0.0 description: Etsy market research for scripts and AI assistants. servers: - url: https://api.alura.io security: - apiKey: [] paths: /v1/etsy/updates: get: summary: List updates description: >- Etsy's changes that affect sellers (fees, listing rules, policies, announced search changes, programs, payments and shipping), newest announced first. Each update is dated, says whether it is announced, in effect or withdrawn, names the fee and rule keys it changes, and cites Etsy's own pages. `since` keeps updates announced or taking effect on or after a day; `country` keeps those for sellers in that country, including the ones that apply everywhere. 10 per page. Free. Cost: free. operationId: etsy.updates.list parameters: - name: since in: query required: false description: >- Only updates announced on or after this day, or taking effect on or after it (so a change announced earlier that starts later is included), `YYYY-MM-DD`. schema: description: >- Only updates announced on or after this day, or taking effect on or after it (so a change announced earlier that starts later is included), `YYYY-MM-DD`. type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ example: '2026-09-01' - name: kind in: query required: false description: Only updates of this kind. schema: description: Only updates of this kind. type: string enum: - fees - listing_rules - policies - search - programs - payments - shipping - name: country in: query required: false description: >- Only updates that apply to sellers in this country (ISO 3166-1 alpha-2, for example `GB`), including those that apply everywhere. schema: description: >- Only updates that apply to sellers in this country (ISO 3166-1 alpha-2, for example `GB`), including those that apply everywhere. type: string pattern: ^[A-Za-z]{2}$ example: GB - name: status in: query required: false description: Only updates with this status. schema: description: Only updates with this status. type: string enum: - announced - in_effect - withdrawn - name: limit in: query required: false description: >- Page size: at most 10, the default. A larger whole number gets 10 rows and `limit_applied`. schema: type: integer minimum: 1 - name: cursor in: query required: false description: >- The `next_cursor` of the previous page. Bound to the query, the workspace and the key. schema: type: string - name: fields in: query required: false description: >- Comma-separated dotted paths to return; `id`, `object` and `as_of` always come back. schema: type: string responses: '200': description: OK headers: Request-Id: $ref: '#/components/headers/Request-Id' Alura-Credits-Cost: $ref: '#/components/headers/Alura-Credits-Cost' Alura-Credits-Remaining: $ref: '#/components/headers/Alura-Credits-Remaining' content: application/json: schema: type: object properties: object: type: string const: list data: type: array items: type: object properties: object: type: string const: etsy.update id: type: string description: >- The update ID, a slug such as `2026-10-19-us-entry-type-13`. kind: type: string enum: - fees - listing_rules - policies - search - programs - payments - shipping description: What area of selling on Etsy it changes. title: type: string description: What changed, in one line. summary: type: string description: >- The facts in at most two sentences: what, who and from when. status: type: string enum: - announced - in_effect - withdrawn description: >- `announced` (not in effect yet), `in_effect`, or `withdrawn` (Etsy called it off). announced_at: type: string description: The day Etsy announced it, `YYYY-MM-DD`. effective_at: description: >- The day it takes or took effect, `YYYY-MM-DD`; null when Etsy gave no day. type: - string - 'null' countries: anyOf: - maxItems: 60 type: array items: type: string - type: 'null' description: >- The seller countries it applies to (ISO 3166-1 alpha-2); null when it applies everywhere. affects: maxItems: 10 type: array items: type: object properties: type: type: string enum: - listing_rule - fee - policy - program description: >- What the update changes: a listing rule, a fee, a policy or a program. key: type: string description: >- Its key, for example `regulatory_operating` (a fee key of `GET /v1/etsy/fees`) or `photos.max_count` (a listing rule key). required: - type - key additionalProperties: false description: >- The listing rules, fees, policies and programs it changes; empty when it changes none Alura tracks. sources: minItems: 1 maxItems: 8 type: array items: type: object properties: url: type: string maxLength: 500 description: >- Etsy's page: etsy.com, or its help, investors, blog or community site; a later source may be a web.archive.org copy of one. title: type: string description: The page's title, as Etsy wrote it. publisher: type: string enum: - Etsy - ISO 4217 description: >- `Etsy` for Etsy-owned pages; `ISO 4217` for currency minor units, the one source that is not Etsy. published_at: anyOf: - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ - type: 'null' description: >- When the page was published or last edited (YYYY-MM-DD); null when it does not say. read_at: anyOf: - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ - type: 'null' description: >- When Alura read the page (YYYY-MM-DD); null when not recorded. required: - url - title - publisher - published_at - read_at additionalProperties: false description: >- Etsy's own pages the facts come from, the main one first. news_slug: description: >- The Etsy News article about it, when there is one (`GET /v1/etsy/news/{slug}`). type: - string - 'null' updated_at: type: string description: When Alura last changed this record (ISO 8601, UTC). required: - object - id - kind - title - summary - status - announced_at - effective_at - countries - affects - sources - news_slug - updated_at additionalProperties: false has_more: type: boolean next_cursor: type: - string - 'null' total: type: object properties: value: type: integer relation: type: string enum: - eq - gte required: - value - relation additionalProperties: false limit_applied: description: >- Present only when `limit` asked for more than 10: the page size used instead, 10. type: integer required: - object - data - has_more - next_cursor - total additionalProperties: false example: object: list data: - object: etsy.update id: 2026-10-20-share-and-save-holiday-refund kind: fees title: >- Share & Save refunds the full 6.5% transaction fee through January 4, 2027 summary: >- From October 20, 2026 through January 4, 2027, sellers enrolled in Share & Save get the full 6.5% transaction fee refunded on eligible orders that come through their Share & Save links, up from the usual 4%. The refund returns to 4% after January 4, 2027. status: in_effect announced_at: '2026-10-20' effective_at: '2026-10-20' countries: null affects: - type: fee key: share_and_save_refund - type: program key: share_and_save sources: - url: >- https://community.etsy.com/forum/announcements-290/topic/our-share-save-holiday-gift-to-you-190476/ title: Our Share & Save holiday gift to you publisher: Etsy published_at: '2026-10-20' read_at: null - url: https://help.etsy.com/hc/en-us/articles/16981332744087 title: How to Save on Etsy Fees with the Share & Save Program publisher: Etsy published_at: '2026-10-20' read_at: null news_slug: share-and-save-holiday-refund updated_at: '2026-10-22T09:00:00.000Z' - object: etsy.update id: 2026-10-19-us-entry-type-13 kind: shipping title: >- US requires electronic Entry Type 13 filing for postal parcels from January 20, 2027 summary: >- From January 20, 2027, international postal packages worth $2,500 USD or less entering the US must be filed electronically in US Customs' ACE system under Entry Type 13, with shipment-level data and any documents US agencies such as the FDA or CPSC require. Etsy says packages without the required customs information may be held or returned, and recommends connecting the shop to a free Zonos Verified Account. status: announced announced_at: '2026-10-19' effective_at: '2027-01-20' countries: null affects: [] sources: - url: >- https://community.etsy.com/forum/announcements-290/topic/new-us-customs-postal-entry-requirements-for-international-sellers-190423/ title: >- New US customs postal entry requirements for international sellers publisher: Etsy published_at: '2026-10-19' read_at: null news_slug: us-entry-type-13-postal updated_at: '2026-10-22T09:00:00.000Z' has_more: false next_cursor: null total: value: 2 relation: eq '400': $ref: '#/components/responses/Problem400' '401': $ref: '#/components/responses/Problem401' '402': $ref: '#/components/responses/Problem402' '403': $ref: '#/components/responses/Problem403' '404': $ref: '#/components/responses/Problem404' '405': $ref: '#/components/responses/Problem405' '429': $ref: '#/components/responses/Problem429' '500': $ref: '#/components/responses/Problem500' '503': $ref: '#/components/responses/Problem503' x-codeSamples: - lang: bash label: cURL source: >- curl "https://api.alura.io/v1/etsy/updates?since=2026-09-01&country=GB" \ -H "Authorization: Bearer $ALURA_API_KEY" - lang: typescript label: TypeScript source: >- const res = await fetch('https://api.alura.io/v1/etsy/updates?since=2026-09-01&country=GB', { headers: { Authorization: `Bearer ${process.env.ALURA_API_KEY}`, }, }); console.log(await res.json()); - lang: python label: Python source: |- import json import os import urllib.request request = urllib.request.Request( "https://api.alura.io/v1/etsy/updates?since=2026-09-01&country=GB", headers={ "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}", }, ) with urllib.request.urlopen(request) as response: print(json.load(response)) components: headers: Request-Id: description: '`req_` + ULID; quote it when reporting a problem.' schema: type: string Alura-Credits-Cost: description: API credits this call cost. schema: type: integer Alura-Credits-Remaining: description: >- API credits left in the workspace's monthly allowance, counting calls still in flight. Absent when it cannot be read right now. schema: type: integer responses: Problem400: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/invalid_request title: Invalid request status: 400 code: invalid_request detail: Invalid request suggestion: Fix the request as the detail says, then send it again. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem401: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/unauthorized title: Unauthorized status: 401 code: unauthorized detail: Unauthorized suggestion: 'Send a valid API key as `Authorization: Bearer alura_sk_...`.' retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem402: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_exhausted title: API credits exhausted status: 402 code: credits_exhausted detail: API credits exhausted suggestion: Upgrade the plan or wait for the monthly reset. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem403: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/plan_required title: Plan required status: 403 code: plan_required detail: Plan required suggestion: Upgrade the workspace plan to use this operation. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem404: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/not_found title: Not found status: 404 code: not_found detail: Not found suggestion: Check the ID, or search for it first. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem405: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/method_not_allowed title: Method not allowed status: 405 code: method_not_allowed detail: Method not allowed suggestion: Use one of the methods in the Allow header. retryable: false request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem429: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/rate_limited title: Rate limited status: 429 code: rate_limited detail: Rate limited suggestion: Wait for Retry-After, then retry. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem500: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/internal_error title: Internal error status: 500 code: internal_error detail: Internal error suggestion: Retry; if it keeps failing, report the request_id. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B Problem503: description: Error content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: type: https://docs.alura.io/errors/credits_unavailable title: API credits unavailable status: 503 code: credits_unavailable detail: API credits unavailable suggestion: Retry shortly. retryable: true request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B schemas: Problem: type: object description: RFC 9457 problem details. properties: type: type: string format: uri title: type: string status: type: integer code: type: string description: A code from the error catalog; new codes may be added. x-extensible-enum: - invalid_request - unknown_parameter - invalid_cursor - cursor_window_exceeded - invalid_reference - id_type_mismatch - invalid_keyword - shop_id_required - listing_not_publishable - sales_window_not_covered - unauthorized - credits_exhausted - plan_required - insufficient_scope - workspace_required - workspace_locked - your_shop_unavailable - writes_suspended - browser_refused - role_required - impersonation_refused - recent_sign_in_required - etsy_scope_required - etsy_partner_required - not_found - not_collected - not_found_on_etsy - shop_opted_out - method_not_allowed - conflict - key_limit_reached - reconnect_required - settings_not_fetched - listing_busy - settings_busy - shop_create_busy - idempotency_partial_unverifiable - listing_has_variations - changed_since - change_not_revertable - listing_in_ab_test - activation_skipped - idempotency_processing - confirmation_required - test_shop_active_cap - write_outcome_unknown - unprocessable - listing_removed_on_etsy - endpoint_removed - rate_limited - throttled - daily_credit_cap_exceeded - credits_reserved - fetch_limit_reached - write_rate_limited - sync_cooldown - shop_write_budget_exhausted - internal_error - write_misconfigured - upstream_unavailable - credits_unavailable - service_unavailable - fetch_unavailable - create_lock_unavailable - writes_paused - etsy_capacity - upstream_timeout detail: type: string suggestion: type: string retryable: type: boolean request_id: type: string upgrade_url: type: string format: uri description: 'credits_exhausted and plan_required: where to upgrade the plan.' credits_needed: type: integer description: 'API credit refusals: what the call needed.' credits_remaining: type: integer description: >- API credit refusals: what is left (of the month, or of the day for daily_credit_cap_exceeded). resets_at: type: string format: date-time description: >- credits_exhausted and daily_credit_cap_exceeded: when the limit resets. required: - type - title - status - code - detail - suggestion - retryable - request_id securitySchemes: apiKey: type: http scheme: bearer description: 'An API key: `Authorization: Bearer alura_sk_...`.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.