> ## 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 news

> List Etsy News: articles Alura writes for sellers, one per major Etsy change, each explaining what changed and citing Etsy's own pages. Newest story first.

**Cost:** Free.

```bash
curl -G "https://api.alura.io/v1/etsy/news" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  --data-urlencode "kind=fees"
```

Each article explains one or more Etsy updates in plain words for sellers. The list gives each article's title, one-sentence `dek`, `topics` and the `update_ids` it explains. [Get article](https://docs.alura.io/api-reference/etsy/news/get.md) returns the whole story.

| 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 articles

| To find | Use |
| - | - |
| Recent articles | `since`, such as `2026-10-01`: the story date (`published_at`) or the day Alura published it (`created_at`) is on or after the day. A story added later about an older change shows up when it's published. |
| Articles on one topic | `kind`: `fees`, `listing_rules`, `policies`, `search`, `programs`, `payments` or `shipping` |
| Articles for sellers in one country | `country`, such as `GB`: articles about updates for that country, and about updates that apply everywhere |

Pages hold 10 articles, the most `limit` allows. See [Pagination](https://docs.alura.io/api-reference/introduction.md#pagination).


## OpenAPI

````yaml /openapi.json get /v1/etsy/news
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/news:
    get:
      summary: List news
      description: >-
        Etsy News, written by Alura: one story per major Etsy change for sellers
        (fees, listing rules, policies, programs, payments, shipping), written
        for sellers and citing Etsy's own pages, newest story first. Each
        article in the list has its title, one-sentence dek, topics and the Etsy
        updates it explains; `GET /v1/etsy/news/{slug}` returns the whole story
        in markdown with its sources and corrections. `since` keeps articles
        whose story date or publishing day is on or after a day (so a backfilled
        story shows up when it is published); `kind` keeps those with that
        topic; `country` keeps articles about updates for sellers in that
        country, including updates that apply everywhere. 10 per page. Free.


        Cost: free.
      operationId: etsy.news.list
      parameters:
        - name: since
          in: query
          required: false
          description: >-
            Only articles whose story date (`published_at`) or publishing day
            (`created_at`) is on or after this day, `YYYY-MM-DD`, so a
            backfilled story shows up when it is published.
          schema:
            description: >-
              Only articles whose story date (`published_at`) or publishing day
              (`created_at`) is on or after this day, `YYYY-MM-DD`, so a
              backfilled story shows up when it is published.
            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-10-01'
        - name: kind
          in: query
          required: false
          description: Only articles with this topic (an Etsy update kind).
          schema:
            description: Only articles with this topic (an Etsy update kind).
            type: string
            enum:
              - fees
              - listing_rules
              - policies
              - search
              - programs
              - payments
              - shipping
        - name: country
          in: query
          required: false
          description: >-
            Only articles about an update for sellers in this country (ISO
            3166-1 alpha-2, for example `GB`), including updates that apply
            everywhere.
          schema:
            description: >-
              Only articles about an update for sellers in this country (ISO
              3166-1 alpha-2, for example `GB`), including updates that apply
              everywhere.
            type: string
            pattern: ^[A-Za-z]{2}$
        - 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.news_article
                        id:
                          type: string
                          description: >-
                            The article ID: its slug, such as
                            `regulatory-operating-fee-june-2026` (`GET
                            /v1/etsy/news/{slug}`).
                        slug:
                          type: string
                          description: Its permanent address, the same as `id`.
                        title:
                          type: string
                          description: What changed, in one line.
                        dek:
                          type: string
                          description: 'One sentence: who is affected and from when.'
                        url:
                          description: >-
                            The article's page on alura.io
                            (`https://www.alura.io/news/{slug}`).
                          type:
                            - string
                            - 'null'
                        published_at:
                          type: string
                          description: >-
                            The story's date: the day Etsy announced the change
                            it covers, `YYYY-MM-DD`.
                        created_at:
                          type: string
                          description: >-
                            When Alura published the article (ISO 8601, UTC); a
                            backfilled story is published long after its date.
                        updated_at:
                          type: string
                          description: >-
                            When Alura last changed the article (ISO 8601, UTC);
                            a correction moves it.
                        topics:
                          minItems: 1
                          maxItems: 7
                          type: array
                          items:
                            type: string
                            enum:
                              - fees
                              - listing_rules
                              - policies
                              - search
                              - programs
                              - payments
                              - shipping
                          description: >-
                            The areas of selling on Etsy it covers, as Etsy
                            update kinds.
                        update_ids:
                          minItems: 1
                          maxItems: 20
                          type: array
                          items:
                            type: string
                          description: >-
                            The Etsy updates it explains (`GET
                            /v1/etsy/updates/{id}`), the main one first.
                        author:
                          type: string
                          description: The byline (`Alura`).
                      required:
                        - object
                        - id
                        - slug
                        - title
                        - dek
                        - url
                        - published_at
                        - created_at
                        - updated_at
                        - topics
                        - update_ids
                        - author
                      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.news_article
                    id: share-and-save-holiday-refund
                    slug: share-and-save-holiday-refund
                    title: >-
                      Share & Save refunds the full 6.5% transaction fee through
                      January 4, 2027
                    dek: >-
                      Sellers enrolled in Share & Save get the whole transaction
                      fee back on eligible orders from their own links from
                      October 20, 2026 through January 4, 2027.
                    url: https://www.alura.io/news/share-and-save-holiday-refund
                    published_at: '2026-10-20'
                    created_at: '2026-10-22T09:00:00.000Z'
                    updated_at: '2026-10-22T09:00:00.000Z'
                    topics:
                      - fees
                      - programs
                    update_ids:
                      - 2026-10-20-share-and-save-holiday-refund
                    author: Alura
                  - object: etsy.news_article
                    id: us-entry-type-13-postal
                    slug: us-entry-type-13-postal
                    title: >-
                      US requires Entry Type 13 customs filing for postal
                      parcels worth $2,500 or less from January 20, 2027
                    dek: >-
                      From January 20, 2027, sellers outside the US who post
                      orders to US buyers need shipment-level customs data on
                      each parcel, or it may be held or returned.
                    url: https://www.alura.io/news/us-entry-type-13-postal
                    published_at: '2026-10-19'
                    created_at: '2026-10-22T09:00:00.000Z'
                    updated_at: '2026-10-22T09:00:00.000Z'
                    topics:
                      - shipping
                      - policies
                    update_ids:
                      - 2026-10-19-us-entry-type-13
                    author: Alura
                  - object: etsy.news_article
                    id: regulatory-operating-fee-june-2026
                    slug: regulatory-operating-fee-june-2026
                    title: >-
                      Etsy changes the regulatory operating fee in 7 countries,
                      with France rising to 1.14%
                    dek: >-
                      Sellers based in France, Hungary, India, Italy, Spain,
                      Türkiye and the UK pay new rates from June 22, 2026, and
                      Canada's rate has fallen to 0.50% with no start date from
                      Etsy.
                    url: >-
                      https://www.alura.io/news/regulatory-operating-fee-june-2026
                    published_at: '2026-04-22'
                    created_at: '2026-10-22T09:00:00.000Z'
                    updated_at: '2026-10-22T09:00:00.000Z'
                    topics:
                      - fees
                    update_ids:
                      - 2026-06-22-regulatory-operating-fee-changes
                      - 2026-06-22-regulatory-operating-fee-canada-cut
                    author: Alura
                has_more: false
                next_cursor: null
                total:
                  value: 3
                  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/news?since=2026-10-01" \
              -H "Authorization: Bearer $ALURA_API_KEY"
        - lang: typescript
          label: TypeScript
          source: >-
            const res = await
            fetch('https://api.alura.io/v1/etsy/news?since=2026-10-01', {
              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/news?since=2026-10-01",
                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.