openapi: 3.0.2
info:
  title: Etsy Open API v3 BuyerTaxonomy Shop HolidayPreferences API
  description: <div class="wt-text-body-01"><p class="wt-pt-xs-2 wt-pb-xs-2">Etsy's Open API provides a simple RESTful interface for various Etsy.com features.</p><p class="wt-pb-xs-2">If you'd like to report an issue or provide feedback on the API design, <a target="_blank" class="wt-text-link wt-p-xs-0" href="https://github.com/etsy/open-api/discussions">please add an issue in Github</a>.</p></div>&copy; 2021-2026 Etsy, Inc. All Rights Reserved. Use of this code is subject to Etsy's <a class='wt-text-link wt-p-xs-0' target='_blank' href='https://www.etsy.com/legal/api'>API Developer Terms of Use</a>.
  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: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        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: '<div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><span class="wt-badge wt-badge--notificationPrimary wt-bg-slime-tint wt-mr-xs-2">General Release</span><a class="wt-text-link" href="https://github.com/etsy/open-api/discussions" target="_blank" rel="noopener noreferrer">Report bug</a></div><div class="wt-display-flex-xs wt-align-items-center wt-mt-xs-2 wt-mb-xs-3"><p class="wt-text-body-01 banner-text">This endpoint is ready for production use.</p></div>


        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:
    ErrorSchema:
      type: object
      x-resource-id: ErrorSchema
      required:
      - error
      properties:
        error:
          type: string
          example: example string
    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
  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