Etsy Shop API

openapi: 3.0.2
info:
  title: Etsy Open API v3 BuyerTaxonomy Shop 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
paths:
  /v3/application/shops/{shop_id}:
    get:
      operationId: getShop
      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 the shop identified by a specific shop ID.'
      tags:
      - Shop
      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 single Shop
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shop'
              examples:
                GetShop200Example:
                  summary: Default getShop 200 response
                  x-microcks-default: true
                  value:
                    shop_id: 123456
                    user_id: 456789
                    shop_name: HandmadeCrafts
                    create_date: 1
                    created_timestamp: 1758153645
                    title: Handmade Ceramic Mug — Stoneware
                    announcement: example string
                    currency_code: USD
                    is_vacation: true
                    vacation_message: Thanks for your order! Shipping out tomorrow.
                    sale_message: Thanks for your order! Shipping out tomorrow.
                    digital_sale_message: Thanks for your order! Shipping out tomorrow.
                    update_date: 1
                    updated_timestamp: 1758153645
                    listing_active_count: 1
                    digital_listing_count: 1
                    login_name: handmade_seller
                    accepts_custom_requests: true
                    policy_welcome: example string
                    policy_payment: example string
                    policy_shipping: example string
                    policy_refunds: example string
                    policy_additional: example string
                    policy_seller_info: example string
                    policy_update_date: 1
                    policy_has_private_receipt_info: true
                    has_unstructured_policies: true
                    policy_privacy: example string
                    vacation_autoreply: example string
                    url: https://www.etsy.com/listing/123456789
                    image_url_760x100: https://www.etsy.com/listing/123456789
                    num_favorers: 1
                    languages:
                    - example string
                    icon_url_fullxfull: https://www.etsy.com/listing/123456789
                    is_using_structured_policies: true
                    has_onboarded_structured_policies: true
                    include_dispute_form_link: true
                    is_direct_checkout_onboarded: true
                    is_etsy_payments_onboarded: true
                    is_calculated_eligible: true
                    is_opted_in_to_buyer_promise: true
                    is_shop_us_based: true
                    transaction_sold_count: 1
                    shipping_from_country_iso: US
                    shop_location_country_iso: US
                    review_count: 1
                    review_average: 1.0
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShop404Example:
                  summary: Default getShop 404 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:
                GetShop400Example:
                  summary: Default getShop 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:
                GetShop500Example:
                  summary: Default getShop 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Shop
    put:
      operationId: updateShop
      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 a shop. Assumes that all string parameters are provided in the shop''s primary language. Please note that the policy_additional field should only be set for shops located in the EU. Passing a value for this field for shops outside of the EU, will result in an error.'
      tags:
      - Shop
      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
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: A brief heading string for the shop's main page.
                announcement:
                  type: string
                  description: An announcement string to buyers that displays on the shop's homepage.
                sale_message:
                  type: string
                  description: A message string sent to users who complete a purchase from this shop.
                digital_sale_message:
                  type: string
                  description: A message string sent to users who purchase a digital item from this shop.
                policy_additional:
                  type: string
                  description: The shop's additional policies string (may be blank).
            examples:
              UpdateShopRequestExample:
                summary: Default updateShop request
                x-microcks-default: true
                value:
                  title: example string
                  announcement: example string
                  sale_message: example string
                  digital_sale_message: example string
                  policy_additional: example string
      responses:
        '200':
          description: A single Shop.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shop'
              examples:
                UpdateShop200Example:
                  summary: Default updateShop 200 response
                  x-microcks-default: true
                  value:
                    shop_id: 123456
                    user_id: 456789
                    shop_name: HandmadeCrafts
                    create_date: 1
                    created_timestamp: 1758153645
                    title: Handmade Ceramic Mug — Stoneware
                    announcement: example string
                    currency_code: USD
                    is_vacation: true
                    vacation_message: Thanks for your order! Shipping out tomorrow.
                    sale_message: Thanks for your order! Shipping out tomorrow.
                    digital_sale_message: Thanks for your order! Shipping out tomorrow.
                    update_date: 1
                    updated_timestamp: 1758153645
                    listing_active_count: 1
                    digital_listing_count: 1
                    login_name: handmade_seller
                    accepts_custom_requests: true
                    policy_welcome: example string
                    policy_payment: example string
                    policy_shipping: example string
                    policy_refunds: example string
                    policy_additional: example string
                    policy_seller_info: example string
                    policy_update_date: 1
                    policy_has_private_receipt_info: true
                    has_unstructured_policies: true
                    policy_privacy: example string
                    vacation_autoreply: example string
                    url: https://www.etsy.com/listing/123456789
                    image_url_760x100: https://www.etsy.com/listing/123456789
                    num_favorers: 1
                    languages:
                    - example string
                    icon_url_fullxfull: https://www.etsy.com/listing/123456789
                    is_using_structured_policies: true
                    has_onboarded_structured_policies: true
                    include_dispute_form_link: true
                    is_direct_checkout_onboarded: true
                    is_etsy_payments_onboarded: true
                    is_calculated_eligible: true
                    is_opted_in_to_buyer_promise: true
                    is_shop_us_based: true
                    transaction_sold_count: 1
                    shipping_from_country_iso: US
                    shop_location_country_iso: US
                    review_count: 1
                    review_average: 1.0
        '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:
                UpdateShop400Example:
                  summary: Default updateShop 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '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:
                UpdateShop403Example:
                  summary: Default updateShop 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                UpdateShop404Example:
                  summary: Default updateShop 404 response
                  x-microcks-default: true
                  value:
                    error: example string
        '401':
          description: The request lacks valid authentication credentials. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                UpdateShop401Example:
                  summary: Default updateShop 401 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:
                UpdateShop500Example:
                  summary: Default updateShop 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - shops_r
        - shops_w
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Update Shop
  /v3/application/users/{user_id}/shops:
    get:
      operationId: getShopByOwnerUserId
      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 the shop identified by the shop owner''s user ID.'
      tags:
      - Shop
      parameters:
      - name: user_id
        in: path
        description: The numeric user ID of the [user](/documentation/reference#tag/User) who owns this shop.
        required: true
        schema:
          type: integer
          description: The numeric user ID of the [user](/documentation/reference#tag/User) who owns this shop.
          format: int64
          minimum: 1
        example: 456789
      responses:
        '200':
          description: A single Shop
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shop'
              examples:
                GetShopByOwnerUserId200Example:
                  summary: Default getShopByOwnerUserId 200 response
                  x-microcks-default: true
                  value:
                    shop_id: 123456
                    user_id: 456789
                    shop_name: HandmadeCrafts
                    create_date: 1
                    created_timestamp: 1758153645
                    title: Handmade Ceramic Mug — Stoneware
                    announcement: example string
                    currency_code: USD
                    is_vacation: true
                    vacation_message: Thanks for your order! Shipping out tomorrow.
                    sale_message: Thanks for your order! Shipping out tomorrow.
                    digital_sale_message: Thanks for your order! Shipping out tomorrow.
                    update_date: 1
                    updated_timestamp: 1758153645
                    listing_active_count: 1
                    digital_listing_count: 1
                    login_name: handmade_seller
                    accepts_custom_requests: true
                    policy_welcome: example string
                    policy_payment: example string
                    policy_shipping: example string
                    policy_refunds: example string
                    policy_additional: example string
                    policy_seller_info: example string
                    policy_update_date: 1
                    policy_has_private_receipt_info: true
                    has_unstructured_policies: true
                    policy_privacy: example string
                    vacation_autoreply: example string
                    url: https://www.etsy.com/listing/123456789
                    image_url_760x100: https://www.etsy.com/listing/123456789
                    num_favorers: 1
                    languages:
                    - example string
                    icon_url_fullxfull: https://www.etsy.com/listing/123456789
                    is_using_structured_policies: true
                    has_onboarded_structured_policies: true
                    include_dispute_form_link: true
                    is_direct_checkout_onboarded: true
                    is_etsy_payments_onboarded: true
                    is_calculated_eligible: true
                    is_opted_in_to_buyer_promise: true
                    is_shop_us_based: true
                    transaction_sold_count: 1
                    shipping_from_country_iso: US
                    shop_location_country_iso: US
                    review_count: 1
                    review_average: 1.0
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetShopByOwnerUserId404Example:
                  summary: Default getShopByOwnerUserId 404 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:
                GetShopByOwnerUserId400Example:
                  summary: Default getShopByOwnerUserId 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '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:
                GetShopByOwnerUserId403Example:
                  summary: Default getShopByOwnerUserId 403 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:
                GetShopByOwnerUserId500Example:
                  summary: Default getShopByOwnerUserId 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Shop by Owner User Id
  /v3/application/shops:
    get:
      operationId: findShops
      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>


        Open API V3 endpoint for searching shops by name. Note: We make every effort to ensure that frozen or removed shops are not included in the search results. However, rarely, due to timing issues, they may appear.'
      tags:
      - Shop
      parameters:
      - name: shop_name
        in: query
        description: The shop's name string.
        required: true
        schema:
          type: string
          description: The shop's name string.
        example: HandmadeCrafts
      - name: limit
        in: query
        description: The maximum number of results to return.
        required: false
        schema:
          type: integer
          description: The maximum number of results to return.
          minimum: 1
          maximum: 100
          default: 25
        example: 25
      - name: offset
        in: query
        description: The number of records to skip before selecting the first result.
        required: false
        schema:
          type: integer
          description: The number of records to skip before selecting the first result.
          minimum: 0
          default: 0
        example: 0
      responses:
        '200':
          description: A list of Shops
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Shops'
              examples:
                FindShops200Example:
                  summary: Default findShops 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                FindShops500Example:
                  summary: Default findShops 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Find Shops
components:
  schemas:
    ErrorSchema:
      type: object
      x-resource-id: ErrorSchema
      required:
      - error
      properties:
        error:
          type: string
          example: example string
    Shop:
      type: object
      x-resource-id: Shop
      description: A shop created by an Etsy user.
      properties:
        shop_id:
          type: integer
          description: The unique positive non-zero numeric ID for an Etsy Shop.
          format: int64
          minimum: 1
          example: 123456
        user_id:
          type: integer
          description: The numeric user ID of the [user](/documentation/reference#tag/User) who owns this shop.
          format: int64
          minimum: 1
          example: 456789
        shop_name:
          type: string
          description: The shop's name string.
          example: HandmadeCrafts
        create_date:
          type: integer
          description: The date and time this shop was created, in epoch seconds.
          minimum: 0
          example: 1
        created_timestamp:
          type: integer
          description: The date and time this shop was created, in epoch seconds.
          minimum: 0
          example: 1758153645
        title:
          type: string
          description: A brief heading string for the shop's main page.
          nullable: true
          example: Handmade Ceramic Mug — Stoneware
        announcement:
          type: string
          description: An announcement string to buyers that displays on the shop's homepage.
          nullable: true
          example: example string
        currency_code:
          type: string
          description: The ISO (alphabetic) code for the shop's currency. The shop displays all prices in this currency by default.
          example: USD
        is_vacation:
          type: boolean
          description: When true, this shop is not accepting purchases.
          example: true
        vacation_message:
          type: string
          description: The shop's message string displayed when `is_vacation` is true.
          nullable: true
          example: Thanks for your order! Shipping out tomorrow.
        sale_message:
          type: string
          description: A message string sent to users who complete a purchase from this shop.
          nullable: true
          example: Thanks for your order! Shipping out tomorrow.
        digital_sale_message:
          type: string
          description: A message string sent to users who purchase a digital item from this shop.
          nullable: true
          example: Thanks for your order! Shipping out tomorrow.
        update_date:
          type: integer
          description: The date and time of the last update to the shop, in epoch seconds.
          minimum: 0
          example: 1
        updated_timestamp:
          type: integer
          description: The date and time of the last update to the shop, in epoch seconds.
          minimum: 0
          example: 1758153645
        listing_active_count:
          type: integer
          description: The number of active listings in the shop.
          minimum: 0
          example: 1
        digital_listing_count:
          type: integer
          description: The number of digital listings in the shop.
          minimum: 0
          example: 1
        login_name:
          type: string
          description: The shop owner's login name string.
          example: handmade_seller
        accepts_custom_requests:
          type: boolean
          description: When true, the shop accepts customization requests.
          example: true
        policy_welcome:
          type: string
          description: The shop's policy welcome string (may be blank).
          nullable: true
          example: example string
        policy_payment:
          type: string
          description: The shop's payment policy string (may be blank).
          nullable: true
          example: example string
        policy_shipping:
          type: string
          description: The shop's shipping policy string (may be blank).
          nullable: true
          example: example string
        policy_refunds:
          type: string
          description: The shop's refund policy string (may be blank).
          nullable: true
          example: example string
        policy_additional:
          type: string
          description: The shop's additional policies string (may be blank).
          nullable: true
          example: example string
        policy_seller_info:
          type: string
          description: The shop's seller information string (may be blank).
          nullable: true
          example: example string
        policy_update_date:
          type: integer
          description: The date and time of the last update to the shop's policies, in epoch seconds.
          minimum: 0
          example: 1
        policy_has_private_receipt_info:
          type: boolean
          description: When true, EU receipts display private info.
          example: true
        has_unstructured_policies:
          type: boolean
          description: When true, the shop displays additional unstructured policy fields.
          example: true
        policy_privacy:
          type: string
          description: The shop's privacy policy string (may be blank).
          nullable: true
          example: example string
        vacation_autoreply:
          type: string
          description: The shop's automatic reply string displayed in new conversations when `is_vacation` is true.
          nullable: true
          example: example string
        url:
          type: string
          description: The URL string for this shop.
          example: https://www.etsy.com/listing/123456789
        image_url_760x100:
          type: string
          description: The URL string for this shop's banner image.
          nullable: true
          example: https://www.etsy.com/listing/123456789
        num_favorers:
          type: integer
          description: The number of users who marked this shop a favorite.
          minimum: 0
          example: 1
        languages:
          type: array
          description: A list of language strings for the shop's enrolled languages where the default shop language is the first element in the array.
          items:
            type: string
        icon_url_fullxfull:
          type: string
          description: The URL string for this shop's icon image.
          nullable: true
          example: https://www.etsy.com/listing/123456789
        is_using_structured_policies:
          type: boolean
          description: When true, the shop accepted using structured policies.
          example: true
        has_onboarded_structured_policies:
          type: boolean
          description: When true, the shop accepted OR declined after viewing structured policies onboarding.
          example: true
        include_dispute_form_link:
          type: boolean
          description: When true, this shop's policies include a link to an EU online dispute form.
          example: true
        is_direct_checkout_onboarded:
          type: boolean
          description: '(**DEPRECATED: Replaced by _is_etsy_payments_onboarded_.) When true, the shop has onboarded onto Etsy Payments.'
          example: true
        is_etsy_payments_onboarded:
          type: boolean
          description: When true, the shop has onboarded onto Etsy Payments.
          example: true
        is_calculated_eligible:
          type: boolean
          description: When true, the shop is eligible for calculated shipping profiles. (Only available in the US and Canada)
          example: true
        is_opted_in_to_buyer_promise:
          type: boolean
          description: When true, the shop opted in to buyer promise.
          example: true
        is_shop_us_based:
          type: boolean
          description: When true, the shop is based in the US.
          example: true
        transaction_sold_count:
          type: integer
          description: The total number of sales ([transactions](/documentation/reference#tag/Shop-Receipt-Transactions)) for this shop.
          minimum: 0
          example: 1
        shipping_from_country_iso:
          type: string
          description: The country ISO the shop is shipping from.
          format: ISO 3166-1 alpha-2
          nullable: true
          example: US
        shop_location_country_iso:
          type: string
          description: The country ISO where the shop is located.
          format: ISO 3166-1 alpha-2
          nullable: true
          example: US
        review_count:
          type: integer
          description: Number of reviews of shop listings in the past year.
          nullable: true
          example: 1
        review_average:
          type: number
          description: Average rating based on reviews of shop listings in the past year.
          format: float
          nullable: true
          example: 1.0
    Shops:
      type: object
      x-resource-id: Shops
      description: A set of Shop records.
      properties:
        count:
          type: integer
          description: The total number of Shops
          minimum: 0
          example: 1
        results:
          type: array
          description: The Shop resources.
          items:
            description: The Shop resources.
            oneOf:
          

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/etsy/refs/heads/main/openapi/etsy-shop-api-openapi.yml