openapi: 3.1.0
info:
  title: Shopify Admin REST About Product Images API
  description: The Shopify Admin REST API lets you build apps and integrations that extend and enhance the Shopify admin. Access products, customers, orders, inventory, fulfillment, and more. Endpoints are organized by resource type and versioned by release date.
  version: 2025-01
  contact:
    name: Shopify
    url: https://shopify.dev/docs/api/admin-rest
    email: api@shopify.com
  license:
    name: Shopify API Terms
    url: https://www.shopify.com/legal/api-terms
  x-date: '2026-03-04'
servers:
- url: https://{store}.myshopify.com/admin/api/2025-01
  description: Shopify Admin REST API
  variables:
    store:
      default: my-store
      description: The Shopify store subdomain
security:
- AccessToken: []
tags:
- name: Product Images
  description: Manage images associated with products
paths:
  /products/{product_id}/images.json:
    get:
      operationId: listProductImages
      summary: Shopify Retrieve a list of product images
      description: Retrieves all images for a given product.
      tags:
      - Product Images
      parameters:
      - $ref: '#/components/parameters/ProductId'
      - name: since_id
        in: query
        description: Return images after the specified ID
        schema:
          type: integer
      - name: fields
        in: query
        description: Comma-separated list of fields to include
        schema:
          type: string
      responses:
        '200':
          description: A list of product images
          content:
            application/json:
              schema:
                type: object
                properties:
                  images:
                    type: array
                    items:
                      $ref: '#/components/schemas/Image'
    post:
      operationId: createProductImage
      summary: Shopify Create a product image
      description: Creates a new image for a product. Images can be provided as a URL or a base64-encoded attachment.
      tags:
      - Product Images
      parameters:
      - $ref: '#/components/parameters/ProductId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - image
              properties:
                image:
                  $ref: '#/components/schemas/ImageInput'
      responses:
        '201':
          description: The created image
          content:
            application/json:
              schema:
                type: object
                properties:
                  image:
                    $ref: '#/components/schemas/Image'
  /products/{product_id}/images/count.json:
    get:
      operationId: getProductImageCount
      summary: Shopify Retrieve a count of product images
      description: Retrieves a count of images for a given product.
      tags:
      - Product Images
      parameters:
      - $ref: '#/components/parameters/ProductId'
      responses:
        '200':
          description: The image count
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
  /products/{product_id}/images/{image_id}.json:
    get:
      operationId: getProductImage
      summary: Shopify Retrieve a single product image
      description: Retrieves a single image for a product by its ID.
      tags:
      - Product Images
      parameters:
      - $ref: '#/components/parameters/ProductId'
      - $ref: '#/components/parameters/ImageId'
      responses:
        '200':
          description: The requested image
          content:
            application/json:
              schema:
                type: object
                properties:
                  image:
                    $ref: '#/components/schemas/Image'
    put:
      operationId: updateProductImage
      summary: Shopify Update a product image
      description: Updates an existing product image. Can update position, alt text, and variant associations.
      tags:
      - Product Images
      parameters:
      - $ref: '#/components/parameters/ProductId'
      - $ref: '#/components/parameters/ImageId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - image
              properties:
                image:
                  $ref: '#/components/schemas/ImageInput'
      responses:
        '200':
          description: The updated image
          content:
            application/json:
              schema:
                type: object
                properties:
                  image:
                    $ref: '#/components/schemas/Image'
    delete:
      operationId: deleteProductImage
      summary: Shopify Delete a product image
      description: Deletes an image from a product.
      tags:
      - Product Images
      parameters:
      - $ref: '#/components/parameters/ProductId'
      - $ref: '#/components/parameters/ImageId'
      responses:
        '200':
          description: Image deleted successfully
components:
  parameters:
    ImageId:
      name: image_id
      in: path
      required: true
      description: The ID of the image
      schema:
        type: integer
    ProductId:
      name: product_id
      in: path
      required: true
      description: The ID of the product
      schema:
        type: integer
  schemas:
    ImageInput:
      type: object
      description: Input for creating or updating a product image
      properties:
        src:
          type: string
          format: uri
          description: URL of the image
        attachment:
          type: string
          description: Base64-encoded image data
        alt:
          type: string
          description: Alt text
        position:
          type: integer
        variant_ids:
          type: array
          items:
            type: integer
    Image:
      type: object
      description: A product image
      properties:
        id:
          type: integer
        product_id:
          type: integer
        position:
          type: integer
          description: Position in the image list
        alt:
          type:
          - string
          - 'null'
          description: Alt text for the image
        width:
          type: integer
        height:
          type: integer
        src:
          type: string
          format: uri
          description: The image URL
        variant_ids:
          type: array
          description: Variant IDs associated with this image
          items:
            type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        admin_graphql_api_id:
          type: string
  securitySchemes:
    AccessToken:
      type: apiKey
      name: X-Shopify-Access-Token
      in: header
      description: Access token obtained via OAuth