Etsy

Etsy Shop HolidayPreferences API

The Shop HolidayPreferences API from Etsy — 2 operation(s) for shop holidaypreferences.

Documentation GitHub OpenAPI

Operations 2

GET /v3/application/shops/{shop_id}/holiday-preferences Etsy Get Holiday Preferences #

PUT /v3/application/shops/{shop_id}/holiday-preferences/{holiday_id} Etsy Update Holiday Preferences #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/etsy-shop-holidaypreferences-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Etsy Open API v3 Shop HolidayPreferences API
  description: 'Etsy''s Open API provides a simple RESTful interface for various Etsy.com features.


    If you''d like to report an issue or provide feedback on the API design, please add an issue in Github.


    © 2021-2026 Etsy, Inc. All Rights Reserved. Use of this code is subject to Etsy''s API Developer Terms of Use.'
  termsOfService: https://www.etsy.com/legal/api
  contact:
    email: developers@etsy.com
  version: 3.0.0
  x-generated-from: https://www.etsy.com/openapi/generated/oas/3.0.0.json
  x-last-validated: '2026-05-30'
servers:
- url: https://openapi.etsy.com
  description: Etsy Open API v3 base URL (per Etsy developer documentation; live calls also resolve at https://api.etsy.com/v3/application).
security:
- api_key: []
tags:
- name: Shop HolidayPreferences
paths:
  /v3/application/shops/{shop_id}/holiday-preferences:
    get:
      operationId: getHolidayPreferences
      description: 'General ReleaseReport bug


        This endpoint is ready for production use.


        Retrieves a list of holidays that are available to a shop to set a preference for. Currently only supported in the US and CA'
      tags:
      - Shop HolidayPreferences
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      responses:
        '200':
          description: A list of holiday preferences
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShopHolidayPreference'
              examples:
                GetHolidayPreferences200Example:
                  summary: Default getHolidayPreferences 200 response
                  x-microcks-default: true
                  value:
                  - shop_id: 123456
                    holiday_id: 1
                    country_iso: US
                    is_working: true
                    holiday_name: Handmade Ceramic Mug
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetHolidayPreferences403Example:
                  summary: Default getHolidayPreferences 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetHolidayPreferences400Example:
                  summary: Default getHolidayPreferences 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetHolidayPreferences500Example:
                  summary: Default getHolidayPreferences 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - shops_r
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Holiday Preferences
  /v3/application/shops/{shop_id}/holiday-preferences/{holiday_id}:
    put:
      operationId: updateHolidayPreferences
      description: 'General ReleaseReport bug


        This endpoint is ready for production use.


        Updates the preference for whether the seller will process orders or not on the holiday. Currently only supported in the US and CA'
      tags:
      - Shop HolidayPreferences
      parameters:
      - name: shop_id
        in: path
        description: The unique positive non-zero numeric ID for an Etsy Shop.
        required: true
        schema:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
        example: 123456
      - name: holiday_id
        in: path
        description: The unique id that maps to the holiday a country observes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#country-holidays) for more info
        required: true
        schema:
          type: integer
          description: The unique id that maps to the holiday a country observes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#country-holidays) for more info
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          - 7
          - 8
          - 9
          - 10
          - 11
          - 12
          - 13
          - 14
          - 15
          - 16
          - 17
          - 18
          - 19
          - 20
          - 21
          - 22
          - 23
          - 24
          - 25
          - 26
          - 27
          - 28
          - 29
          - 30
          - 31
          - 32
          - 33
          - 34
          - 35
          - 36
          - 37
          - 38
          - 39
          - 40
          - 41
          - 42
          - 43
          - 44
          - 45
          - 46
          - 47
          - 48
          - 49
          - 50
          - 51
          - 52
          - 53
          - 54
          - 55
          - 56
          - 57
          - 58
          - 59
          - 60
          - 61
          - 62
          - 63
          - 64
          - 65
          - 66
          - 67
          - 68
          - 69
          - 70
          - 71
          - 72
          - 73
          - 74
          - 75
          - 76
          - 77
          - 78
          - 79
          - 80
          - 81
          - 82
          - 83
          - 84
          - 85
          - 86
          - 87
          - 88
          - 89
          - 90
          - 91
          - 92
          - 93
          - 94
          - 95
          - 96
          - 97
          - 98
          - 99
          - 100
          - 101
          - 102
          - 103
          - 104
          - 105
        example: 1
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - is_working
              properties:
                is_working:
                  type: boolean
                  description: A boolean value for whether the shop will process orders on a particular holiday.
            examples:
              UpdateHolidayPreferencesRequestExample:
                summary: Default updateHolidayPreferences request
                x-microcks-default: true
                value:
                  is_working: true
      responses:
        '200':
          description: The updated holiday preferences
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShopHolidayPreference'
              examples:
                UpdateHolidayPreferences200Example:
                  summary: Default updateHolidayPreferences 200 response
                  x-microcks-default: true
                  value:
                    shop_id: 123456
                    holiday_id: 1
                    country_iso: US
                    is_working: true
                    holiday_name: Handmade Ceramic Mug
        '403':
          description: The request attempted to perform an operation it is not allowed to. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                UpdateHolidayPreferences403Example:
                  summary: Default updateHolidayPreferences 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '400':
          description: There was a problem with the request data. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                UpdateHolidayPreferences400Example:
                  summary: Default updateHolidayPreferences 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                UpdateHolidayPreferences500Example:
                  summary: Default updateHolidayPreferences 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - shops_w
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Update Holiday Preferences
components:
  schemas:
    ShopHolidayPreference:
      type: object
      x-resource-id: ShopHolidayPreference
      description: Represents a shop's holiday preference
      properties:
        shop_id:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
          example: 123456
        holiday_id:
          type: integer
          description: The unique id that maps to the holiday a country observes. See the [Fulfillment Tutorial docs](https://developer.etsy.com/documentation/tutorials/fulfillment/#country-holidays) for more info
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          - 6
          - 7
          - 8
          - 9
          - 10
          - 11
          - 12
          - 13
          - 14
          - 15
          - 16
          - 17
          - 18
          - 19
          - 20
          - 21
          - 22
          - 23
          - 24
          - 25
          - 26
          - 27
          - 28
          - 29
          - 30
          - 31
          - 32
          - 33
          - 34
          - 35
          - 36
          - 37
          - 38
          - 39
          - 40
          - 41
          - 42
          - 43
          - 44
          - 45
          - 46
          - 47
          - 48
          - 49
          - 50
          - 51
          - 52
          - 53
          - 54
          - 55
          - 56
          - 57
          - 58
          - 59
          - 60
          - 61
          - 62
          - 63
          - 64
          - 65
          - 66
          - 67
          - 68
          - 69
          - 70
          - 71
          - 72
          - 73
          - 74
          - 75
          - 76
          - 77
          - 78
          - 79
          - 80
          - 81
          - 82
          - 83
          - 84
          - 85
          - 86
          - 87
          - 88
          - 89
          - 90
          - 91
          - 92
          - 93
          - 94
          - 95
          - 96
          - 97
          - 98
          - 99
          - 100
          - 101
          - 102
          - 103
          - 104
          - 105
          example: 1
        country_iso:
          type: string
          description: The country ISO where the shop is located.
          format: ISO 3166-1 alpha-2
          example: US
        is_working:
          type: boolean
          description: A boolean value for whether the shop will process orders on a particular holiday.
          example: true
        holiday_name:
          type: string
          description: The name of the holiday that a country observes.
          example: Handmade Ceramic Mug
    ErrorSchema:
      type: object
      x-resource-id: ErrorSchema
      required:
      - error
      properties:
        error:
          type: string
          example: example string
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header
      description: Every request to a v3 API endpoint must include this data in the format `keystring:shared_secret`. Your keystring and shared secret are available on the [Your Apps](https://www.etsy.com/developers/your-apps) page.
    oauth2:
      type: oauth2
      description: Open API v3 supports authenticating via OAuth 2.0. More information about Etsy's specific implementation of OAuth2 can be found [here](/documentation/essentials/oauth2).
      flows:
        authorizationCode:
          authorizationUrl: https://www.etsy.com/oauth/connect
          tokenUrl: https://openapi.etsy.com/v3/public/oauth/token
          scopes:
            address_r: see billing and shipping addresses
            address_w: update billing and shipping addresses
            billing_r: see all billing statement data
            cart_r: read shopping carts
            cart_w: add/remove from shopping carts
            email_r: read a user profile
            favorites_r: see private favorites
            favorites_w: add/remove favorites
            feedback_r: see purchase info in feedback
            listings_d: delete listings
            listings_r: see all listings (including expired etc)
            listings_w: create/edit listings
            profile_r: see all profile data
            profile_w: update user profile, avatar, etc
            recommend_r: see recommended listings
            recommend_w: accept/reject recommended listings
            shops_r: see private shop info
            shops_w: update shop
            transactions_r: see all checkout/payment data
            transactions_w: update receipts
x-tagGroups:
- name: Listing Management
  tags:
  - BuyerTaxonomy
  - SellerTaxonomy
  - ShopListing
  - ShopListing File
  - ShopListing Image
  - ShopListing Inventory
  - ShopListing Offering
  - ShopListing Personalization
  - ShopListing Product
  - ShopListing Translation
  - ShopListing VariationImage
  - ShopListing Video
- name: Other
  tags:
  - Other
- name: Payment Management
  tags:
  - Ledger Entry
  - Payment
- name: Receipt Management
  tags:
  - Shop Receipt
  - Shop Receipt Transactions
- name: Review Management
  tags:
  - Review
- name: Shipping Management
  tags:
  - Shop HolidayPreferences
  - Shop ProcessingProfiles
  - Shop ShippingProfile
- name: Shop Management
  tags:
  - Shop
  - Shop ProductionPartner
  - Shop Section
- name: Shop Policy Management
  tags:
  - Shop Return Policy
- name: User Management
  tags:
  - User
  - UserAddress