openapi: 3.0.2
info:
  title: Etsy Open API v3 BuyerTaxonomy ShopListing Image 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: ShopListing Image
paths:
  /v3/application/shops/{shop_id}/listings/{listing_id}/images/{listing_image_id}:
    delete:
      operationId: deleteListingImage
      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 to delete a listing image. A copy of the file remains on our servers, and so a deleted image may be re-associated with the listing without re-uploading the original image; see uploadListingImage.'
      tags:
      - ShopListing Image
      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: listing_id
        in: path
        description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
          format: int64
          minimum: 1
        example: 123456789
      - name: listing_image_id
        in: path
        description: The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
          format: int64
          minimum: 1
        example: 1
      responses:
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                DeleteListingImage404Example:
                  summary: Default deleteListingImage 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:
                DeleteListingImage400Example:
                  summary: Default deleteListingImage 400 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:
                DeleteListingImage401Example:
                  summary: Default deleteListingImage 401 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:
                DeleteListingImage403Example:
                  summary: Default deleteListingImage 403 response
                  x-microcks-default: true
                  value:
                    error: example string
        '204':
          description: The ListingImage resource was correctly deleted
        '500':
          description: The server encountered an internal error. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                DeleteListingImage500Example:
                  summary: Default deleteListingImage 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - listings_w
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Delete Listing Image
  /v3/application/listings/{listing_id}/images/{listing_image_id}:
    get:
      operationId: getListingImage
      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 references and metadata for a listing image with a specific image ID.'
      tags:
      - ShopListing Image
      parameters:
      - name: listing_id
        in: path
        description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
          format: int64
          minimum: 1
        example: 123456789
      - name: listing_image_id
        in: path
        description: The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
          format: int64
          minimum: 1
        example: 1
      responses:
        '200':
          description: A single ListingImage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingImage'
              examples:
                GetListingImage200Example:
                  summary: Default getListingImage 200 response
                  x-microcks-default: true
                  value:
                    listing_id: 123456789
                    listing_image_id: 1
                    hex_code: example string
                    red: 1
                    green: 1
                    blue: 1
                    hue: 1
                    saturation: 1
                    brightness: 1
                    is_black_and_white: true
                    creation_tsz: 1
                    created_timestamp: 1758153645
                    rank: 1
                    url_75x75: https://www.etsy.com/listing/123456789
                    url_170x135: https://www.etsy.com/listing/123456789
                    url_570xN: https://www.etsy.com/listing/123456789
                    url_fullxfull: https://www.etsy.com/listing/123456789
                    full_height: 1
                    full_width: 1
                    alt_text: 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:
                GetListingImage404Example:
                  summary: Default getListingImage 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:
                GetListingImage400Example:
                  summary: Default getListingImage 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:
                GetListingImage403Example:
                  summary: Default getListingImage 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:
                GetListingImage500Example:
                  summary: Default getListingImage 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Listing Image
  /v3/application/listings/{listing_id}/images:
    get:
      operationId: getListingImages
      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 all listing image resources for a listing with a specific listing ID.'
      tags:
      - ShopListing Image
      parameters:
      - name: listing_id
        in: path
        description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
          format: int64
          minimum: 1
        example: 123456789
      responses:
        '200':
          description: An array of ListingImage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingImages'
              examples:
                GetListingImages200Example:
                  summary: Default getListingImages 200 response
                  x-microcks-default: true
                  value:
                    count: 1
                    results:
                    - null
        '404':
          description: A resource could not be found. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                GetListingImages404Example:
                  summary: Default getListingImages 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:
                GetListingImages400Example:
                  summary: Default getListingImages 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:
                GetListingImages403Example:
                  summary: Default getListingImages 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:
                GetListingImages500Example:
                  summary: Default getListingImages 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Get Listing Images
  /v3/application/shops/{shop_id}/listings/{listing_id}/images:
    post:
      operationId: uploadListingImage
      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>


        Uploads or assigns an image to a listing identified by a shop ID with a listing ID. To upload a new image, set the image file as the value for the `image` parameter. You can assign a previously deleted image to a listing using the deleted image''s image ID in the `listing_image_id` parameter. When a request contains both `image` and `listing_image_id` parameter values, the endpoint uploads the image in the `image` parameter only. Note: When uploading a new image, data such as colors and size may return as null values due to asynchronous processing of the image. Use getListingImage endpoint to fetch these values.'
      tags:
      - ShopListing Image
      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: listing_id
        in: path
        description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
        required: true
        schema:
          type: integer
          description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
          format: int64
          minimum: 1
        example: 123456789
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  description: The file name string of a file to upload
                  format: binary
                  nullable: true
                listing_image_id:
                  type: integer
                  description: The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
                  format: int64
                  minimum: 1
                rank:
                  type: integer
                  description: The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.
                  minimum: 0
                  default: 1
                overwrite:
                  type: boolean
                  description: When true, this request replaces the existing image at a given rank.
                  default: false
                is_watermarked:
                  type: boolean
                  description: When true, indicates that the uploaded image has a watermark.
                  default: false
                alt_text:
                  type: string
                  description: Alt text for the listing image. Max length 500 characters.
                  default: ''
      responses:
        '201':
          description: A single ListingImage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingImage'
              examples:
                UploadListingImage201Example:
                  summary: Default uploadListingImage 201 response
                  x-microcks-default: true
                  value:
                    listing_id: 123456789
                    listing_image_id: 1
                    hex_code: example string
                    red: 1
                    green: 1
                    blue: 1
                    hue: 1
                    saturation: 1
                    brightness: 1
                    is_black_and_white: true
                    creation_tsz: 1
                    created_timestamp: 1758153645
                    rank: 1
                    url_75x75: https://www.etsy.com/listing/123456789
                    url_170x135: https://www.etsy.com/listing/123456789
                    url_570xN: https://www.etsy.com/listing/123456789
                    url_fullxfull: https://www.etsy.com/listing/123456789
                    full_height: 1
                    full_width: 1
                    alt_text: 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:
                UploadListingImage404Example:
                  summary: Default uploadListingImage 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:
                UploadListingImage400Example:
                  summary: Default uploadListingImage 400 response
                  x-microcks-default: true
                  value:
                    error: example string
        '409':
          description: There was a request conflict with the current state of the target resource. See the error message for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
              examples:
                UploadListingImage409Example:
                  summary: Default uploadListingImage 409 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:
                UploadListingImage403Example:
                  summary: Default uploadListingImage 403 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:
                UploadListingImage401Example:
                  summary: Default uploadListingImage 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:
                UploadListingImage500Example:
                  summary: Default uploadListingImage 500 response
                  x-microcks-default: true
                  value:
                    error: example string
      security:
      - api_key: []
        oauth2:
        - listings_w
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      summary: Etsy Upload Listing Image
components:
  schemas:
    ErrorSchema:
      type: object
      x-resource-id: ErrorSchema
      required:
      - error
      properties:
        error:
          type: string
          example: example string
    ListingImage:
      type: object
      x-resource-id: ListingImage
      description: Reference urls and metadata for an image associated with a specific listing. The `url_fullxfull` parameter contains the URL for full-sized binary image file.
      properties:
        listing_id:
          type: integer
          description: The numeric ID for the [listing](/documentation/reference#tag/ShopListing) associated to this transaction.
          format: int64
          minimum: 1
          example: 123456789
        listing_image_id:
          type: integer
          description: The numeric ID of the primary [listing image](/documentation/reference#tag/ShopListing-Image) for this transaction.
          format: int64
          minimum: 1
          example: 1
        hex_code:
          type: string
          description: The webhex string for the image's average color, in webhex notation.
          nullable: true
          example: example string
        red:
          type: integer
          description: The numeric red value equal to the image's average red value, from 0-255 (RGB color).
          nullable: true
          minimum: 0
          example: 1
        green:
          type: integer
          description: The numeric red value equal to the image's average red value, from 0-255 (RGB color).
          nullable: true
          minimum: 0
          example: 1
        blue:
          type: integer
          description: The numeric red value equal to the image's average red value, from 0-255 (RGB color).
          nullable: true
          minimum: 0
          example: 1
        hue:
          type: integer
          description: The numeric hue equal to the image's average hue, from 0-360 (HSV color).
          nullable: true
          minimum: 0
          example: 1
        saturation:
          type: integer
          description: The numeric saturation equal to the image's average saturation, from 0-100 (HSV color).
          nullable: true
          minimum: 0
          example: 1
        brightness:
          type: integer
          description: The numeric brightness equal to the image's average brightness, from 0-100 (HSV color).
          nullable: true
          minimum: 0
          example: 1
        is_black_and_white:
          type: boolean
          description: When true, the image is in black & white.
          nullable: true
          example: true
        creation_tsz:
          type: integer
          description: The listing image's creation time, in epoch seconds.
          minimum: 0
          example: 1
        created_timestamp:
          type: integer
          description: The listing image's creation time, in epoch seconds.
          minimum: 0
          example: 1758153645
        rank:
          type: integer
          description: The positive non-zero numeric position in the images displayed in a listing, with rank 1 images appearing in the left-most position in a listing.
          minimum: 0
          example: 1
        url_75x75:
          type: string
          description: The url string for a 75x75 pixel thumbnail of the image.
          example: https://www.etsy.com/listing/123456789
        url_170x135:
          type: string
          description: The url string for a 170x135 pixel thumbnail of the image.
          example: https://www.etsy.com/listing/123456789
        url_570xN:
          type: string
          description: The url string for a thumbnail of the image, no more than 570 pixels wide with variable height.
          example: https://www.etsy.com/listing/123456789
        url_fullxfull:
          type: string
          description: The url string for the full-size image, up to 3000 pixels in each dimension.
          example: https://www.etsy.com/listing/123456789
        full_height:
          type: integer
          description: The numeric height, measured in pixels, of the full-sized image referenced in url_fullxfull.
          nullable: true
          minimum: 0
          example: 1
        full_width:
          type: integer
          description: The numeric width, measured in pixels, of the full-sized image referenced in url_fullxfull.
          nullable: true
          minimum: 0
          example: 1
        alt_text:
          type: string
          description: Alt text for the listing image. Max length 500 characters.
          nullable: true
          example: example string
    ListingImages:
      type: object
      x-resource-id: ListingImages
      description: Represents a list of listing image resources, each of which contains the reference URLs and metadata for an image.
      properties:
        count:
          type: integer
          description: The number of results.
          minimum: 0
          example: 1
        results:
          type: array
          description: The list of requested resources.
          items:
            description: The list of requested resources.
            oneOf:
            - $ref: '#/components/schemas/ListingImage'
  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